Parliament MCP

🚀 议会MCP服务器

议会MCP服务器大致映射到 https://developer.parliament.uk/ 的一个子集，同时还提供额外的语义搜索功能。

🚀 快速开始（本地Elasticsearch）

你需要准备以下环境：

• Docker和Docker Compose
• Node.js（用于 mcp-remote）
• Claude Desktop（或其他MCP客户端）
• 具备API访问权限的Azure OpenAI账户

通过复制项目根目录下的 .env.example 文件来创建一个 .env 文件，并替换其中必要的变量。

在配置好 .env 文件后，运行以下命令，一次性完成MCP服务器和Elasticsearch数据库的设置，并加载2025年6月的一些示例数据：

make dev_setup_from_scratch

运行上述命令后，你可以使用以下配置连接到MCP服务器：

# 将此配置添加到你的Claude Desktop配置文件中，或其他MCP客户端配置文件中：
# 在macOS系统中，Claude Desktop配置文件位于 `~/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议会记录中搜索辩论期间的实际发言内容

📦 安装指南

手动设置

关于Elasticsearch配置的说明

系统支持两种连接到Elasticsearch的方法：

1. 本地/自托管：使用 ELASTICSEARCH_HOST、ELASTICSEARCH_PORT 和 ELASTICSEARCH_SCHEME
2. Elasticsearch Cloud：使用 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

3. 初始化Elasticsearch并加载数据

# 初始化Elasticsearch
docker compose exec mcp-server uv run parliament-mcp --log-level INFO init-elasticsearch

# 加载2025年6月23日至2025年6月27日的Hansard数据
docker compose exec mcp-server uv run parliament-mcp load-data hansard --from-date 2025-06-23 --to-date 2025-06-27

# 加载2025年6月23日至2025年6月27日的议会问题
docker compose exec mcp-server uv run parliament-mcp --log-level WARNING load-data parliamentary-questions --from-date 2025-06-23 --to-date 2025-06-27

2. 安装mcp-remote

npm install -g mcp-remote

3. 配置Claude Desktop

将以下内容添加到你的Claude Desktop配置文件中：

• 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 Desktop

此时Claude应该可以访问议会MCP工具了。

💻 使用示例

连接到Claude后，你可以使用自然语言进行查询，例如：

议会问题

• "搜索关于气候变化政策的议会问题"
• "查找保守党议员提出的关于医疗保健资金的问题"
• "显示上周关于教育的近期问题"

Hansard发言记录

• "搜索关于预算辩论的发言记录"
• "查找基尔·斯塔默关于经济政策的演讲"
• "显示上议院关于移民问题的辩论"

议员信息

• "获取伯明翰埃德巴斯顿选区议员的详细信息"
• "搜索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                # 本文件

命令行工具命令

项目包含一个统一的命令行工具，用于数据管理和服务器操作：

# 初始化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发言记录（索引：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点左右运行 - cron(0 4 * * ? *)

• 请记住将默认超时时间增加到约10分钟，以确保摄取任务有足够的时间完成。

🔧 技术细节

常见问题排查

MCP连接问题

• 确保MCP服务器在端口8080上运行
• MCP服务器运行在 /{MCP_ROOT_PATH}/mcp，而不是 /MCP_ROOT_PATH
• 验证Claude Desktop配置是否正确

数据加载失败

• 检查 .env 文件中的Azure OpenAI凭证
• 确保Elasticsearch正在运行且可访问
• 验证与议会API的网络连接
• 使用 --ll DEBUG 标志进行详细日志记录

Elasticsearch问题

• 验证推理端点是否已创建：parliament-mcp init-elasticsearch
• 使用 https://elasticvue.com/ 检查Elasticsearch实例

📄 许可证

本项目采用MIT许可证，详情请参阅 LICENSE 文件。

🤝 贡献

欢迎贡献代码！有关如何开始的详细信息，请参阅我们的 贡献指南。