文化遗产搜索服务器

Kulturerbe MCP服务器

模型上下文协议（MCP）服务器，用于通过Kulturpool API搜索奥地利文化遗产。

概述

此MCP服务器通过 API库尔图普尔它实现了一个6工具渐进式披露架构，旨在实现高效的上下文窗口使用和全面的文化对象发现。

特性

🔍 6-Tool渐进式披露架构

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端点

⚡ 性能优化

• 渐进呈现：从宽开始，然后缩小范围
• 压缩响应：仅基本元数据
• 基于Facet的导航：智能过滤建议
• 连接池：具有重试逻辑的高效HTTP客户端

安装

先决条件

• Python 3.8或更高版本
• pip包管理器
• Git（用于克隆存储库）

设置

1. 克隆存储库：

   复制

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

2. 创建并激活虚拟环境：

   窗户：

   复制

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

   Linux/WWSL/macOS：

   复制

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

3. 安装依赖项：

   复制

   pip install -r requirements.txt
   

4. 测试服务器：

   窗户：

   复制

   python server.py
   

   Linux/WWSL/macOS：

   复制

   python3 server.py
   

Claude桌面配置

将服务器添加到Claude Desktop MCP配置文件中：

配置文件位置：

• 窗户： %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 -将相关部分复制到配置文件中。

替代方案：启动器脚本

窗户：

run_server.bat

Linux/WWSL/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传输
• 异步/等待：完全异步操作
• Pydantic验证：类型安全参数处理
• 安全层：输入消毒和速率限制
• 错误处理：全面的异常管理

关键组件

├── SecurityValidator     # Input sanitization and validation
├── RateLimiter          # Request rate limiting (100/hour)
├── KulturpoolClient     # HTTP client with retry logic
├── ResponseProcessor    # Data processing and facet analysis
└── Tool Handlers        # Six specialized tool implementations

配置

环境变量

不需要环境变量-服务器直接连接到公共Kulturpool API。

速率限制

• 默认：每个客户端每小时100个请求
• 可配置的：修改 RateLimiter(max_requests=100, time_window=3600)
• 范围：全球所有工具调用

响应限制

• 探索：<2KB的回复，有刻面
• 搜索：≤20个包含完整元数据的结果
• 详情：每个请求≤3个对象ID
• 总体：<10KB响应大小限制

api参考

数据源

此服务器提供对以下内容的访问：

• API基础: https://api.kulturpool.at/search/
• API机构: https://api.kulturpool.at/institutions/
• 资产API: https://api.kulturpool.at/assets/

对象类型

• 图像：照片、绘画、素描、图形
• 文本：手稿、书籍、文件、信件
• 声音：录音、音乐、口述历史
• 视频：电影录制、纪录片
• 三维：三维物体、雕塑

排序选项

• titleSort:asc/desc -按标题字母顺序排列
• dataProvider:asc/desc -按机构
• dateMin:asc/desc -最早日期
• dateMax:asc/desc -截止日期

贡献

1. 复刻仓库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

许可证

此项目根据MIT许可证获得许可-请参阅 LICENSE.txt 文件以获取详细信息。

支持

• 问题: GitHub问题
• 讨论: GitHub讨论
• API文档: API库尔图普尔

开发信贷

该MCP服务器是在 ÖAW-ACDH 使用 氛围编程 方法论 克劳德·十四行诗4 通过 克劳德代码CLI.

⚠️ Beta免责声明

此MCP服务器是测试版和实验软件。

• 该软件经过了有限的测试，应被视为实验性软件
• 在生产环境中使用，风险自负
• 开发人员对使用本软件造成的任何损害、数据丢失或其他后果不承担任何责任
• 对于本软件用于任何特定目的的功能、可靠性或适用性，不提供任何明示或暗示的保证

致谢

• 文化游泳池 -奥地利文化遗产平台
• 模型上下文协议 -协议规范
• Anthropic -Claude桌面集成
• 奥地利科学院 -研究机构支持