Parliament MCP

🚀 議會MCP服務器

議會MCP服務器大致映射到https://developer.parliament.uk/ 的一個子集，同時還提供額外的語義搜索功能。

🚀 快速開始

本地Elasticsearch環境

你需要準備以下環境：

• Docker和Docker Compose
• Node.js（用於mcp-remote）
• Claude桌面版（或其他MCP客戶端）
• 具備API訪問權限的Azure OpenAI賬戶

在項目根目錄下，複製.env.example文件並創建.env文件，然後替換其中必要的變量。

配置好.env文件後，運行以下命令，一次性完成MCP服務器和Elasticsearch數據庫的設置，並加載2025年6月的一些示例數據：

make dev_setup_from_scratch

運行上述命令後，你可以使用以下配置連接到MCP服務器：

# 將此配置添加到你的Claude桌面版配置文件中，或其他MCP客戶端配置文件中：
# 在macOS系統中，Claude桌面版配置文件位於`~/Library/Application\ Support/Claude/claude_desktop_config.json`
{
  "mcpServers": {
    "parliament-mcp": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8080/mcp/", "--allow-http", "--debug"]
    }
  }
}

✨ 主要特性

可用的MCP工具

MCP服務器提供了11種工具，可輔助議會研究工作：

1. search_constituency - 按名稱搜索選區，或通過ID獲取選區的詳細信息。
2. get_election_results - 獲取選區或特定議員的選舉結果。
3. search_members - 按多種條件搜索下議院或上議院議員。
4. get_detailed_member_information - 獲取議員的綜合信息，包括傳記、聯繫方式、利益關係和投票記錄。
5. get_state_of_the_parties - 獲取特定日期下某議院各政黨的情況。
6. get_government_posts - 獲取所有政府職位及其現任官員的詳盡列表。
7. get_opposition_posts - 獲取所有反對黨職位及其現任官員的詳盡列表。
8. get_departments - 獲取政府部門的參考數據。
9. search_parliamentary_questions - 按主題、日期、政黨或議員搜索議會書面問題（PQs）。
10. search_debates - 通過辯論標題搜索相關辯論。
11. search_contributions - 在議會記錄（Hansard）中搜索辯論期間的實際發言內容。

📦 安裝指南

手動設置

1. 克隆項目、設置環境並啟動服務

Elasticsearch配置說明

系統支持兩種連接Elasticsearch的方法：

1. 本地/自託管：使用ELASTICSEARCH_HOST、ELASTICSEARCH_PORT和ELASTICSEARCH_SCHEME。
2. Elasticsearch雲服務：使用ELASTICSEARCH_CLOUD_ID和ELASTICSEARCH_API_KEY（自動配置主機、端口和協議）。

# 克隆倉庫
git clone git@github.com:i-dot-ai/parliament-mcp.git
cd parliament-mcp

# 設置環境並完成.env文件配置
cp .env.example .env
nano .env

# 啟動Elasticsearch和MCP服務器
docker-compose up --build

服務將在以下地址可用：

• MCP服務器：http://localhost:8080/mcp/
• Elasticsearch：http://localhost:9200

2. 安裝mcp-remote

npm install -g mcp-remote

3. 配置Claude桌面版

將以下內容添加到Claude桌面版配置文件中：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "parliament-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8080/mcp/",
        "--allow-http",
        "--debug"
      ]
    }
  }
}

你也可以使用以下命令自動生成此配置：

make mcp_claude_config

4. 重啟Claude桌面版

重啟後，Claude應該可以訪問議會MCP工具。

💻 使用示例

基礎用法

連接到Claude後，你可以使用自然語言查詢，例如：

• 議會問題：
  • "搜索關於氣候變化政策的議會問題"
  • "查找保守黨議員提出的關於醫療保健資金的問題"
  • "顯示上週關於教育的近期問題"
• 議會記錄發言：
  • "搜索關於預算辯論的發言"
  • "查找基爾·斯塔默關於經濟政策的演講"
  • "顯示上議院關於移民問題的辯論"
• 議員信息：
  • "獲取伯明翰埃德巴斯頓選區議員的詳細信息"
  • "搜索2024年當選的工黨議員"
  • "查找郵編SW1A 0AA對應的選區信息"
• 議會結構：
  • "顯示現任政府部長"
  • "獲取下議院各政黨的情況"
  • "列出所有反對黨影子內閣職位"
• 通用查詢：
  • "搜索關於人工智能監管的辯論"
  • "查找邊緣選區的選舉結果"
  • "顯示政府部門及其職責"

日誌和調試

• 查看服務器日誌：

docker-compose logs mcp-server

• 在Claude配置中啟用調試模式：添加--debug標誌。
• 檢查Elasticsearch狀態：

curl http://localhost:9200/_cat/health?v
# 或者使用make命令：
make es_health

📚 詳細文檔

開發

本地開發的先決條件

• Python >= 3.12
• uv（Python包管理器）
• Docker和Docker Compose
• Node.js（用於mcp-remote）

本地開發設置

1. 安裝uv（如果尚未安裝）：

curl -LsSf https://astral.sh/uv/install.sh | sh

2. 克隆並設置項目：

git clone <repository>
cd parliament-mcp

# 使用uv安裝依賴項
uv sync --extra dev

3. 可用的Make命令：

make install           # 安裝所有依賴項
make test              # 運行測試
make test_integration  # 運行集成測試（首次運行較慢）
make lint              # 檢查代碼格式
make format            # 格式化並修復代碼
make safe              # 運行安全檢查

# 預提交鉤子
make pre-commit-install  # 安裝預提交鉤子
make pre-commit         # 對所有文件運行預提交檢查

# Docker操作
make run             # 使用Docker Compose啟動服務
make stop            # 停止Docker服務
make logs            # 查看MCP服務器日誌

# 開發輔助命令
make mcp_test        # 測試MCP服務器連接
make es_health       # 檢查Elasticsearch健康狀態

4. 在本地運行MCP服務器：

make run_mcp_server
# 或者直接使用uv運行：
uv run parliament-mcp serve

項目結構

parliament-mcp/
├── parliament_mcp/           # 主要Python包
│   ├── cli.py               # 命令行界面
│   ├── models.py            # 數據模型
│   ├── mcp_server/          # MCP服務器實現
│   │   ├── api.py           # API端點和工具定義
│   │   ├── handlers.py      # Elasticsearch查詢處理程序
│   │   ├── main.py          # FastAPI應用程序設置
│   │   └── utils.py         # 實用函數
│   └── ...                  # 其他模塊
├── tests/                   # 測試套件
│   ├── mcp_server/          # MCP服務器測試
│   └── ...                  # 其他測試
├── Dockerfile.mcp-server    # MCP服務器容器配置
├── docker-compose.yaml      # 服務編排
└── README.md                # 本文件

CLI命令

項目包含一個統一的命令行界面，用於數據管理和服務器操作：

# 初始化Elasticsearch索引和推理端點
parliament-mcp init-elasticsearch

# 運行MCP服務器
parliament-mcp serve

# 靈活解析日期並加載數據
parliament-mcp load-data hansard --from-date "3 days ago" --to-date "today"
parliament-mcp load-data parliamentary-questions --from-date "2025-01-01"

# 刪除所有數據
parliament-mcp delete-elasticsearch

數據結構

系統處理兩種主要類型的議會文檔：

• 議會問題（索引：parliamentary_questions）：
  • 對問題和答案文本進行語義搜索的書面問題。
  • 提問和回答議員的信息。
  • 日期、參考編號和部門詳細信息。
• 議會記錄發言（索引：hansard_contributions）：
  • 議會辯論中的發言內容。
  • 對完整發言文本進行語義搜索。
  • 發言者信息和辯論背景。
  • 議院（下議院/上議院）和會議日期。

數據加載過程

1. 獲取：從議會API（Hansard API、議會問題API）獲取數據。
2. 轉換：將數據轉換為帶有計算字段的結構化模型。
3. 嵌入：使用Azure OpenAI進行語義搜索嵌入。
4. 索引：將數據索引到Elasticsearch中，並進行適當的映射。 數據會自動從官方議會API加載，無需手動創建文檔。

每日數據攝取

為了保持Elasticsearch中的數據更新，提供了每日攝取機制，該機制會從hansard和parliamentary-questions數據源加載最近兩天的數據。

手動運行每日攝取：

make ingest_daily

這相當於運行以下命令：

parliament-mcp load-data hansard --from-date "2 days ago" --to-date "today"
parliament-mcp load-data parliamentary-questions --from-date "2 days ago" --to-date "today"

你可以使用cron作業實現自動每日攝取。以下是標準cron和AWS EventBridge cron的示例：

標準Cron

此cron作業將在每天凌晨4點運行：

0 4 * * * cd /path/to/parliament-mcp && make ingest_daily

AWS EventBridge Cron

此AWS EventBridge cron表達式將在每天凌晨4點UTC運行：

cron(0 4 * * ? *)

AWS Lambda部署每日攝取任務說明

提供了基於Docker的AWS Lambda鏡像，用於運行每日攝取任務。

1. 構建Lambda容器鏡像： 使用提供的Makefile目標構建Docker鏡像：

make docker_build_lambda

這將創建一個名為parliament-mcp-lambda:latest的Docker鏡像。 2. 在本地測試Lambda： 你可以使用AWS Lambda運行時接口模擬器（RIE）在本地測試Lambda函數，該模擬器包含在基礎鏡像中。

• 先決條件：
  • 本地Elasticsearch容器必須正在運行（docker compose up -d elasticsearch）。
  • 必須構建Lambda容器鏡像（make docker_build_lambda）。
• 運行容器： 使用--env-file標誌和.env文件提供必要的環境變量。你仍然需要覆蓋ELASTICSEARCH_HOST，以確保容器可以連接到本地運行的服務。

docker run --rm -p 9000:8080 \
  --env-file .env \
  -e ELASTICSEARCH_HOST="host.docker.internal" \
  parliament-mcp-lambda:latest

• 觸發函數： 打開一個新終端，運行以下curl命令發送測試調用。from_date和to_date參數是可選的，如果未提供，將默認加載最近兩天的所有數據。

curl -X POST "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{"from_date": "2025-06-23", "to_date": "2025-06-27"}'

3. 在AWS中配置Lambda： 將鏡像推送到ECR後，你可以使用以下配置創建Lambda：

• 使用ELASTICSEARCH_HOST、ELASTICSEARCH_PORT和ELASTICSEARCH_SCHEME指向你的Elasticsearch集群。
• 將默認超時時間增加到約10分鐘，以確保攝取任務有足夠的時間完成。
• 使用AWS的cron表達式每天凌晨4點UTC運行任務：cron(0 4 * * ? *)。

🔧 技術細節

常見問題排查

常見問題

• MCP連接問題：
  • 確保MCP服務器在端口8080上運行。
  • MCP服務器運行在/{MCP_ROOT_PATH}/mcp，而不是/MCP_ROOT_PATH。
  • 驗證Claude桌面版配置是否正確。
• 數據加載失敗：
  • 檢查.env文件中的Azure OpenAI憑證。
  • 確保Elasticsearch正在運行且可訪問。
  • 驗證與議會API的網絡連接。
  • 使用--ll DEBUG標誌進行詳細日誌記錄。
• Elasticsearch問題：
  • 驗證推理端點是否已創建：parliament-mcp init-elasticsearch。
  • 使用https://elasticvue.com/ 檢查Elasticsearch實例。

📄 許可證

本項目採用MIT許可證，詳情請參閱LICENSE文件。

貢獻說明

歡迎貢獻代碼！請參閱貢獻指南瞭解如何開始貢獻。