Kulturpool MCP Server

🚀 奧地利文化遺產MCP服務器

本項目是一個基於模型上下文協議（MCP）的服務器，藉助Kulturpool API實現奧地利文化遺產的搜索功能，為用戶提供便捷、安全且高效的文化遺產信息查詢服務。

🚀 快速開始

前提條件

• 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桌面配置

將服務器添加到Claude桌面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代碼配置

對於WSL/Linux環境中的Claude代碼：

{
  "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. 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 - 經過優化和轉換的圖像資源

🛡️ 內置安全機制

• 輸入清理：防止注入攻擊
• 速率限制：每個客戶端每小時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桌面配置

將服務器添加到Claude桌面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代碼配置

對於WSL/Linux環境中的Claude代碼：

{
  "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. 初始探索

從廣泛的探索開始，瞭解可用數據：

# 獲取帶分面的概述
kulturpool_explore(query="Mozart")

返回結果：按機構、類型和時間段劃分的分面計數，以及示例結果。

2. 過濾搜索

使用分面縮小搜索結果範圍：

# 帶過濾器的目標搜索
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. 相關對象發現

使用基於內容的搜索查找相關文化對象：

# 查找相關對象
kulturpool_get_details(object_ids=["obj123", "obj456"])

4. 機構管理

探索參與的機構：

# 獲取機構目錄
kulturpool_get_institutions(include_locations=True, language="de")

# 獲取詳細的機構信息
kulturpool_get_institution_details(institution_id=42, language="de")

5. 資源優化

訪問經過優化和轉換的圖像：

# 獲取優化後的圖像資源
kulturpool_get_assets(
    asset_id="logo_123",
    width=400,
    height=300,
    format="webp",
    quality=85,
    fit="inside"
)

📚 詳細文檔

支持的機構選擇

奧地利主要的文化機構參與了Kulturpool網絡：

• 阿爾貝蒂娜博物館 - 圖形和現代藝術
• 美景宮 - 奧地利藝術和巴洛克藝術收藏
• 奧地利國家圖書館 - 國家圖書館和檔案館
• 維也納市立和州立檔案館 - 維也納城市檔案館
• 應用藝術博物館 - 應用藝術和當代藝術
• 維也納世界博物館 - 民族誌收藏
• 維也納技術博物館 - 技術和工業
• 維也納自然歷史博物館 - 自然歷史

開發

架構

服務器採用單文件實現（server.py，約1300行），具備以下特點：

• MCP協議：傳統的標準輸入輸出傳輸
• 異步/等待：全異步操作
• Pydantic驗證：類型安全的參數處理
• 安全層：輸入清理和速率限制
• 錯誤處理：全面的異常管理

關鍵組件

├── SecurityValidator     # 輸入清理和驗證
├── RateLimiter          # 請求速率限制（每小時100個）
├── KulturpoolClient     # 具備重試邏輯的HTTP客戶端
├── ResponseProcessor    # 數據處理和分面分析
└── Tool Handlers        # 六個專門的工具實現

配置

環境變量

無需設置環境變量，服務器直接連接到公共的Kulturpool API。

速率限制

• 默認值：每個客戶端每小時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 - 按最晚日期排序

🔧 技術細節

服務器採用單文件實現（server.py，約1300行），運用了MCP協議進行傳統的標準輸入輸出傳輸。通過異步/等待機制實現全異步操作，提高了服務器的響應性能。使用Pydantic進行參數驗證，確保了類型安全。同時，具備輸入清理和速率限制的安全層，以及全面的異常管理機制，保障了服務器的穩定性和安全性。

📄 許可證

本項目採用MIT許可證，詳情請參閱 LICENSE.txt 文件。

支持

• 問題反饋：GitHub Issues
• 討論交流：GitHub Discussions
• API文檔：Kulturpool API

開發致謝

本MCP服務器由 奧地利科學院數字人文中心（ÖAW - ACDH） 開發，採用了 Vibe Coding 方法，並藉助 Claude Code CLI 工具，在 Claude Sonnet 4 的協助下完成。

⚠️ 測試版免責聲明

此MCP服務器為測試版，屬於實驗性軟件。

• 該軟件僅經過有限測試，應視為實驗性產品。
• 在生產環境中使用需自行承擔風險。
• 開發者對因使用本軟件而導致的任何損害、數據丟失或其他後果不承擔責任。
• 對於本軟件的功能、可靠性或適用性，不提供任何明示或暗示的保證。

致謝

• Kulturpool - 奧地利文化遺產平臺
• 模型上下文協議 - 協議規範
• Anthropic - Claude桌面集成
• 奧地利科學院 - 研究機構支持