Kulturpool MCP Server

🚀 クルチュレルベ MCP サーバー

このサーバーは、Kulturpool API を介してオーストリアの文化遺産を検索するための Model Context Protocol (MCP) サーバーです。

🚀 クイックスタート

この MCP サーバーを使用することで、Kulturpool API を介してオーストリアの文化遺産に安全でレート制限付きのアクセスが可能になります。これは、効率的なコンテキストウィンドウの使用と包括的な文化オブジェクトの発見のために設計された6つのツールを持つ段階的開示アーキテクチャを実装しています。

✨ 主な機能

🔍 6つのツールによる段階的開示アーキテクチャ

1. kulturpool_explore - ファセット分析による初期探索 (< 2KB のレスポンス)
2. kulturpool_search_filtered - 包括的なフィルターを使用したターゲット検索 (≤ 20 件の結果)
3. kulturpool_get_details - コンテンツベースの検索を使用して関連オブジェクトを検索 (≤ 3 つの ID)
4. kulturpool_get_institutions - 場所情報を含む完全な機関ディレクトリ
5. kulturpool_get_institution_details - 機関の詳細メタデータ
6. kulturpool_get_assets - 変換機能を持つ最適化された画像アセット

🛡️ 組み込みのセキュリティ機能

• 入力サニタイズ：インジェクション攻撃からの保護
• レート制限：クライアントごとに1時間あたり100リクエスト
• レスポンス制限：コンテキスト効率のために < 10KB のレスポンス
• パラメーター検証：包括的な Pydantic ベースの検証
• 安全な URL 処理：Kulturpool API エンドポイントに制限

⚡ パフォーマンス最適化

• 段階的開示：広範囲から絞り込む
• 圧縮されたレスポンス：必要なメタデータのみ
• ファセットベースのナビゲーション：スマートなフィルター推奨
• コネクションプーリング：リトライロジックを持つ効率的な HTTP クライアント

📦 インストール

前提条件

• Python 3.8 以上
• pip パッケージマネージャー
• Git (リポジトリのクローン用)

セットアップ

1. リポジトリをクローンする:

   git clone https://github.com/yourusername/kulturerbe_mcp.git
   cd kulturerbe_mcp
   

2. 仮想環境を作成してアクティブ化する:

   Windows:

   python -m venv .venv
   .venv\Scripts\activate
   

   Linux/WSL/macOS:

   python3 -m venv .venv
   source .venv/bin/activate
   

3. 依存関係をインストールする:

   pip install -r requirements.txt
   

4. サーバーをテストする:

   Windows:

   python server.py
   

   Linux/WSL/macOS:

   python3 server.py
   

Claude Desktop の設定

サーバーを Claude Desktop の MCP 設定ファイルに追加します:

設定ファイルの場所:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

オプション 1: WSL を使用した Windows (このプロジェクトで推奨)

{
  "mcpServers": {
    "kulturerbe-mcp-server": {
      "command": "wsl",
      "args": ["-e", "/home/username/kulturerbe_mcp/run_server.sh"],
      "cwd": "\\\\wsl$\\Ubuntu\\home\\username\\kulturerbe_mcp",
      "env": {
        "VIRTUAL_ENV": "/home/username/kulturerbe_mcp/.venv",
        "PATH": "/home/username/kulturerbe_mcp/.venv/bin:$PATH"
      }
    }
  }
}

オプション 2: ネイティブの Windows

{
  "mcpServers": {
    "kulturerbe-mcp-server": {
      "command": "python",
      "args": ["C:\\path\\to\\kulturerbe_mcp\\server.py"],
      "cwd": "C:\\path\\to\\kulturerbe_mcp",
      "env": {}
    }
  }
}

オプション 3: Linux/macOS

{
  "mcpServers": {
    "kulturerbe-mcp-server": {
      "command": "python3",
      "args": ["/path/to/kulturerbe_mcp/server.py"],
      "cwd": "/path/to/kulturerbe_mcp",
      "env": {}
    }
  }
}

Claude Code の設定

WSL/Linux 環境での Claude Code の場合:

{
  "mcpServers": {
    "kulturerbe-mcp-server": {
      "command": "/home/username/kulturerbe_mcp/run_server.sh",
      "args": [],
      "cwd": "/home/username/kulturerbe_mcp",
      "env": {
        "VIRTUAL_ENV": "/home/username/kulturerbe_mcp/.venv",
        "PATH": "/home/username/kulturerbe_mcp/.venv/bin:$PATH"
      }
    }
  }
}

📝 注意: mcp_config.json に事前設定されたオプションがあります - 関連するセクションを設定ファイルにコピーしてください。

代替方法: ランチャースクリプト

Windows:

run_server.bat

Linux/WSL/macOS:

chmod +x run_server.sh
./run_server.sh

💻 使用例

基本的な使用法

1. 初期探索

利用可能なデータを理解するために広範囲の探索から始めます:

# Get overview with facets
kulturpool_explore(query="Mozart")

返り値: 機関、タイプ、期間ごとのファセットカウントとサンプル結果。

2. フィルター付き検索

ファセットを使用して結果を絞り込みます:

# Targeted search with filters
kulturpool_search_filtered(
    query="Vienna",
    institutions=["Albertina", "Belvedere"],
    object_types=["IMAGE"],
    date_from=1800,
    date_to=1900,
    creators=["Klimt"],
    limit=15
)

高度なフィルター:

• 日付範囲: 期間の重複セマンティクス (オブジェクトの [dateMin,dateMax] が [date_from,date_to] と重複する)
• 作成者: ワイルドカードを使用した部分一致
• 主題: トピックの正確な一致
• メディア: 素材/媒体でフィルター
• ダブリンコアタイプ: パフォーマンス制限付きのオブジェクト分類

3. 関連オブジェクトの発見

コンテンツベースの検索を使用して関連する文化オブジェクトを検索します:

# Find related objects
kulturpool_get_details(object_ids=["obj123", "obj456"])

4. 機関管理

参加する機関を探索します:

# Get institution directory
kulturpool_get_institutions(include_locations=True, language="de")

# Get detailed institution info
kulturpool_get_institution_details(institution_id=42, language="de")

5. アセットの最適化

変換機能を持つ最適化された画像にアクセスします:

# Get optimized image assets
kulturpool_get_assets(
    asset_id="logo_123",
    width=400,
    height=300,
    format="webp",
    quality=85,
    fit="inside"
)

サポートされている機関の選択

主要なオーストリアの文化機関が Kulturpool ネットワークに参加しています:

• アルベルティナ美術館 - グラフィックと現代美術
• ベルベデーレ美術館 - オーストリア美術とバロック美術コレクション
• オーストリア国立図書館 - 国立図書館とアーカイブ
• ウィーン市立・州立アーカイブ - ウィーン市のアーカイブ
• オーストリア応用美術館 - 応用美術と現代美術
• ウィーン世界博物館 - 民族学コレクション
• ウィーン技術博物館 - 技術と産業
• ウィーン自然史博物館 - 自然史

🔧 技術詳細

アーキテクチャ

サーバーは単一ファイル実装 (server.py, ~1300 行) で構築されており、以下の機能を持っています:

• MCP プロトコル: 従来の stdio トランスポート
• Async/Await: 完全な非同期操作
• Pydantic 検証: 型安全なパラメーター処理
• セキュリティレイヤー: 入力サニタイズとレート制限
• エラーハンドリング: 包括的な例外管理

主要なコンポーネント

├── SecurityValidator     # 入力サニタイズと検証
├── RateLimiter          # リクエストのレート制限 (1時間あたり100件)
├── KulturpoolClient     # リトライロジックを持つ HTTP クライアント
├── ResponseProcessor    # データ処理とファセット分析
└── Tool Handlers        # 6つの特殊なツールの実装

設定

環境変数

環境変数は必要ありません - サーバーは直接公開されている Kulturpool API に接続します。

レート制限

• デフォルト: クライアントごとに1時間あたり100リクエスト
• 設定可能: RateLimiter(max_requests=100, time_window=3600) を変更
• 適用範囲: すべてのツール呼び出しに対してグローバル

レスポンス制限

• 探索: ファセット付きで < 2KB のレスポンス
• 検索: 完全なメタデータを含む ≤ 20 件の結果
• 詳細: リクエストあたり ≤ 3 つのオブジェクト ID
• 全体: < 10KB のレスポンスサイズ制限

📚 ドキュメント

API リファレンス

データソース

このサーバーは以下の API にアクセスできます:

• ベース API: https://api.kulturpool.at/search/
• 機関 API: https://api.kulturpool.at/institutions/
• アセット API: https://api.kulturpool.at/assets/

オブジェクトタイプ

• IMAGE: 写真、絵画、素描、グラフィック
• TEXT: 写本、書籍、文書、手紙
• SOUND: 音声録音、音楽、口頭史
• VIDEO: 映画録画、ドキュメンタリー
• 3D: 三次元オブジェクト、彫刻

ソートオプション

• titleSort:asc/desc - タイトルのアルファベット順
• dataProvider:asc/desc - 機関ごと
• dateMin:asc/desc - 最も早い日付ごと
• dateMax:asc/desc - 最も遅い日付ごと

📄 ライセンス

このプロジェクトは MIT ライセンスの下で公開されています - 詳細は LICENSE.txt ファイルを参照してください。

サポート

• 問題報告: GitHub Issues
• ディスカッション: GitHub Discussions
• API ドキュメント: Kulturpool API

開発のクレジット

この MCP サーバーは ÖAW-ACDH で開発され、Vibe Coding 方法論を使用し、Claude Code CLI を介して Claude Sonnet 4 の支援を受けています。

⚠️ ベータ版の免責事項

この MCP サーバーはベータ版であり、実験的なソフトウェアです。

• このソフトウェアは限られたテストしか受けておらず、実験的なものと見なされるべきです
• 本番環境での使用は自己責任で行ってください
• 開発者は、このソフトウェアの使用に起因する損害、データ損失、またはその他の結果に対して一切の責任を負いません
• このソフトウェアの機能、信頼性、または特定の目的への適合性に関して、明示的または黙示的な保証は一切提供されません

謝辞

• Kulturpool - オーストリアの文化遺産プラットフォーム
• Model Context Protocol - プロトコル仕様
• Anthropic - Claude Desktop の統合
• オーストリア科学アカデミー - 研究機関のサポート