ikuzo

# 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.