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 對象類型的訪問：

⚠️ 項目狀態

本項目目前正在開發中，需要進行額外的驗證和測試。雖然核心功能已實現，但尚未在生產環境中進行全面測試。請謹慎使用，並報告您遇到的任何問題。

⚙️ 配置

服務器可以使用環境變量或通過編程方式進行配置：

環境變量配置

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 實現配合使用：

每個實現可能有不同的：

• 認證要求
• 可用數據
• 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 集成標準