Oparl MCP Server

🚀 OParl MCP Server

OParl MCP Serverは、Model Context Protocol（MCP）を介して、AIモデルやアプリケーションにOParl議会データAPIへのシームレスなアクセスを提供します。自然言語クエリや、複数の実装にまたがる議会情報システムへの構造化アクセスを可能にします。

⚠️ プロジェクトの状態

⚠️ 重要提示

このプロジェクトは現在開発中で、追加の検証とテストが必要です。コア機能は実装されていますが、本番環境で十分にテストされていません。注意して使用し、遭遇した問題は報告してください。

🚀 クイックスタート

前提条件

• 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統合：完全なModel Context Protocol準拠
• 🏛️ 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"Found {len(meetings)} resources")

            # 特定の会議を取得する
            meeting = await session.read_resource("oparl_meeting_123")
            print(f"Meeting: {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"Server: {info['name']}")
print(f"Features: {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 Model      │    │   MCP Client    │    │   MCP Server    │
│                 │◄──►│                 │◄──►│   (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 Specification - 公式OParlドキュメント
• FastMCP Framework - MCPサーバー生成フレームワーク
• Model Context Protocol - AI統合標準