fbi-crime-mcp-server

---

概要

FBI Crime Data Explorer の米国犯罪統計を提供します。人口と報告状況を含む月次の犯罪発生率と件数、国・州・機関レベルのヘイトクライム、逮捕、NIBRS の合計、州別の機関 ORI 検索、職務中に死亡または襲撃された法執行官の統計（LEOKA）を利用できます。

ツール

ツール	説明
fbi_search_agencies	州内の機関と、その ORI コードを CDE 機関ディレクトリから検索します。名前の語句、郡、機関種別で絞り込み可能で、ページ分割に対応しています
fbi_get_crime_estimates	CDE の集計エンドポイントから、全国、州、または機関の範囲で、月次の UCR 犯罪率と件数を取得します。州および全国との比較率も任意で取得できます
fbi_get_hate_crimes	1991年から現年までの、偏見の動機とカテゴリ別のヘイトクライム事件、および犯罪、場所、加害者、司法地区別の内訳
fbi_get_arrests	1985年から現年までの、犯罪、逮捕者の性別と人種、年齢層別の逮捕件数
fbi_get_nibrs_breakdown	1991年から現年までの、1種類の犯罪に関する NIBRS 被害者、加害者、武器、関連犯罪の内訳
fbi_get_leoka	2020年から現年までの、月次または年初来の警察官死亡、武器、状況のデータ（LEOKA）
fbi_get_arson	[無効] offense="arson" を指定して fbi_get_crime_estimates を使用してください
fbi_get_agency	[無効] UCR 機関プロフィールのバックエンドは廃止されました。fbi_search_agencies を使用してください
fbi_get_human_trafficking	[無効] UCR の人身取引バックエンドは廃止されました
fbi_get_participation	[無効] UCR および CDE の参加状況バックエンドは廃止されました
fbi_list_code_table	[無効] UCR コードテーブルのバックエンドは廃止されました

上記の利用できない5項目は、呼び出し可能なツールではなく、無効化されたオペレーター記録です。廃止されたデータセットについては、FBI CDEをご覧ください。

機能リファレンス

fbi_search_agencies _ツール

• state_abbr（必須、2文字、大文字と小文字を区別しません）で州のディレクトリを選択します。任意のフィルターは州全体を対象に適用されます。name_contains（すべての語句が、順不同かつ大文字と小文字を区別せずに機関名に含まれている必要があります）、county（機関の郡のいずれかと、大文字と小文字を区別せずに一致）、agency_type（City、County、Other State Agency、Other、State Police、University or College、Tribal）を指定できます。
• limit（1～200、既定値は50）とoffset（既定値は0）で一致項目をページ分割します。機関名、次に ORI の順で並べ替えられます。
• state_abbr、total（ページ分割前の一致件数）、offset、next_offset（最終ページでは省略）、および CDE に登録されている場合はori、agency_name、agency_type、counties、is_nibrs、nibrs_start_dateを含むagencies[]を返します。
• CDE にディレクトリがないコード（AS、MP、または認識されないコード）を指定すると、通知とともに機関数0件を返します。末尾を超えるoffsetを指定すると、合計件数を示す通知とともに機関数0件を返します。

---

fbi_get_crime_estimates _ツール

• scope：national（識別子なし）、state（state_abbr のみ。2 文字）、または agency（ori のみ。英字または数字 9 文字。fbi_search_agencies で検索してください）。大文字と小文字は区別せず、大文字に正規化されます。
• offense：violent-crime、property-crime、robbery、burglary、larceny、motor-vehicle-theft、arson、aggravated-assault、rape、または homicide。期間は from_year／from_month から to_year／to_month までです（1985 年から現在の年まで。月のデフォルトはそれぞれ 1 月と 12 月）。開始日時は終了日時より後にできません。現在の UTC 年より後の年を指定すると year_out_of_range が返されます。現在の年のうち、最新データより後の月は null 値を返します。
• 各犯罪の月について、entity_name、参加人口 10 万人あたりの率、実際の件数と検挙件数、および null になり得る population、participated_population、population_coverage_percent を返します。プロバイダーが提供する場合は、data_last_updated と max_data_date も返します。
• include_comparisons（デフォルトは false。state または agency スコープのみ）を指定すると、comparisons が追加されます。CDE の順序で比較対象エンティティごとに 1 件ずつ返されます（警察機関の場合はその州、次に米国全体。州の場合は米国全体）。各項目は { entity_name, months[] } で、対象範囲と完全に同じ月について year、month、rate_per_100k、clearance_rate_per_100k、population、participated_population、population_coverage_percent を含みます。CDE は比較対象エンティティの件数を送信せず、CDE から何も送信されない場合、リストは空になります。
• 型付きエラー：scope_param_missing、scope_param_incompatible（国全体のスコープで include_comparisons: true を指定した場合も含む）、year_out_of_range、invalid_date_range、no_data（形式が正しい識別子でも、プロバイダーが認識しない場合に返されます）。

---

fbi_get_hate_crimes _ツール

• scope、state_abbr、ori、および from_year／from_month／to_year／to_month の期間は、年の範囲が 1991 年から現在の年までである点を除き、fbi_get_crime_estimates の仕様に従います。件数は期間内で合算されます。
• bias：all（デフォルト）、または 34 種類の CDE バイアスコード（11～85。フィールドに記載）から 1 つ。コードを指定すると、その動機に該当する事件と、複数のバイアスが含まれる事件のうちそのコードに該当する事件が集計されます。
• incident_section（bias、bias_category）と bias_section（offense_type、location_type、offender_race、offender_ethnicity、judicial_district）を、カテゴリと件数のマップとして返します。CDE が送信するすべてのカテゴリが含まれ、ゼロと null も保持されます。bias_section の各次元は異なる基準で集計されるため、合計は全体の件数や事件数と一致しません。提供される場合は、bias_label と data_last_updated も返します。
• CDE は報告がない場合も、州または ORI が認識されない場合もゼロを返すため、すべての値がゼロの結果は notice とともに成功します。
• 型付きエラー：scope_param_missing、scope_param_incompatible、year_out_of_range、invalid_date_range。

---

fbi_get_arrests _ツール

• スコープ、識別子、期間は fbi_get_hate_crimes と同じです。年の範囲は 1985 年から現在の年までです。
• offense：all（デフォルト）、または 46 種類の CDE 数値犯罪コードから 1 つ（例：30 Robbery、11 Murder and Nonnegligent Homicide。フィールドに記載）。robbery のような単語のスラッグは受け付けません。コード 23（Rape - Not Specified）は、CDE がゼロのみを返すため除外されています。
• offense_name、offense_category、offense_breakdown、arrestee_sex、arrestee_race、male_arrests_by_age、female_arrests_by_age をカテゴリと件数のマップとして返します。提供される場合は、offense_label、data_last_updated、max_data_date も返します。各グループは個別に集計されるため、合計は一致しません。
• fbi_get_hate_crimes と同じ、すべての値がゼロの場合の notice と型付きエラーを返します。

---

fbi_get_nibrs_breakdown _ツール

• fbi_get_hate_crimes と同じ範囲、識別子、期間を使用し、対象年は1991年から現在の年までです。
• offense（必須、大文字・小文字を区別しません）：CDE の NIBRS 犯罪コード71種類のいずれかです（例：13A 加重暴行、120 強盗。コードはフィールドに記載されています）。all はなく、CDE がすべて null を返すため、23*（未指定）は除外されます。
• victim（age、sex、race、location、ethnicity、relationship）、offender（age、sex、race、ethnicity）、offense_details（weapons、related_offenses）を、カテゴリーと件数のマップとして返します。CDE が送信するすべてのカテゴリーが含まれ、ゼロと null も保持されます。また、提供されている場合は offense_label、data_last_updated、max_data_date も返します。各ディメンションは個別に集計され、合計件数が一致するとは限りません。
• 型付きエラー：scope_param_missing、scope_param_incompatible、year_out_of_range、invalid_date_range、no_data（CDE にいずれのカテゴリーの値もない場合です。認識されない州または ORI、対象期間に NIBRS データがない場合、または対象期間中に報告された事案がない犯罪が該当します。機関については、fbi_search_agencies で is_nibrs と nibrs_start_date を確認できます）。

---

fbi_get_leoka _ツール

• period：ytd（年初来。month は省略）または monthly（month が必須。1～12）。year は必須です（2020年から現在の年まで。それ以降の年を指定すると year_out_of_range が発生します）。
• totals には、CDE の年初来ブロックから取得した total_officers、total_incidents、total_officers_dod、total_officers_doi、total_incidents_dod、total_incidents_doi が含まれます。両方の期間で表示されますが、指定した月の合計ではありません。上流では dod／doi が定義されていません。削除された total_*_felonious および total_*_accidental フィールドと同じ値で置き換えられています。
• カテゴリーと件数のマップ：weapons、officer_activity、lighting_conditions、body_armor_worn、location_of_attack、offender_previously_known_to_agency、offender_prior_mental_illness、offender_prior_relationship、officer_circumstances_time_of_attack、officer_incident_type、officer_type_of_assignment、weather_conditions、offender_demographic、officer_demographic、officer_death_by_time_of_day、officer_death_by_month。
• deaths_by_region と任意の deaths_by_year には、Felonious／Accidental などの殺害の種類ごとの内訳が含まれます。月次レスポンスでは年間の時系列データは省略されます。deaths_by_year は CDE が返す期間を対象とし、指定年以降の年が含まれる場合があります。また、現在の年の値は年初来のものです。存在しないセクションは省略され、件数が null の場合は利用できないことを示し、ゼロはゼロのまま保持されます。
• officer_death_by_month では、CDE が対象とする月のみが保持されます。そのため、補完されたゼロが件数として読み取られることはありません。月次レスポンスでは各年に指定月のみが含まれ、現在の年の年初来レスポンスでは現在の UTC 月までの月が含まれます。過去年の年初来レスポンスでは、返された時系列データがそのまま保持されます。
• 型付きエラー：month_required（月次期間で month が未指定）、month_not_applicable（年初来で month が指定されている）、year_out_of_range、no_data

---

特徴

@cyanheads/mcp-ts-core を基盤としており、stdio および Streamable HTTP トランスポート、プラグイン可能な認証（none / jwt / oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレーシングを備えた構造化ログに対応しています。

FBI CDE 固有の機能：

• CDE 要約エンドポイント（/cde/summarized/）では、10 種類の犯罪について、全国、州、各機関の犯罪率と件数を取得できます。州および全国との比較率も任意で取得できます。
• CDE 機関ディレクトリ（/cde/agency/byStateAbbr/）では、州、名称、郡、機関の種類で ORI を検索できます。
• CDE のヘイトクライム（/cde/hate-crime/）、逮捕（/cde/arrest/）、NIBRS（/cde/nibrs/）の合計を、全国、州、機関の範囲で取得できます。NIBRS は71種類の犯罪コードに対応しています。
• CDE LEOKA エンドポイント（/cde/leoka/）では、月別または年初からの警察官の死亡、武器、状況に関するデータを取得できます。
• 登録不要で DEMO_KEY を利用できます（共有のレート制限付きプール）。登録済みの api.data.gov キーを使うと、スループットが向上します。
• 廃止された5つのツールは、HTTP ランディングページに無効化の理由が表示されます。MCP クライアントに公開されるのは、呼び出し可能な6つのツールのみで、リソースはありません。

エージェントに適した出力：

• 型付きのエラー理由に、範囲、日付や期間の修正、データが利用できない場合の対処方法が含まれています。
• 上流のデータに率、検挙数、件数、人口、対象範囲が存在しない場合、架空のゼロではなく null を返します。
• data_last_updated と max_data_date には、CDE 自身の日付が反映されます。

はじめに

公開ホストインスタンス

https://fbi-crime.caseyjhand.com/mcp で公開インスタンスを利用できます。インストールは不要です。API キーも必要ありません。インスタンスが独自のキーを使用します。Streamable HTTP 経由で、任意の MCP クライアントを接続してください。

{
  "mcpServers": {
    "fbi-crime-mcp-server": {
      "type": "streamable-http",
      "url": "https://fbi-crime.caseyjhand.com/mcp"
    }
  }
}

セルフホスト／ローカル環境

以下を MCP クライアントの設定ファイルに追加してください。キーを取得するには、FBI CDE API キーの登録を参照してください。探索には DEMO_KEY を利用できますが、レート制限があります。

{
  "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"
      }
    }
  }
}

または、npx を使用する場合（Bun は不要です）：

{
  "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"
      }
    }
  }
}

または、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"
      ]
    }
  }
}

Streamable HTTP を使用する場合は、トランスポートを設定してサーバーを起動してください。

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

前提条件

• Bun v1.4.0 以降（または Node.js v24 以降）。
• FBI CDE API 用の api.data.gov API キー。テストには DEMO_KEY を利用できますが、共有プールからのリクエストは約1,000件／時に制限されています。

インストール

1. リポジトリをクローンします：

git clone https://github.com/cyanheads/fbi-crime-mcp-server.git

2. ディレクトリに移動します：

cd fbi-crime-mcp-server

3. 依存関係をインストールします：

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env and set FBI_API_KEY

設定

すべての設定は、src/config/server-config.ts の Zod スキーマを使って起動時に検証されます。主な環境変数は次のとおりです。

変数	説明	デフォルト
FBI_API_KEY	必須。 FBI CDE API 用の api.data.gov API キーです。制限付きのテストには DEMO_KEY を使用してください。	—
FBI_API_BASE_UCR	UCR ベース URL を上書きします。	https://api.usa.gov/crime/fbi/ucr
FBI_API_BASE_CDE	CDE ベース URL を上書きします。	https://api.usa.gov/crime/fbi/cde
FBI_REQUEST_TIMEOUT_MS	リクエストごとのタイムアウト（ミリ秒）です。	15000
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_HTTP_ENDPOINT_PATH	HTTP エンドポイントのパスです。	/mcp
MCP_SESSION_MODE	HTTP セッションモード：stateless、stateful、または auto（stateful に解決されます）。サーバーはコード内で stateless を宣言しています。上書きするには、この値を設定してください。	stateless
MCP_PUBLIC_URL	TLS 終端リバースプロキシ環境で使用するパブリックオリジンの上書き値です。	なし
MCP_AUTH_MODE	認証モード：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（RFC 5424）です。	info
MCP_GC_PRESSURE_INTERVAL_MS	Bun 専用の強制 GC 圧力間隔（ms）のオプトイン設定です。HTTP 負荷が継続しているときに RSS が増加する場合は、60000 を試してください。	0
LOGS_DIR	ログファイルのディレクトリ（Node.js のみ）です。	<project-root>/logs
STORAGE_PROVIDER_TYPE	ストレージバックエンド：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	OpenTelemetry 計装を有効にします。	false
OTEL_EXPORTER_OTLP_ENDPOINT	トレースとメトリクスのエクスポートに使用する OTLP ベース URL です。ログのエクスポートは有効になりません。	なし
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	OTLP ログエクスポートの明示的なエンドポイントです。Docker イメージには必要なオプションのピア依存関係が含まれています。	なし

オプションの上書き設定の全一覧については、.env.example を参照してください。

サーバーの実行

ローカル開発

• ビルドして実行：

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

• チェックとテストを実行：

  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

Dockerfile のデフォルトは HTTP トランスポート、ステートレスセッションモードで、ログは /var/log/fbi-crime-mcp-server に出力されます。OpenTelemetry のピア依存関係はデフォルトでインストールされます。省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	用途
src/index.ts	エントリーポイントの createApp() です。ツール、リソース、サービスを登録します。
src/config	サーバー固有の環境変数の解析と、Zod による検証を行います。
src/mcp-server/tools	ツール定義（*.tool.ts）です。呼び出し可能なツールが 6 個、無効化されたオペレーターエントリーが 5 個あります。
src/mcp-server/resources	廃止された機関／州の定義です。登録されていません。
src/services	レスポンス検証と共通の再試行／タイムアウト処理を備えた FBI CDE API サービスです。
tests/	src/ に対応するユニットテストと統合テストです。

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックに try/catch を使わないでください
• リクエストスコープのログには ctx.log を、テナントスコープのストレージには ctx.state を使用してください
• 新しいツールとリソースは、src/index.ts で createApp() に渡す配列に登録してください
• 有効なツールは CDE API（/cde/summarized/、/cde/agency/byStateAbbr/、/cde/hate-crime/、/cde/arrest/、/cde/nibrs/、/cde/leoka/）を呼び出します。廃止された定義は disabledTool でラップされ、MCP 登録から除外されます
• FBI API の呼び出しは、未加工データの検証 → ドメイン型への正規化 → 出力スキーマの返却、の順に処理してください。不足しているフィールドを捏造しないでください

コントリビューション

課題の報告を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細については LICENSE を参照してください。