Taiwan Garbage Truck Map

台湾垃圾车地图 — MCP 服务

只读的模型上下文协议服务，为 garbage.yukai.dev 提供垃圾车数据集。基于 mcp-handler 2.x 和 @modelcontextprotocol/server 2.x 构建，提供单一无状态的 Streamable HTTP 端点，支持 MCP 协议版本 2025-11-25、2025-06-18 和 2025-03-26。

服务复用 Web 应用的城市适配器（../src/cities），确保网站和 MCP 响应中的字段映射一致。数据从已发布的 JSON 文件获取（DATA_BASE_URL，默认值为 https://garbage.yukai.dev），并在每个热实例的内存中缓存一小时。城市数据按需延迟加载（注意：台中的数据集约为 50 MB，冷加载需约 1 秒，内存中的 RSS 约为 400 MB）。

工具

工具	用途
list_cities	列出支持的城市、其 ID 和地理边界框
find_nearby_points	查找指定坐标 50–2,000 m 范围内的站点，按距离从近到远排序
search_points	按行政区、村里、道路或路线关键词搜索城市中的站点
get_schedule	获取一个站点及其路线上的所有站点，并按到达顺序排列

所有工具均标注为只读，并会在返回纯文本摘要的同时返回 structuredContent。所有时间均使用 Asia/Taipei。

对于新北和台中（其开放数据包含平日班次），每个站点都包含每周的 schedule（collectionType → ISO 星期，1=周一 … 7=周日）以及根据台湾时间计算的 servesToday 布尔值。台北和高雄不发布平日班次，因此不提供这些字段。与 Web 应用中台中的默认“仅今天”视图不同，MCP 服务会以 allDays 模式加载适配器，让 Agent 能够回答一周中任何一天的问题。

开发

cd mcp
bun install
bun test            # query logic + adapter schedule tests
bun run typecheck
bun dev.ts          # http://localhost:3939/api/mcp

使用 MCP Inspector 进行交互式测试：

npx @modelcontextprotocol/inspector

然后连接到 http://localhost:3939/api/mcp。

部署（Vercel）

此目录作为独立的 Vercel 项目（taipei-trash-mcp）部署，与 GitHub Pages 上的 Web 应用分开。无服务器函数在构建时使用 esbuild 打包（bun run build → api/mcp.js），以便 ../src/cities 中不带扩展名的 TypeScript 导入能在 Node ESM 中正常解析。

从仓库根目录部署（.vercelignore 可将上传内容保持精简）：

1. 在 Vercel 中导入仓库，并将 Root Directory 设为 mcp。
2. 保持启用 Include source files outside of the Root Directory（默认设置），以便构建过程可以导入 ../src/cities。
3. 添加自定义域名（vercel api /v10/projects/<id>/domains -X POST -F name=mcp.garbage.yukai.dev），并在 DNS 服务商处配置 CNAME 和 _vercel TXT 记录。
4. 可选环境变量：DATA_BASE_URL、MCP_ALLOWED_ORIGINS（以逗号分隔的浏览器客户端允许列表）。
5. 通过 Vercel Firewall 规则实施速率限制（mcp-rate-limit：针对 /api/mcp 和 /mcp，每个 IP 每分钟 60 个请求）。

生产端点：**https://mcp.garbage.yukai.dev/mcp**（也可通过 /api/mcp 访问；备用地址为 https://taipei-trash-mcp.vercel.app）。对于仅支持 stdio 的客户端，请使用 npx mcp-remote https://mcp.garbage.yukai.dev/mcp。

发现端点

• /mcp/server-card — MCP Server Card（SEP-2127），以 application/mcp-server-card+json 格式从 public/server-card.json 提供。
• /.well-known/ai-catalog.json — AI Catalog 条目，指向 Server Card（也托管在 https://garbage.yukai.dev）。
• /llms.txt — 面向大模型的纯文本指南。

目录列表

• server.json — 此仅限远程服务的官方 MCP Registry 清单。它与 public/server-card.json 保持一致（name、version、title、description、repository 和远程 URL 相同），确保两者始终一致。

• 使用官方 CLI 发布（命名空间 dev.yukai/* 需要通过 DNS 或 HTTP 验证 yukai.dev——GitHub OAuth 仅授予 io.github.*/*）：

  mcp-publisher validate server.json
  mcp-publisher login dns --domain yukai.dev --private-key "$PRIVATE_KEY"
  mcp-publisher publish server.json
  

• 有关向官方注册表、Smithery、Glama、PulseMCP、mcp.so 和 awesome-remote-mcp-servers 提交的分步说明（包括要粘贴的内容以及手动账户／DNS 操作步骤），请参阅 docs/mcp-directory-submission.md。

安全说明

• 无需身份验证：所有底层数据都是公开的政府开放数据，并且所有工具都严格只读。
• Origin 检查：根据 MCP 传输规范，携带 Origin 标头的请求会被拒绝并返回 403，除非该来源列在 MCP_ALLOWED_ORIGINS 中。本机和服务器端客户端不会发送 Origin 标头。