oparl-mcp-server

🚀 OParl MCP 服务器

OParl MCP 服务器是一个基于模型上下文协议（MCP）的服务器，用于访问 OParl 议会数据 API，它能让 AI 模型和应用程序无缝接入议会数据。

🚀 快速开始

前提条件

• Python 3.11 或更高版本
• pip（Python 包管理器）

安装步骤

1. 克隆仓库

   git clone https://github.com/jtwolfe/oparl-mcp-server.git
   cd oparl-mcp-server
   

2. 创建虚拟环境

   python -m venv venv
   source venv/bin/activate  # 在 Windows 系统上使用：venv\Scripts\activate
   

3. 安装依赖

   pip install -r requirements.txt
   

4. 运行服务器

   python -m oparl_mcp.server
   

开发环境设置

若进行开发，需安装额外的依赖：

pip install -r requirements-dev.txt

✨ 主要特性

• 🔌 MCP 集成：完全符合模型上下文协议。
• 🏛️ 支持 OParl 1.1：全面支持所有 OParl 对象类型。
• 🌐 多实现支持：可与各种 OParl 实现配合使用。
• 🔐 认证机制：灵活支持 API 密钥和 Bearer 令牌。
• 📊 丰富的数据访问：可访问议会会议、文件、组织等数据。
• 🔍 高级搜索功能：具备查询参数和过滤功能。
• 🐳 Docker 支持：可通过 Docker Compose 进行容器化部署。
• 🧪 全面测试：包含单元测试和集成测试。
• 📚 详细文档：提供完整的 API 参考和使用指南。

🏛️ OParl API

服务器提供对所有标准 OParl 1.1 对象类型的访问： | 对象类型 | 描述 | 关键属性 | |-------------|-------------|----------------| | 系统 | 根系统信息 | oparlVersion、body、created | | 机构 | 议会机构 | name、shortName、organization | | 组织 | 政党和团体 | name、shortName、member | | 人员 | 代表和官员 | name、givenName、familyName | | 会议 | 议会会议 | name、start、end、location | | 议程项目 | 会议主题 | name、meeting、order | | 文件 | 文件和决议 | name、reference、date | | 咨询 | 公众咨询 | name、paper、start、end | | 附件 | 附件和媒体 | name、mimeType、accessUrl | | 地点 | 会议地点 | name、geojson、postalCode |

⚠️ 项目状态

本项目目前正在开发中，需要进行额外的验证和测试。虽然核心功能已实现，但尚未在生产环境中进行全面测试。请谨慎使用，并报告您遇到的任何问题。

⚙️ 配置

服务器可以使用环境变量或通过编程方式进行配置：

环境变量配置

export OPARL_BASE_URL="https://api.oparl.org"
export OPARL_API_KEY="your-api-key"  # 可选
export OPARL_TIMEOUT="30.0"
export OPARL_LOG_LEVEL="INFO"
export OPARL_SERVER_NAME="OParl MCP Server"

编程方式配置

from oparl_mcp import OParlConfig, OParlMCPServer

# 创建配置
config = OParlConfig(
    base_url="https://oparl.muenchen.de",
    api_key="your-munich-api-key",
    timeout=60.0,
    server_name="Munich OParl Server"
)

# 创建并运行服务器
server = OParlMCPServer(config)
server.run()

🌍 OParl 实现

服务器可与各种 OParl 实现配合使用： | 实现 | URL | 描述 | |----------------|-----|-------------| | 通用 OParl API | https://api.oparl.org | 标准 OParl 实现 | | 慕尼黑市议会 | https://oparl.muenchen.de | 慕尼黑议会数据 | | 科隆市议会 | https://oparl.koeln.de | 科隆议会数据 | | 汉堡议会 | https://oparl.hamburg.de | 汉堡议会数据 |

每个实现可能有不同的：

• 认证要求
• 可用数据
• API 端点
• 速率限制

🐳 Docker

使用 Docker Compose

1. 创建环境文件

   cp .env.example .env
   # 编辑 .env 文件，填入您的配置
   

2. 使用 Docker Compose 运行

   docker-compose -f docker/docker-compose.yml up -d
   

直接使用 Docker

# 构建镜像
docker build -f docker/Dockerfile -t oparl-mcp-server .

# 运行容器
docker run -p 8000:8000 \
  -e OPARL_BASE_URL=https://api.oparl.org \
  -e OPARL_API_KEY=your-key \
  oparl-mcp-server

💻 使用示例

基础 MCP 客户端使用

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    async with stdio_client(StdioServerParameters(
        command="python",
        args=["-m", "oparl_mcp.server"]
    )) as (read, write):
        async with ClientSession(read, write) as session:
            # 列出所有会议
            meetings = await session.list_resources()
            print(f"找到 {len(meetings)} 个资源")

            # 获取特定会议
            meeting = await session.read_resource("oparl_meeting_123")
            print(f"会议: {meeting['name']}")

高级配置

from oparl_mcp import OParlMCPServer, OParlConfig

# 为慕尼黑定制配置
config = OParlConfig(
    base_url="https://oparl.muenchen.de",
    api_key="your-munich-api-key",
    timeout=45.0,
    server_name="Munich OParl MCP Server"
)

server = OParlMCPServer(config)
info = server.get_server_info()
print(f"服务器: {info['name']}")
print(f"特性: {info['features']}")

🧪 测试

运行全面的测试套件：

# 运行所有测试
pytest

# 运行带覆盖率的测试
pytest --cov=oparl_mcp --cov-report=html

# 运行特定测试文件
pytest tests/test_server.py

# 运行集成测试
python test_integration.py

📚 详细文档

完整的文档可在 https://jtwolfe.github.io/oparl-mcp-server/ 查看：

• 入门指南 - 快速设置和基本使用
• OParl API 指南 - 完整的 OParl API 参考
• FastMCP 集成 - 技术集成细节
• 架构 - 系统设计和数据流
• API 参考 - 完整的 API 文档
• 贡献指南 - 开发和贡献指南

🔧 MCP 组件

资源

• 系统信息：根系统数据和元数据
• 机构集合：议会机构列表
• 会议日程：即将举行和过去的会议
• 文档集合：文件和报告
• 人员简介：当选官员和工作人员

资源模板

• 单个对象：特定的会议、人员、文件等
• 参数化访问：通过 ID 动态访问资源
• 结构化数据：所有对象的数据格式一致

工具

• 搜索操作：在系统中查找特定数据
• 过滤操作：按各种条件过滤数据
• 导出操作：以不同格式导出数据

🏗️ 架构

服务器使用 FastMCP 将 OParl API 转换为与 MCP 兼容的组件：

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   AI 模型       │    │   MCP 客户端    │    │   MCP 服务器    │
│                 │◄──►│                 │◄──►│   (FastMCP)     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                                       │
                                                       ▼
                                               ┌─────────────────┐
                                               │   OParl API     │
                                               │   (HTTP/REST)   │
                                               └─────────────────┘

🤝 贡献

我们欢迎贡献！请参阅我们的 贡献指南 了解详细信息。

开发环境设置

1. 分叉仓库
2. 创建功能分支：git checkout -b feature/new-feature
3. 安装开发依赖：pip install -r requirements-dev.txt
4. 进行更改
5. 为新功能添加测试
6. 运行测试套件：pytest
7. 提交拉取请求

📄 许可证

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

🙏 致谢

• OParl Initiative 提供标准化的议会数据 API
• FastMCP 提供出色的 MCP 框架
• Model Context Protocol 提供 AI 集成标准
• 开源社区提供的灵感和支持

📞 支持

• 文档：https://jtwolfe.github.io/oparl-mcp-server/
• 问题反馈：GitHub Issues
• 讨论：GitHub Discussions

🔗 相关项目

• OParl 规范 - 官方 OParl 文档
• FastMCP 框架 - MCP 服务器生成框架
• 模型上下文协议 - AI 集成标准