ikuzo

在 Ikuzo (ikuzo.app)（一款基于位置的探索应用程序）上管理地图、景点和旅行计划。在创建/编辑地图、添加/搜索景点、规划每日行程、查找附近地点或管理旅行物流时使用。触发地图管理、地点跟踪、旅行计划、位置发现和“我应该去哪里”问题。

# Ikuzo

Ikuzo is a map & travel planning app. Access via MCP (JSON-RPC 2.0 over HTTP POST).

## Connection

```
Endpoint: https://ikuzo.app/api/mcp
Auth: Bearer token (from TOOLS.md or user config)
Protocol: JSON-RPC 2.0 — POST with {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"<tool>","arguments":{...}}}
```

## Tools

### Maps
- `maps_list` — list all maps (owned + shared)
- `maps_get(mapId)` — get map details
- `maps_create(title)` — create a new empty map, returns map with ID

### Spots
- `spots_list(mapId, ...)` — list/filter spots in a map. Filters: `status[]`, `type[]`, `period[]`, `momentFrom/To`, `text`, `limit`, `offset`, `fields[]`
- `spots_get(spotId)` — get spot details
- `spots_create(mapId, title, gps{lat,lng}, ...)` — create spot. Optional: `description`, `type`, `status`, `period[]`, `moment{date, repeat, reminder[]}`
- `spots_update(spotId, ...)` — update any field (including `moment`, `rating`)
- `spots_delete(spotId)` — soft delete (recoverable)
- **`spots_nearby(lat, lng, ...)`** — find spots near a point across ALL accessible maps. Optional: `radius` (km, default 10, max 500), `mapIds[]`, all spot filters. Returns sorted by distance.
- `spots_box(north, south, east, west, ...)` — find spots in bounding box. Same filters as nearby.

### Travel Plans
- `travels_list` — list all travel plans
- `travels_get(travelId)` — get plan with steps
- `travels_create(title)` — create plan
- `travels_update(travelId, title)` — rename plan
- `travels_delete(travelId)` — delete plan

### Steps (within a travel plan)
- `steps_add(travelId, type, ...)` — add step. `type="spot"` requires `spotId`, `type="day"` requires `title`. Optional: `orderKey`
- `steps_update(stepId, ...)` — update position or title
- `steps_delete(stepId)` — remove step

### Utility
- `ping` — test connection
- `schema` — get valid values for `type`, `status`, `period`
- `quota` — check API usage (doesn't count against quota)

## Schema Reference

See `references/schema.md` for valid spot types, statuses, and periods. Call `schema` tool at runtime if unsure.

## Key Patterns

### Find spots to visit nearby
```
spots_nearby(lat, lng, radius=20, status=["a","b"])
```
Status `a` = "Ikuzo!" (priority), `b` = "To Visit"

### Seasonal spots with upcoming moments
```
spots_list(mapId, momentFrom="2026-03-01", momentTo="2026-04-30")
```

### Create a trip itinerary
1. `travels_create(title)` → get travelId
2. `steps_add(travelId, type="day", title="Day 1 - Arrival")`
3. `steps_add(travelId, type="spot", spotId="...")` for each spot
4. Repeat day dividers + spots for each day

### Efficient listing (reduce tokens)
Use `fields` to request only what you need:
```
spots_list(mapId, fields=["_id","title","gps","status","type"])
```

### Image URLs
Spot images use Ikuzo's CDN:
```
https://ik.offbeatjapan.org/ikuzo/{imageId}.{ext}?tr=h-{height},w-{width}
```
Where `imageId` and `ext` come from the spot's `image[]` array.

---

## 中文说明

# Ikuzo

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

## 连接

```
Endpoint: https://ikuzo.app/api/mcp
Auth: Bearer token (from TOOLS.md or user config)
Protocol: JSON-RPC 2.0 — POST with {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"<tool>","arguments":{...}}}
```

## 工具

### 地图（Maps）
- `maps_list` — 列出所有地图（自有 + 共享）
- `maps_get(mapId)` — 获取地图详情
- `maps_create(title)` — 创建一个新的空地图，返回带 ID 的地图

### 景点（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`（公里，默认 10，最大 500）、`mapIds[]`、所有景点筛选条件。返回结果按距离排序。
- `spots_box(north, south, east, west, ...)` — 在边界框内查找景点。筛选条件与 nearby 相同。

### 旅行计划（Travel Plans）
- `travels_list` — 列出所有旅行计划
- `travels_get(travelId)` — 获取含步骤的计划
- `travels_create(title)` — 创建计划
- `travels_update(travelId, title)` — 重命名计划
- `travels_delete(travelId)` — 删除计划

### 步骤（旅行计划中的步骤）
- `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 参考

有关有效的景点类型、状态和时段，请参阅 `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. 为每一天重复添加日期分隔符 + 景点

### 高效列出（减少 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[]` 数组。