Ikuzo

Ikuzo 是一款地图与旅行规划应用，通过 MCP（基于 HTTP POST 的 JSON-RPC 2.0）访问。

连接方式

端点（Endpoint）：https://ikuzo.app/api/mcp  
认证（Auth）：Bearer token（来自 TOOLS.md 或用户配置）  
协议（Protocol）：JSON-RPC 2.0 — 发送 POST 请求，请求体为：  
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"","arguments":{...}}}

工具列表

地图（Maps）

• maps_list — 列出所有地图（包括本人拥有及共享的地图）
• maps_get(mapId) — 获取指定地图的详细信息
• maps_create(title) — 创建一张新的空地图，返回含 mapId 的地图对象

地点（Spots）

• spots_list(mapId, ...) — 列出或筛选某张地图中的地点。支持的筛选参数包括：status[]、type[]、period[]、momentFrom/To、text、limit、offset、fields[]
• spots_get(spotId) — 获取指定地点的详细信息
• spots_create(mapId, title, gps{lat,lng}, ...) — 创建地点。可选参数包括：description、type、status、period[]、moment{date, repeat, reminder[]}
• spots_update(spotId, ...) — 更新任意字段（包括 moment、rating 等）
• spots_delete(spotId) — 软删除（可恢复）
• spots_nearby(lat, lng, ...) — 在所有可访问地图中查找指定坐标附近的地点。可选参数：radius（单位：km，默认 10，最大 500）、mapIds[]，以及全部地点筛选参数。结果按距离升序排列。
• spots_box(north, south, east, west, ...) — 在指定地理边界框内查找地点。支持的筛选参数与 spots_nearby 相同。

旅行计划（Travel Plans）

• travels_list — 列出所有旅行计划
• travels_get(travelId) — 获取指定旅行计划及其行程步骤
• travels_create(title) — 创建旅行计划
• travels_update(travelId, title) — 重命名旅行计划
• travels_delete(travelId) — 删除旅行计划

行程步骤（Steps，属于某旅行计划内）

• steps_add(travelId, type, ...) — 添加步骤。type="spot" 时需提供 spotId；type="day" 时需提供 title。可选参数：orderKey
• steps_update(stepId, ...) — 更新步骤位置或标题
• steps_delete(stepId) — 移除该步骤

工具类（Utility）

• ping — 测试连接是否正常
• schema — 获取 type、status、period 等字段的有效取值
• quota — 查询当前 API 使用配额（该调用不计入配额）

Schema 参考文档

有效地点类型（type）、状态（status）和周期（period）详见 references/schema.md。若运行时不确定取值，可直接调用 schema 工具获取。

常用模式

查找附近待访问的地点

spots_nearby(lat, lng, radius=20, status=["a","b"])

状态码 a 表示 “Ikuzo!”（高优先级），b 表示 “To Visit”（待访问）

查找具有即将发生时间点的季节性地点

spots_list(mapId, momentFrom="2026-03-01", momentTo="2026-04-30")

创建旅行行程单

1. travels_create(title) → 获取 travelId
2. steps_add(travelId, type="day", title="Day 1 - Arrival")
3. 对每个地点执行：steps_add(travelId, type="spot", spotId="...")
4. 为每一天重复添加“日期分隔步骤（type="day"）”与对应地点步骤

高效查询（减少 token 消耗）

使用 fields 参数仅请求所需字段：

spots_list(mapId, fields=["_id","title","gps","status","type"])

图片 URL 格式

地点图片托管于 Ikuzo 的 CDN：

https://ik.offbeatjapan.org/ikuzo/{imageId}.{ext}?tr=h-{height},w-{width}

其中 imageId 和 ext 来自地点对象的 image[] 数组。