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桌面集成
• 奥地利科学院 - 研究机构支持