berlin-services-mcp-server

🚀 柏林服务MCP服务器 - 增强版

这是一个用于柏林城市服务（Dienstleistungen）的生产级模型上下文协议（MCP）服务器。它具备弹性缓存、高级搜索、PDF表单发现和填写等功能。

✨ 主要特性

• 综合工具：搜索、浏览柏林服务并获取详细信息。
• 表单管理：发现、分析和填写各种服务的PDF表单。
• 弹性缓存：经过性能优化，具备智能回退机制，支持离线使用。
• 远程同步：支持本地和远程（云）部署。

🔧 技术细节

1. 数据来源

服务器从官方的 柏林城市服务API 获取数据。

• 实时获取：像 search_services 和 get_service_details 这样的工具会调用实时API。
• 弹性缓存：实现了双层缓存（内存 + 磁盘），以确保高性能和离线可靠性。
• 智能回退：如果API不可用且没有缓存，服务器会回退到一组核心服务以保持功能可用。

2. 高级PDF处理

服务器由 PyMuPDF (fitz) 提供支持，提供复杂的文档处理功能：

• 字段提取：自动检测城市服务器上托管的PDF表单中的可填写字段。
• 智能填写：使用智能匹配和常见翻译片段将用户数据映射到PDF字段。
• 循环保护：包含一个 LoopProtector 以防止工具的冗余执行和大语言模型循环。
• 视觉预览：可以将PDF的特定页面渲染为JPEG，以便在聊天中快速查看（无需离开聊天即可验证）。

3. 部署模式

• 本地模式：针对Claude Desktop使用进行了优化。在此模式下，可以使用 open_file_locally 直接用系统默认查看器打开填写好的PDF。
• 远程/云模式：设计用于在Fly.io或Railway等平台上部署。用安全同步和聊天内预览取代本地文件打开功能。

📦 安装指南

前提条件

• Python 3.11或更高版本
• uv（推荐）或 pip

使用 uv（推荐）

1. 安装依赖并同步环境：

   uv sync
   

2. 以模块形式运行服务器：

   export PYTHONPATH=$PYTHONPATH:$(pwd)/src && uv run python -m berlin_mcp.main
   

   注意：如果通过 uv sync 安装了包，也可以直接运行：

   uv run berlin-mcp
   

使用 pip

1. 安装依赖：

   pip install -r requirements.txt
   

2. 运行服务器：

   export PYTHONPATH=$PYTHONPATH:$(pwd)/src && python -m berlin_mcp.main
   

📚 详细文档

Claude Desktop配置

将以下内容添加到Claude Desktop配置文件中。将 /Users/mananshah/Desktop/Berlin-Services-MCP-Server 替换为实际文件夹的绝对路径。

macOS

文件位置：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "berlin-services": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/Users/YourUser/Desktop/Berlin-Services-MCP-Server",
        "python",
        "-m",
        "berlin_mcp.main"
      ],
      "env": {
        "PYTHONPATH": "src"
      }
    }
  }
}

Windows

文件位置：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "berlin-services": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:\\Users\\YourUser\\Desktop\\Berlin-Services-MCP-Server",
        "python",
        "-m",
        "berlin_mcp.main"
      ],
      "env": {
        "PYTHONPATH": "src"
      }
    }
  }
}

💻 使用示例

工具和资源

服务器提供以下工具，帮助你浏览和管理柏林城市服务：

| 工具 | 描述 | |------|-------------| | search_services | 对柏林服务进行高级搜索，支持分页和过滤。 | | get_service_details | 获取服务的完整详细信息，包括表单和先决条件。 | | get_service_forms | 获取与服务相关的所有表单及其详细元数据。 | | search_forms | 在所有服务中搜索表单。 | | get_forms_by_type | 获取所有服务中特定类型的表单。 | | get_service_prerequisites | 获取服务的所有先决条件和要求。 | | get_service_checklist | 获取完成服务申请的综合清单。 | | analyze_form_for_filling | 下载PDF表单并提取其可填写字段。 | | perform_form_filling | 填写PDF表单并保存到本地。 | | download_filled_form | 获取填写好的PDF表单。 | | get_form_visual_preview | 将填写好的PDF的某一页渲染为图像。 | | open_file_locally | 在用户本地系统上打开文件（仅适用于本地设置）。 | | delete_filled_form | 手动从服务器删除填写好的表单。 | | browse_services_by_category | 按类别浏览服务。 | | find_online_services | 查找所有在线可用的服务。 | | get_service_locations | 获取服务的所有地点。 | | get_api_status | 获取API和缓存状态诊断信息。 | | clear_cache | 清除服务缓存并强制刷新。 |

⚠️ 重要提示

在远程服务器上填写的PDF表单应下载后使用 delete_filled_form 工具删除，以确保数据隐私。