| 1 |
# go-mcp |
| 2 |
|
| 3 |
An MCP server that exposes GoingsOn's tasks and projects to an LLM pair. It lets |
| 4 |
a Claude session create and query tasks directly instead of round-tripping |
| 5 |
through the CSV import wizard. The primary consumer is the `/dellm` skill, which |
| 6 |
migrates scattered todo backlogs into GoingsOn. |
| 7 |
|
| 8 |
Built on [kberg](../../../../MNW/shared/kberg) (`ToolRegistry` + Streamable HTTP |
| 9 |
MCP server). go-mcp opens the same `goingson.db` the desktop app uses and writes |
| 10 |
through the normal repository layer, so the sync-changelog triggers fire and a |
| 11 |
running GoingsOn stays consistent. It is a peer writer, never a back door. |
| 12 |
|
| 13 |
## Run |
| 14 |
|
| 15 |
``` |
| 16 |
go-mcp [--db <path>] [--host <ip>] [--port <n>] |
| 17 |
[--grant <cap>]... | [--grant-all] [--compact] |
| 18 |
``` |
| 19 |
|
| 20 |
- `--db` defaults to the desktop app's database (`com.goingson.app`'s |
| 21 |
`app_data_dir`). The database must already exist — run GoingsOn once to create |
| 22 |
the schema and the single desktop user. |
| 23 |
- Reads (`list_projects`, `list_tasks`, `get_task`) are always callable. |
| 24 |
- Writes are refused unless their capability is granted. Grant them with |
| 25 |
`--grant go.task.bulk_import` (repeatable) or `--grant-all` for a fully-trusted |
| 26 |
local session. |
| 27 |
- `--compact` serves only the small-model-safe surface (the read tools). |
| 28 |
|
| 29 |
Default bind is `127.0.0.1:7337`; the MCP endpoint is `POST /mcp`. |
| 30 |
|
| 31 |
## Tools |
| 32 |
|
| 33 |
Read: |
| 34 |
|
| 35 |
- `list_projects` — id, name, type, status. |
| 36 |
- `list_tasks(project?, status?, tag?, limit?, offset?)` — compact task rows, |
| 37 |
paged (default 50, max 200). Descriptions over 240 chars are clipped and the |
| 38 |
row marked `truncated`; `get_task` has the full text. The reply carries |
| 39 |
`total` and, while pages remain, `next_offset` — walk until it is absent. |
| 40 |
- `get_task(id)` — one task with subtasks and annotations. |
| 41 |
|
| 42 |
Write (each gated on a capability id): |
| 43 |
|
| 44 |
|
| 45 |
|
| 46 |
| `create_project(name, type?, description?)` — idempotent on name | `go.project.create` | |
| 47 |
| `update_project(project, {status?, type?, description?})` — resolved by name, overlays only the fields you pass | `go.project.update` | |
| 48 |
| `create_task({description, project?, tags?, due?, priority?})` | `go.task.create` | |
| 49 |
| `bulk_import_tasks([...])` — the `/dellm` primitive | `go.task.bulk_import` | |
| 50 |
| `update_task(id, fields)` — overlays only the fields you pass | `go.task.update` | |
| 51 |
| `complete_task(id)` | `go.task.complete` | |
| 52 |
|
| 53 |
`bulk_import_tasks` dedupes on a `source:` provenance tag (e.g. |
| 54 |
`source:todo.md:42`), so re-running a migration wave does not double-insert. |
| 55 |
Projects referenced by name are resolved, and created if absent. |
| 56 |
|
| 57 |
`update_project` is how a session retires a project: set `status` to `Archived`. |
| 58 |
There is no `delete_project` — the underlying delete is a hard DELETE with no |
| 59 |
soft-delete behind it, which is the wrong default to hand a session. Renaming is |
| 60 |
not offered either, since the name is how `create_task` and `bulk_import_tasks` |
| 61 |
resolve a project. |
| 62 |
|
| 63 |
Enum values are the same words in and out (`SideProject`, `OnHold`), not the |
| 64 |
UI's display forms (`Side Project`, `On Hold`), so a row from `list_projects` |
| 65 |
can be fed straight back to `update_project`. An unknown word is refused rather |
| 66 |
than defaulted. |
| 67 |
|
| 68 |
## Wiring into a Claude session |
| 69 |
|
| 70 |
Register the running server as an HTTP MCP server, then grant the capabilities |
| 71 |
`/dellm` needs: |
| 72 |
|
| 73 |
``` |
| 74 |
go-mcp --grant-all & |
| 75 |
claude mcp add --transport http go-mcp http://127.0.0.1:7337/mcp |
| 76 |
``` |
| 77 |
|
| 78 |
`/dellm` detects go-mcp among the available MCP tools and uses it for |
| 79 |
`bulk_import_tasks`; without it, the skill falls back to CSV import. |
| 80 |
|
| 81 |
## Design |
| 82 |
|
| 83 |
`_private/docs/goingson/plans/go-mcp-design.md`. |
| 84 |
|