Gingerguide: European city walking tours

Gingerguide MCP 服务和 Agent 技能

**Gingerguide 是一款适用于 iPhone 和 Android 的自助式语音导览应用。**它覆盖 39 个国家的 169 座欧洲城市和 3,100 多处配有讲解的景点。每处景点都有一段经过研究、时长 2 至 3 分钟的故事，由逼真的 AI 语音朗读，支持英语、西班牙语、法语、德语、土耳其语和中文。各城市的内容均可完全离线使用。

此仓库让 AI 助手和 Agent 能够使用 Gingerguide 目录。内容包括：

• 公共 Gingerguide MCP 服务（地址为 https://gingerguide.app/mcp）的连接详情。其 14 个工具可按兴趣、历史时期或位置查找景点，推荐景点和城市、比较城市、查找一日游行程、提供实用的游览信息，并规划徒步游览路线和多日行程，支持六种语言。
• 两项用于查询语音导览和规划一日城市步行游的 Agent 技能（SKILL.md 格式）。
• 可直接复制的 客户端配置和 curl 示例。

此服务为只读服务，无需 API 密钥或登录。可选的免费 API 密钥可提高每日限额（参见可选的免费 API 密钥）。

MCP 端点	https://gingerguide.app/mcp
传输方式	Streamable HTTP（无状态，JSON 响应）
身份验证	无需身份验证（可选的免费 API 密钥）
MCP 注册表名称	app.gingerguide/catalog
开发者文档	https://gingerguide.app/developers/
OpenAPI（REST）	https://gingerguide.app/api/openapi.json
llms.txt	https://gingerguide.app/llms.txt

可选的免费 API 密钥

此服务无需密钥即可使用。不使用密钥时，每个 UTC 日每个 IP 地址可调用工具 1,000 次。Claude 和 ChatGPT 等托管助手会通过少数几个共享 IP 地址发出请求，因此每个 IP 地址每天可调用 50,000 次。免费密钥可将限额提高至每个密钥每天调用工具 20,000 次，并显示使用量。如果你的 Agent 运行在共享云环境（Vercel、AWS、Cloudflare）中，此密钥会很有用。只有 tools/call 会计入限额。无需注册，也无需提供电子邮件。

# Create a key (it is shown once; the server stores only its hash)
curl -sS -X POST https://gingerguide.app/api/keys \
  -H 'content-type: application/json' -d '{"label":"my-agent"}'

# Use it
curl -sS https://gingerguide.app/mcp \
  -H 'authorization: Bearer ggk_...' \
  -H 'content-type: application/json' -H 'accept: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Usage for the last 30 days, and revoke
curl -sS https://gingerguide.app/api/keys/me -H 'authorization: Bearer ggk_...'
curl -sS -X DELETE https://gingerguide.app/api/keys/me -H 'authorization: Bearer ggk_...'

你也可以通过 X-API-Key 发送密钥。未知或已撤销的密钥会收到 HTTP 401。移除该请求头即可继续无密钥使用。工具调用响应会携带 RateLimit 和 X-RateLimit-Remaining 请求头。详情：https://gingerguide.app/developers/#api-key。

工具

所有工具均为只读（readOnlyHint: true），并接受 language 参数：en、es、fr、de、tr 或 zh。

查找

工具	功能	主要参数
search_attractions	按自由文本、类别、兴趣、历史时期、室内或室外、游览时长、是否免费入场或距某地点的距离，搜索所有城市或某个城市的景点。例如：伊斯坦布尔的五处拜占庭景点。	query、city_id、country、categories、interests、periods、setting、free_only、near_lat、near_lng、radius_km、sort、limit
find_nearby_attractions	返回距离某个纬度和经度最近的景点，并附上步行分钟数。如果半径范围内没有景点，则返回最近的已收录城市。	lat、lng、radius_km、interests、categories、pace
get_attraction	返回一处景点的信息：详细介绍、值得一提的事实、照片、坐标、地图链接、游览时间以及最近的其他景点。在已调研的城市中，还会提供门票、预订信息、每周闭馆日、着装要求和官方网站。	attraction_id（例如 rome-colosseum）
get_visit_info	提供某个城市的实用信息：最佳月份和游客高峰期、从机场、主要车站或邮轮港口前往市中心的方式、城市通票、免费景点、需要提前预订的项目、每周闭馆日和着装要求。每条信息都附有来源和核查日期。目前仅适用于已调研的城市（罗马、巴塞罗那和维也纳）；对于其他城市，会说明这一点。	city_id、topics
search_cities	按名称（支持六种语言中的任意一种）、国家或地区查找城市。返回其他工具所需的城市 ID。	query、country、limit
get_city_guide	返回某个城市的信息：概览、知名景点、鲜为人知的景点，以及每处景点的类别、坐标和游览时间。detail: "full" 会补充每处景点的详细介绍。	city_id、detail
list_countries	列出已收录的国家及其城市 ID。	无
get_catalog_overview	返回收录范围统计、支持的语言，以及 categories、interests 和 periods 筛选器接受的所有确切值。	无

推荐

工具	功能	主要参数
recommend_attractions	根据旅行者的兴趣、偏爱的历史时期、知名景点或隐藏瑰宝、室内或室外偏好以及可用时间，为某个城市挑选景点。每项推荐都会说明入选原因。	city_id、interests、periods、style、setting、available_minutes、exclude_ids
recommend_destinations	根据兴趣或历史时期为城市排名，例如“最适合了解拜占庭历史的城市”，并说明推荐原因。	interests、periods、country、trip_days
compare_cities	并排比较 2 至 4 个城市：景点、所需天数、最突出的兴趣和历史时期、室内景点占比、知名景点以及城市间的距离。还会指出每个城市在哪种兴趣或历史时期方面更具优势。	city_ids、interests、periods、trip_days
find_day_trips	列出适合从某个出发城市进行一日游的已收录城市，并按距离、兴趣和知名度排序，同时说明一天内可以游览哪些内容。不包含需要乘飞机的海上航线；短途渡轮会特别标注。	city_id、max_distance_km、interests、periods、hours_on_site

规划

工具	功能	主要参数
plan_walking_tour	为单个城市规划适合指定时间预算的步行路线。返回每个停靠点的步行分钟数、游览时间、具体时刻和 Google Maps 步行路线链接。	city_id、duration_minutes、interests、periods、style、pace、start_lat、start_lng 或 start_attraction_id、start_time、must_include、weekday
plan_trip_itinerary	规划在单个城市游览 1 到 7 天的行程。每天游览一个或两个适合步行的区域，区域之间乘坐一次公共交通。	city_id、days、hours_per_day、interests、periods、style、pace、start_time、start_weekday

筛选值。 兴趣：history、architecture、art、museums、religious_sites、archaeology、nature、views、food、local_life、shopping、relaxing、royalty、military、music、literature、science、performing_arts、memorials。时期：prehistoric、ancient_greek、etruscan、roman、byzantine、medieval、gothic、moorish_islamic、ottoman、renaissance、baroque、georgian_neoclassical、nineteenth_century、art_nouveau、twentieth_century_modern、world_war_ii、cold_war。风格：must_see、balanced、hidden_gems。节奏：relaxed、normal、brisk。

数据限制。 兴趣、时期以及室内或室外属性，根据每个景点的类别和描述推导得出。步行时间为估算值（直线距离 x 1.3，按所选节奏计算）。一日游和对比距离均为直线距离，不包含出行时间。在经过调研的城市中，使用 weekday 时，规划器会排除当天闭馆或暂时关闭的景点。不包含开放时间和门票价格。输入无效时会返回错误，并列出允许的值。

连接客户端

Claude Code

claude mcp add --transport http gingerguide https://gingerguide.app/mcp

Claude（桌面版和网页版）

打开 Settings → Connectors → Add custom connector。将名称设为 Gingerguide，URL 设为 https://gingerguide.app/mcp。

对于只读取 claude_desktop_config.json 的旧版 Claude Desktop，请使用 examples/claude_desktop_config.json 中的桥接配置。

Cursor

将以下内容添加到 ~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）。文件：examples/cursor-mcp.json。

{
  "mcpServers": {
    "gingerguide": { "url": "https://gingerguide.app/mcp" }
  }
}

VS Code（GitHub Copilot Agent 模式）

将以下内容添加到 .vscode/mcp.json。文件：examples/vscode-mcp.json。

{
  "servers": {
    "gingerguide": { "type": "http", "url": "https://gingerguide.app/mcp" }
  }
}

ChatGPT

在支持自定义连接器的工作区或方案中（开发者模式），添加一个新连接器，URL 为 https://gingerguide.app/mcp，无需身份验证。

其他客户端

任何支持远程 Streamable HTTP 服务的 MCP 客户端都可以连接到 https://gingerguide.app/mcp。原始 JSON-RPC 调用请参阅 examples/curl.md。

示例提示词

• “找出伊斯坦布尔的 5 个拜占庭历史景点。”
• “规划罗马两小时的历史步行游览，10:00 出发。”
• “我住在维也纳圣斯德望主教座堂附近。10 分钟内步行可以到哪些地方？”
• “为艺术和音乐爱好者规划维也纳三日游。”
• “哪些欧洲城市最适合了解拜占庭历史？”
• “从佛罗伦萨出发，有哪些不错的一日游？”
• “如何从奇维塔韦基亚邮轮港口前往罗马？需要预订什么？”
• “规划周日罗马的四小时艺术之旅。”
• “首次旅行选波尔图还是里斯本？请比较一下。”
• “为建筑爱好者推荐巴黎的隐藏瑰宝，最好是室内景点，因为正在下雨。”
• “用德语介绍斗兽场。”
• “塞维利亚有语音步行导览吗？”

Agent 技能

skills/ 文件夹中有两个采用 SKILL.md 格式的技能。Claude、Claude Code 和其他可读取此格式的 Agent 均可加载它们。

技能	适用于用户……
find-audio-walking-tour	请求某座城市的语音导览、徒步导览或自助导览
plan-city-day-with-gingerguide	请求某个覆盖城市的一日行程或步行路线

这些技能也通过网站提供，地址为 https://gingerguide.app/.well-known/agent-skills/index.json。

REST API（无需 MCP）

端点	返回内容
GET https://gingerguide.app/api/cities.json	所有城市及其 id、国家、景点数量和导览 URL
GET https://gingerguide.app/api/cities/{id}.json	一个城市及其所有景点
GET https://gingerguide.app/api/openapi.json	OpenAPI 描述

CLI

cli/ 文件夹中包含官方命令行客户端的源代码。它已发布到 npm，名称为 gingerguide。

npx gingerguide cities
npx gingerguide city rome
npx gingerguide countries
npx gingerguide health

Agent 规则

• 仅说明数据所确认的覆盖范围。不要编造导览或景点。
• 旁白是逼真的 AI 语音。不要称其为真人语音。
• 使用数据中的城市导览 URL 链接，例如 https://gingerguide.app/en/cities/rome/。

获取应用

• iPhone 和 iPad：App Store
• Android：Google Play
• 网页导览：gingerguide.app

许可证

此存储库中的文件（文档、配置、技能）采用 MIT License。服务器和 API 返回的目录数据归 Gingerguide 所有。请参阅条款。

有问题或遇到故障：请提交 issue，或发送邮件至 [email protected]。