🚀 议会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服务器:
{
"mcpServers": {
"parliament-mcp": {
"command": "npx",
"args": ["mcp-remote", "http://localhost:8080/mcp/", "--allow-http", "--debug"]
}
}
}
✨ 主要特性
可用的MCP工具
MCP服务器提供了11种工具,可辅助议会研究工作:
search_constituency
- 按名称搜索选区,或通过ID获取选区的详细信息。
get_election_results
- 获取选区或特定议员的选举结果。
search_members
- 按多种条件搜索下议院或上议院议员。
get_detailed_member_information
- 获取议员的综合信息,包括传记、联系方式、利益关系和投票记录。
get_state_of_the_parties
- 获取特定日期下某议院各政党的情况。
get_government_posts
- 获取所有政府职位及其现任官员的详尽列表。
get_opposition_posts
- 获取所有反对党职位及其现任官员的详尽列表。
get_departments
- 获取政府部门的参考数据。
search_parliamentary_questions
- 按主题、日期、政党或议员搜索议会书面问题(PQs)。
search_debates
- 通过辩论标题搜索相关辩论。
search_contributions
- 在议会记录(Hansard)中搜索辩论期间的实际发言内容。
📦 安装指南
手动设置
1. 克隆项目、设置环境并启动服务
Elasticsearch配置说明
系统支持两种连接Elasticsearch的方法:
- 本地/自托管:使用
ELASTICSEARCH_HOST
、ELASTICSEARCH_PORT
和ELASTICSEARCH_SCHEME
。
- Elasticsearch云服务:使用
ELASTICSEARCH_CLOUD_ID
和ELASTICSEARCH_API_KEY
(自动配置主机、端口和协议)。
git clone git@github.com:i-dot-ai/parliament-mcp.git
cd parliament-mcp
cp .env.example .env
nano .env
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 es_health
📚 详细文档
开发
本地开发的先决条件
- Python >= 3.12
- uv(Python包管理器)
- Docker和Docker Compose
- Node.js(用于mcp-remote)
本地开发设置
- 安装uv(如果尚未安装):
curl -LsSf https://astral.sh/uv/install.sh | sh
- 克隆并设置项目:
git clone <repository>
cd parliament-mcp
uv sync --extra dev
- 可用的Make命令:
make install
make test
make test_integration
make lint
make format
make safe
make pre-commit-install
make pre-commit
make run
make stop
make logs
make mcp_test
make es_health
- 在本地运行MCP服务器:
make run_mcp_server
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命令
项目包含一个统一的命令行界面,用于数据管理和服务器操作:
parliament-mcp init-elasticsearch
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
):
- 议会辩论中的发言内容。
- 对完整发言文本进行语义搜索。
- 发言者信息和辩论背景。
- 议院(下议院/上议院)和会议日期。
数据加载过程
- 获取:从议会API(Hansard API、议会问题API)获取数据。
- 转换:将数据转换为带有计算字段的结构化模型。
- 嵌入:使用Azure OpenAI进行语义搜索嵌入。
- 索引:将数据索引到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镜像,用于运行每日摄取任务。
- 构建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"}'
- 在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文件。
贡献说明
欢迎贡献代码!请参阅贡献指南了解如何开始贡献。