🚶‍♂️ Just Walking MCP (CityWalk 智能路线决策台)

这是一个基于 MCP (Model Context Protocol) 的智能 CityWalk 决策服务。 它充当“逻辑大脑”与“渲染引擎”，配合高德地图数据，为您生成包含 5种策略、真实步行路径 和 交互式决策面板 的可视化地图。

✨ 核心特性

• 双模架构：支持 Stdio (适配 Claude/Cursor 等 IDE) 和 SSE (独立 HTTP 服务) 两种启动模式。
• 五种游玩策略：
  • 🟥 特种兵 (Special Forces): 极限打卡，效率至上。
  • 💗 恋爱约会 (Couple): 浪漫氛围，慢节奏。
  • 🟩 独自闲逛 (Solo): 安静独处，享受时光。
  • 🟧 基友聚会 (Friends): 吃喝玩乐，边走边聊。
  • 🟪 姐妹拍照 (Photos): 一步一景，出片第一。
• 真实路径渲染：前端集成高德 Walking 引擎，绘制沿着街道弯曲的真实路线，拒绝生硬的直线。
• 全景决策台：生成的地图包含悬浮面板，展示天气、预算、所有候选点及方案对比，支持点击切换方案。
• 在线交付：自动将生成的 HTML 地图上传至您的 Pastebin 服务，直接返回 HTTP 访问链接。

📦 安装

无需安装，建议直接使用 npx 运行：

npx @suenal/just-walking-mcp

或者全局安装：

npm install -g @suenal/just-walking-mcp

⚙️ 前置准备

• 在使用本服务前，您需要准备以下密钥和服务：
• 高德地图 Web 端 (JS API) Key：用于前端地图渲染 (必填)。
• 高德地图安全密钥 (Security Code)：与 JS Key 配套的安全密钥 (必填)。
• Pastebin 服务：用于托管生成的 HTML 地图。
  • 需提供一个 API 接口 (如 http://your-server/publish)。
  • 接受 POST 请求，Body 为纯文本 (HTML)。
  • 返回 JSON: { "url": "http://your-server/abc1234" }。

🚀 使用指南

在 灵码中配置 中配置 (推荐)

请在您的 MCP 配置文件中（如 claude_desktop_config.json），添加以下配置。

注意：本服务通常需要配合一个 数据层 MCP (如 amap-mcp) 使用，由数据层提供 POI 搜索能力，本服务负责逻辑规划和渲染。

  {
    "mcpServers": {
      "just-walking": {
        "command": "npx",
        "args": [
          "-y",
          "@suenal/just-walking-mcp"
        ],
        "env": {
          "AMAP_JS_KEY": "您的_AMAP_JS_KEY",
          "AMAP_SECURITY_CODE": "您的_AMAP_SECURITY_CODE",
          "PASTEBIN_API_URL": "http://您的Pastebin接口地址/publish"
        }
      }
    }
  }

本地调试 (SSE 模式)

如果您想作为独立 Web 服务运行进行调试，可以使用 --sse 参数启动：

# 启动 SSE 服务 (默认端口 3000)
npx @suenal/just-walking-mcp --sse

🛠️ 环境变量说明

| 变量名 | 必填 | 描述 | | ------------------ | --- | ---------------------------------- | | AMAP_JS_KEY | ✅ | 高德地图 Web 端 (JS API) Key。 | | AMAP_SECURITY_CODE | ✅ | 高德地图 JS API 安全密钥。 | | PASTEBIN_API_URL | ✅ | HTML 上传接口，用于生成在线链接。 | | MCP_MODE | ❌ | 设为 sse 可强制以 SSE 模式启动 (同 --sse 参数)。 |

CityWalk 规划师工作流

1. 数据采集: 调用数据层工具 (如 maps_around_search) 获取目标地点周围 50+ 个 POI。
2. 全局规划: 调用本服务的 plan_all_routes 工具。
   • 传入所有候选点。
   • 指定用户偏好策略 (solo/couple/friends/special_forces/photos)。
3. 可视化: 调用本服务的 render_dashboard_html 工具。
   • 工具会自动上传并返回链接。
   • 直接向用户展示返回的 HTTP 链接，无需输出代码块。

🏗️ 依赖技术栈

• Node.js & Express: 服务端运行时。

• @modelcontextprotocol/sdk: MCP 协议实现。

• AMap JS API v2.0: 高德地图前端渲染与 Walking 路径规划。

• Zod: 参数校验。

📄 License

ISC

Author: suenal