convez.ai
MCP Server
cyanheads

fbi-crime-mcp-server

cyanheads/fbi-crime-mcp-server

Ver no GitHub
InicialPluginScore · de 0 a 100

Exposes the FBI Crime Data Explorer API — UCR crime estimates, NIBRS incident breakdowns, hate crimes, arrests, human trafficking, and agency participation data via MCP. STDIO or Streamable HTTP.

Instalação

$npx convez-ai cyanheads/fbi-crime-mcp-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 4 dias
Versão
v0.5.0
Issues abertas
4
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

Version License Docker MCP SDK npm TypeScript Bun

Install in Claude Desktop Install in Cursor Install in VS Code

Framework


Tools

12 tools defined. 4 are active via the FBI CDE API; 8 are decommissioned — the legacy UCR backend (crime-data-api.fr.cloud.gov) was shut down, and those tools return a ServiceUnavailable error on every call with guidance to the FBI CDE website.

Active tools (CDE API)

ToolDescription
fbi_get_crime_estimatesMonthly offense rates (per 100k) and raw counts from the FBI CDE summarized endpoint. National, state, or agency scope. Covers violent-crime, property-crime, robbery, burglary, larceny, motor-vehicle-theft, arson, aggravated-assault, rape, homicide.
fbi_get_agency_offensesSame CDE summarized endpoint, scoped to a single agency by ORI code. Returns month-by-month rates and counts for that agency.
fbi_get_leokaLaw Enforcement Officers Killed and Assaulted (LEOKA) — fatality and assault counts with circumstance and weapon detail, by month or year-to-date.
fbi_get_arsonRedirects to fbi_get_crime_estimates with offense="arson" — arson data is available via the CDE summarized endpoint.

Decommissioned tools (always return error)

ToolStatus
fbi_search_agenciesUCR agency search backend decommissioned
fbi_get_agencyUCR agency lookup backend decommissioned
fbi_get_arrestsUCR arrests backend decommissioned
fbi_get_hate_crimesUCR hate crimes backend decommissioned
fbi_get_participationUCR participation backend decommissioned
fbi_get_human_traffickingUCR human trafficking backend decommissioned
fbi_get_nibrs_breakdownNIBRS backend decommissioned
fbi_list_code_tableUCR code table backend decommissioned

For decommissioned data, consult cde.ucr.cjis.gov or download FBI bulk CSV files.

fbi_get_crime_estimates

Monthly offense rates and raw counts from the FBI CDE summarized endpoint.

  • Scope: national, state (requires state_abbr), or agency (requires ORI)
  • Offense types: violent-crime, property-crime, robbery, burglary, larceny, motor-vehicle-theft, arson, aggravated-assault, rape, homicide
  • Returns per-100k rates and raw actuals by month for the requested date range

fbi_get_agency_offenses

Same CDE summarized endpoint scoped to a single agency, state, or national level.

  • Functionally equivalent to fbi_get_crime_estimates with scope="agency" — useful when the agent's mental model is "offenses for this agency" rather than "crime trends"
  • Provide ORI for agency scope; state_abbr for state scope

fbi_get_leoka

Law Enforcement Officers Killed and Assaulted (LEOKA) data.

  • Two period modes: monthly (by month) or ytd (year-to-date)
  • Returns feloniously killed, accidentally killed, and assault counts with circumstance and weapon detail

fbi_get_arson

Redirects to fbi_get_crime_estimates with offense="arson". The dedicated UCR arson endpoint is decommissioned; arson data remains available via the CDE summarized endpoint.

Resources

TypeNameDescription
Resourcefbi://agency/{ori}Agency profile from the CDE summarized endpoint — offense rates and counts for the agency's ORI.
Resourcefbi://state/{state_abbr}State crime overview — offense rates and counts from the CDE summarized endpoint.

Features

Built on @cyanheads/mcp-ts-core:

  • Declarative tool and resource definitions — single file per primitive, framework handles registration and validation
  • Unified error handling — handlers throw, framework catches, classifies, and formats
  • Pluggable auth: none, jwt, oauth
  • Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
  • Structured logging with optional OpenTelemetry tracing
  • STDIO and Streamable HTTP transports

FBI Crime Data Explorer-specific:

  • CDE API (/cde/summarized/, /cde/leoka/) — the surviving FBI endpoints post-UCR decommission
  • Decommissioned tools return a ServiceUnavailable error with a recovery hint pointing to cde.ucr.cjis.gov — agents can report the gap rather than silently failing
  • DEMO_KEY mode for no-config exploration; registered api.data.gov key for production throughput

Getting started

Add the following to your MCP client configuration file. See the FBI CDE API key registration to obtain a key — DEMO_KEY works for exploration but is rate-limited.

{
  "mcpServers": {
    "fbi-crime-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/fbi-crime-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "FBI_API_KEY": "your-api-key"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "fbi-crime-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/fbi-crime-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "FBI_API_KEY": "your-api-key"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "fbi-crime-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "FBI_API_KEY=your-api-key",
        "ghcr.io/cyanheads/fbi-crime-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 FBI_API_KEY=... bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

  • Bun v1.3.2 or higher (or Node.js v24+).
  • An api.data.gov API key for the FBI CDE API. DEMO_KEY works for testing but is rate-limited to ~1,000 req/hr from a shared pool.

Installation

  1. Clone the repository:
git clone https://github.com/cyanheads/fbi-crime-mcp-server.git
  1. Navigate into the directory:
cd fbi-crime-mcp-server
  1. Install dependencies:
bun install
  1. Configure environment:
cp .env.example .env
# edit .env and set FBI_API_KEY

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Key environment variables:

VariableDescriptionDefault
FBI_API_KEYRequired. api.data.gov API key for the FBI CDE API. Use DEMO_KEY for limited testing.—
FBI_API_BASE_UCROverride UCR base URL.https://api.usa.gov/crime/fbi/ucr
FBI_API_BASE_CDEOverride CDE base URL.https://api.usa.gov/crime/fbi/cde
FBI_REQUEST_TIMEOUT_MSPer-request timeout in milliseconds.15000
MCP_TRANSPORT_TYPETransport: stdio or http.stdio
MCP_HTTP_PORTPort for HTTP server.3010
MCP_HTTP_ENDPOINT_PATHHTTP endpoint path./mcp
MCP_PUBLIC_URLPublic origin override for TLS-terminating reverse-proxy deployments.none
MCP_AUTH_MODEAuth mode: none, jwt, or oauth.none
MCP_LOG_LEVELLog level (RFC 5424).info
MCP_GC_PRESSURE_INTERVAL_MSOpt-in Bun-only forced-GC pressure interval (ms). Try 60000 if RSS grows under sustained HTTP load.0
LOGS_DIRDirectory for log files (Node.js only).<project-root>/logs
STORAGE_PROVIDER_TYPEStorage backend: in-memory, filesystem, supabase, cloudflare-kv/r2/d1.in-memory
OTEL_ENABLEDEnable OpenTelemetry instrumentation.false

See .env.example for the full list of optional overrides.

Running the server

Local development

  • Build and run:

    # One-time build
    bun run rebuild
    
    # Run the built server
    bun run start:stdio
    # or
    bun run start:http
    
  • Run checks and tests:

    bun run devcheck   # Lint, format, typecheck, security
    bun run test       # Vitest test suite
    bun run lint:mcp   # Validate MCP definitions against spec
    

Docker

docker build -t fbi-crime-mcp-server .
docker run --rm -e FBI_API_KEY=your-key -p 3010:3010 fbi-crime-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/fbi-crime-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

DirectoryPurpose
src/index.tscreateApp() entry point — registers tools, resources, and inits services.
src/configServer-specific environment variable parsing and validation with Zod.
src/mcp-server/toolsTool definitions (*.tool.ts). 12 tools — 4 active via CDE API, 8 decommissioned.
src/mcp-server/resourcesResource definitions (*.resource.ts). Agency and state overview resources.
src/servicesFBI API service layer — UCR and CDE clients with shared retry/timeout logic.
tests/Unit and integration tests mirroring src/.

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

  • Handlers throw, framework catches — no try/catch in tool logic
  • Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
  • Register new tools and resources via the barrels in src/mcp-server/*/definitions/index.ts
  • Active tools call the CDE API (/cde/summarized/, /cde/leoka/); decommissioned tools throw serviceUnavailable with a recovery hint
  • Wrap FBI API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.

Ver o original no GitHub

Bom para

Relacionados