MCP Server Project (Proof of Concept)

BayernCloud MCP 服务

一个 Model Context Protocol (MCP) 服务，可向 Claude 等 AI 助手提供 BayernCloud Tourismus API。为巴伐利亚旅游数据提供搜索、筛选和地理工具，涵盖活动、游览路线、POI 和餐饮。

工具

搜索

工具	说明
search_events	按地理半径、日期范围、全文和分类搜索活动
search_tours	搜索游览路线，可按长度、爬升高度（Höhenmeter）、时长和环线筛选
search_pois	按地理位置、全文和分类搜索兴趣点
search_gastronomy	按地理位置、全文和分类搜索餐厅、咖啡馆和酒吧

详情

工具	说明
get_item	根据 UUID 获取任意项目的完整详情
get_elevation_profile	获取游览路线的高程剖面（Höhenprofil）

分类

工具	说明
list_classification_trees	获取所有可用的分类树（缓存 30 分钟）
get_classifications	获取分类树中的类别 — 使用 ID 筛选搜索结果

实用工具

工具	说明
suggest	为活动、游览路线或 POI 提供标题自动补全
geocode	地址 → 坐标
reverse_geocode	坐标 → 地址
route_distance	计算两点之间的驾车距离（OSRM）
haversine_distance	计算两点之间的直线距离

设置

前提条件

• Node.js v18+
• BayernCloud Tourismus API 令牌 — 前往 bayerncloud.digital 获取

安装

git clone <repo>
cd mcp-server
npm install
npm run build

配置

将 .env.example 复制为 .env 并填写相应值：

BCT_API_TOKEN=your_token_here
BAYERN_CLOUD_API_URL=https://data.bayerncloud.digital/api/v4

# Endpoint UUIDs — copy from the end of the endpoint URL in the BayernCloud portal
BCT_ENDPOINT_EVENTS=107df2c2-ff3e-4eaa-b24c-863d85d505d1
BCT_ENDPOINT_TOURS=cd177e6a-c6db-4efd-84a6-decf4a3711de
BCT_ENDPOINT_POIS=7b228c8c-23f5-49b9-b55e-e18e73386fbb
BCT_ENDPOINT_GASTRONOMY=5453abda-5e76-43f0-acdf-4855c3cb351e

# Geocoding (optional — defaults shown)
NOMINATIM_BASE_URL=https://nominatim.openstreetmap.org
OSRM_BASE_URL=http://router.project-osrm.org

使用方法

本地运行（Claude Desktop）

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "bayerncloud-mcp": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/index.js"]
    }
  }
}

公共 HTTP 服务

该服务也可作为公共 HTTP 端点运行（使用 Streamable HTTP 传输，每个 IP 的速率限制为每分钟 60 个请求）：

PORT=3000 npm run start:http

端点：

• POST /mcp — MCP 端点
• GET /health — 健康检查

将其作为远程 MCP 服务添加到 Claude：

{
  "mcpServers": {
    "bayerncloud-mcp": {
      "type": "http",
      "url": "https://your-deployment.example.com/mcp"
    }
  }
}

部署到 Railway

npm run build
railway login && railway init && railway up

在 Railway 控制面板中设置 .env 中的相同环境变量。PORT 会自动设置。

开发

npm run build      # compile TypeScript → dist/
npm run start      # run stdio server (local)
npm run start:http # run HTTP server (public)
npm run dev        # watch mode

架构

src/
  index.ts          # stdio entry point (Claude Desktop)
  server-http.ts    # HTTP entry point (public deployment)
  lib/
    create-server.ts  # registers all tools on an McpServer instance
    bct.ts            # BayernCloud API client
    config.ts         # environment variables + dotenv
    format.ts         # response formatters (strips JSON-LD overhead)
    cache.ts          # TTL cache for classification data
    nominatim.ts      # Nominatim + OSRM client
  tools/
    events.ts         # search_events
    tours.ts          # search_tours
    pois.ts           # search_pois
    gastronomy.ts     # search_gastronomy
    item.ts           # get_item
    elevation.ts      # get_elevation_profile
    classifications.ts # list_classification_trees, get_classifications
    suggest.ts        # suggest
    geocoding.ts      # geocode, reverse_geocode, route_distance, haversine_distance

无论本地还是公共部署，BCT API 令牌都不会暴露给客户端，而是保留在服务端。

许可证

MIT