eu-parliament-mcp-server

---

概要

Open Data API を通じて、欧州議会の記録を利用できます。立法手続きを見つけてその根拠資料を追跡し、MEP を検索し、本会議の決定や投票者を調べ、文書、演説、質問のメタデータを取得できます。stdio プロセス、またはローカルの Streamable HTTP サーバーとして動作します。API キーは不要です。

ツール

ツール	説明
euparl_list_reference	フィルターコード、識別子の形式、対象範囲、委員会、会派を確認します
euparl_list_procedures	種類別に手続きの参照情報を一覧表示します
euparl_get_procedure	手続きの識別情報、段階、イベント、参加者、文書の参照情報を読み取ります
euparl_search_documents	採択文書を検索し、委員会・本会議の文書を一覧表示するか、正式な文書を取得します
euparl_search_speeches	第10期の演説活動を検索し、メタデータと録音文書へのリンクを取得します
euparl_search_meps	現職または指定した任期の全名簿から MEP を検索します
euparl_get_mep	議員の識別情報と公開されている在籍履歴を読み取ります
euparl_get_plenary_votes	会議を見つけ、決定を調べ、記録された投票者または投票予定者をページ単位で取得します
euparl_list_questions	年・種類別に質問を一覧表示するか、質問と回答の参照情報を取得します

機能リファレンス

すべてのリストツールは、offset（既定値 0）、limit（既定値 20、指定可能な値は 1～1000、実効上限は通知付きで 100）、および language（既定値 en、24 の EU 言語コードのいずれか）を受け付けます。page.next_offset に従ってください。ローカルコレクションでは、返された page.snapshot も渡してください。snapshot_changed エラーが発生した場合は、スナップショットを指定せずにオフセット 0 からやり直してください。ローカルスナップショットは新たに検索したときに変更を検出しますが、過去のデータは保持しません。

ローカライズされたテキストには実際のソース言語が含まれます。フォールバックが発生した場合はその旨が通知され、テキストが翻訳されることはありません。通常、詳細が見つからない場合は found: false が返され、空のリストはガイダンスとともに正常に返されます。詳細な決定情報の検索では、代わりに decision_not_found が返されます。

euparl_list_reference _ツール

• 必須の topic：committees、political_groups、procedure_types、document_types、question_types、activity_types、mep_filters、identifiers、または coverage
• 委員会と政治グループは、現在活動している組織です。組織識別子が、受け付けられるフィルターコードであることを意味するわけではありません。リファレンスページではスナップショットは不要です

---

euparl_list_procedures _ツール

• 任意の process_type は euparl_list_reference の値を指定します。キーワード、年、委員会、段階のフィルターはありません
• 情報が限られた行には procedure_id、ソース URL、利用可能なリファレンス／タイプが含まれます。タイトル、段階、参加者を取得するには euparl_get_procedure を使用してください

---

euparl_get_procedure _ツール

• 必須の procedure_id は、YYYY-NNNN、YYYY/NNNN(TYPE)、任意の文字サフィックス、既知のパスプレフィックス、または完全一致する公開手続き URI を受け付けます
• section: "overview" はスカラー形式のメタデータとコレクション件数を返します。events、participants、documents は、スナップショットを使って各コレクションの 1 ページを取得します
• 過去の参加者グループは過去のものとして保持されます。ドキュメント ID を使って、get モードの euparl_search_documents を呼び出してください

---

euparl_search_documents _ツール

• mode: "search" の既定値は source: "adopted_texts" です。このソースのみが text、title、会期日付、related_process_id を受け付けます。採択文書では年と会期を指定でき、委員会文書では会期、本会議文書では年を指定できます
• work_type には、euparl_list_reference にあるソースファミリー固有のコードを使用します。委員会／本会議の検索にはキーワードフィルターがありません
• mode: "get" では document_id が必須で、ソース、検索フィルター、既定値以外のページ指定は受け付けません。手続き、演説、投票、質問、回答の ID はすべて同じ検索で取得できます
• 詳細には、メタデータ、手続き／親文書への参照、および選択した言語で利用できるすべてのソースファイルへのリンクが含まれます。分割文書にファイルがない場合は parent_document_ids をたどってください。文書本文のダウンロードや抽出は行われません

---

euparl_search_speeches _ツール

• text、title、person_id、activity_type、または会期日付の範囲で検索します。対象は欧州議会第 10 期に限られます
• mode: "get" では speech_id が必須で、検索フィルターと既定値以外のページ指定は受け付けません
• 発言録ではなく、活動のメタデータと参加者を返します。document_ids をたどってドキュメントを取得し、ソースファイルへの親参照も確認してください

---

euparl_search_meps _ツール

• term を省略すると、現在在職中の議員が選択されます。term を明示すると、第 0 期から第 10 期までの公開名簿が選択されます。任意の国、政治グループ、性別コードは mep_filters で確認できます
• name_contains は、ページ分割の前に名簿全体から正規化されたすべてのトークンを照合します。大文字小文字、ダイアクリティカルマーク、句読点は無視されます
• 結果のページ継続にはスナップショットを使用します。国／グループは、選択した名簿の情報であり、投票日時点の所属を示すものではありません

---

euparl_get_mep _ツール

• mep_id は、10 進数の人物 ID、person/ プレフィックス、または完全一致する公開人物 URI を受け付けます
• 既定の section: "overview" は、本人情報と membership_count を返します。section: "memberships" は、スナップショットを使用して公開済みの履歴をページ単位で取得します
• 所属終了日がない場合でも、現在の所属を示すことにはなりません

---

euparl_get_plenary_votes _ツール

• mode: "sittings" では year が必要です。デフォルトの decisions では sitting_id が必要で、簡潔な要約をページ分割して返します。会議 ID には、実在する YYYY-MM-DD 日付、MTG-PL- 形式、既知のイベント接頭辞、または公開 URI を指定できます
• mode: "decision" では会議 ID と決定 ID が必要です。ラベル全文、解説、文書参照を含む詳細なレコードを 1 件返します。ページ分割とスナップショットは受け付けません
• mode: "voters" では、さらに position が必要です。指定できる値は favor、against、abstention、intended_favor、intended_against、intended_abstention です。決定と投票者の立場は、それぞれ独立してページ分割され、スナップショットが適用されます
• resolve_names: true は voters でのみ指定でき、roster_term（0～10）が必要です。解決できない ID は出力に残ります。氏名は公開済みの対象会期の名簿から取得し、投票日時点の所属情報は含まれません
• 公開済みの集計値は投票者配列の件数とは別に保持されます。available: false は配列が存在しないことを示し、公開済みの空配列では available: true になります。訂正予定は記録された投票を置き換えません

---

euparl_list_questions _ツール

• デフォルトの mode: "list" では year と work_type を指定できます。キーワード、著者、宛先による検索には対応していません
• mode: "get" では question_id が必要です。正規の文書 ID、既知の文書接頭辞／公開 URI、または E-000001/2025 のような人間が読める引用形式（P/O 接頭辞も可）を指定できます。省略可能な term を指定すると引用を直接解決します。省略した場合は引用に含まれる年全体を検索し、完全一致が 1 件必要です
• Get では、一覧用フィルターとデフォルト以外のページ分割設定は受け付けません。詳細にはメタデータ、ソースファイル、公開済みの回答参照が含まれます。answers が空でも、質問が未回答であるとは限りません

機能

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

欧州議会固有の機能：

• 議会の公開 JSON-LD レコードにキーなしでアクセスでき、正規識別子によって検索、詳細、ソース証拠を相互に関連付けます
• 共通のリクエスト間隔制御、上限付き再試行、取得とキュー待ちの両方を含む 40 秒の操作期限
• 全名簿を対象とした氏名フィルタリングと、手続きの証拠、議員履歴、決定の要約、投票者の個別ページ分割

エージェント向けの出力：

• ソース URL、実際の言語ラベル、正規化されたフィルター、取得可能な場合は正確な合計数、続行方法の案内
• 欠損フィールドには不確実性を保持し、公開済みのゼロ値、存在しない配列、過去の所属情報を区別します
• content[] と structuredContent に一致するデータを含め、利用可能なソースリンクと型付きのエラー理由を提供します

データソース：European Parliament Open Data。ライセンスは CC BY 4.0 です。このサーバーは識別子とレコード構造を正規化します。議会の記録は、制定法の網羅性や議員の生涯にわたる投票履歴を証明するものではありません。

はじめに

セルフホスト／ローカル

MCP クライアントの設定ファイルに以下を追加してください。

{
  "mcpServers": {
    "eu-parliament-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/eu-parliament-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

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

{
  "mcpServers": {
    "eu-parliament-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/eu-parliament-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または Docker を使用する場合：

{
  "mcpServers": {
    "eu-parliament-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/eu-parliament-mcp-server:latest"]
    }
  }
}

Streamable HTTP の場合は、トランスポートを設定してサーバーを起動してください：

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

前提条件

• Bun v1.4.0 以降（または Node.js v24 以降）。
• API キーや上流サービスのアカウントは不要です。

インストール

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

git clone https://github.com/cyanheads/eu-parliament-mcp-server.git

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

cd eu-parliament-mcp-server

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

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env to override framework settings as needed

設定

変数	説明	デフォルト
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_HOST	HTTP のリッスンホスト。	127.0.0.1
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_SESSION_MODE	HTTP セッションモード：stateless、stateful、または auto。	stateless
MCP_AUTH_MODE	認証：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（debug、info、warning、error など）。	info
LOGS_DIR	ログファイル用ディレクトリ（Node.js のみ）。	<app-root>/logs
STORAGE_PROVIDER_TYPE	ストレージバックエンド：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	OpenTelemetry を有効にします。	false

サーバー固有の環境変数は必要ありません。共通のフレームワーク設定の上書きについては、.env.example を参照してください。

サーバーの実行

ローカル開発

• 本番用バージョンをビルドして実行する：

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

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

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

プロジェクト構成

ディレクトリ	目的
src/mcp-server/tools/definitions	9 個の読み取り専用ツール定義（*.tool.ts）。
src/mcp-server/tools/utils	共通スキーマ、情報を損なわないレンダリング、拡充処理。
src/services/eu-parliament	JSON-LD クライアント、エッジスキーマ、参照コード、正規化、ドメインワークフロー。
tests/	src/ の構成を反映したユニットテストと統合テスト。
docs/	設計契約と生成されたプロジェクトツリー。

開発ガイド

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

• ハンドラーは例外をスローし、フレームワークがキャッチします — ツールのロジックで try/catch を使わないでください
• ログには ctx.log を、ストレージには ctx.state を使用します
• src/index.ts の createApp() 配列に新しいツールとリソースを登録します
• 外部 API 呼び出しはラップします：生データを検証 → ドメイン型に正規化 → 出力スキーマを返す。欠落しているフィールドを作り出してはいけません

コントリビューション

イシューを歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

このプロジェクトは Apache 2.0 ライセンスの下でライセンスされています。詳細は LICENSE ファイルを参照してください。