# go-mcp

An MCP server that exposes GoingsOn's tasks and projects to an LLM pair. It lets
a Claude session create and query tasks directly instead of round-tripping
through the CSV import wizard. The primary consumer is the `/dellm` skill, which
migrates scattered todo backlogs into GoingsOn.

Built on [kberg](../../../../MNW/shared/kberg) (`ToolRegistry` + Streamable HTTP
MCP server). go-mcp opens the same `goingson.db` the desktop app uses and writes
through the normal repository layer, so the sync-changelog triggers fire and a
running GoingsOn stays consistent. It is a peer writer, never a back door.

## Run

```
go-mcp [--db <path>] [--host <ip>] [--port <n>]
       [--grant <cap>]... | [--grant-all] [--compact]
```

- `--db` defaults to the desktop app's database (`com.goingson.app`'s
  `app_data_dir`). The database must already exist — run GoingsOn once to create
  the schema and the single desktop user.
- Reads (`list_projects`, `list_tasks`, `get_task`) are always callable.
- Writes are refused unless their capability is granted. Grant them with
  `--grant go.task.bulk_import` (repeatable) or `--grant-all` for a fully-trusted
  local session.
- `--compact` serves only the small-model-safe surface (the read tools).

Default bind is `127.0.0.1:7337`; the MCP endpoint is `POST /mcp`.

## Tools

Read:

- `list_projects` — id, name, type, status.
- `list_tasks(project?, status?, tag?, limit?, offset?)` — compact task rows,
  paged (default 50, max 200). Descriptions over 240 chars are clipped and the
  row marked `truncated`; `get_task` has the full text. The reply carries
  `total` and, while pages remain, `next_offset` — walk until it is absent.
- `get_task(id)` — one task with subtasks and annotations.

Write (each gated on a capability id):

| Tool | Capability |
|------|------------|
| `create_project(name, type?, description?)` — idempotent on name | `go.project.create` |
| `update_project(project, {status?, type?, description?})` — resolved by name, overlays only the fields you pass | `go.project.update` |
| `create_task({description, project?, tags?, due?, priority?})` | `go.task.create` |
| `bulk_import_tasks([...])` — the `/dellm` primitive | `go.task.bulk_import` |
| `update_task(id, fields)` — overlays only the fields you pass | `go.task.update` |
| `complete_task(id)` | `go.task.complete` |

`bulk_import_tasks` dedupes on a `source:` provenance tag (e.g.
`source:todo.md:42`), so re-running a migration wave does not double-insert.
Projects referenced by name are resolved, and created if absent.

`update_project` is how a session retires a project: set `status` to `Archived`.
There is no `delete_project` — the underlying delete is a hard DELETE with no
soft-delete behind it, which is the wrong default to hand a session. Renaming is
not offered either, since the name is how `create_task` and `bulk_import_tasks`
resolve a project.

Enum values are the same words in and out (`SideProject`, `OnHold`), not the
UI's display forms (`Side Project`, `On Hold`), so a row from `list_projects`
can be fed straight back to `update_project`. An unknown word is refused rather
than defaulted.

## Wiring into a Claude session

Register the running server as an HTTP MCP server, then grant the capabilities
`/dellm` needs:

```
go-mcp --grant-all &
claude mcp add --transport http go-mcp http://127.0.0.1:7337/mcp
```

`/dellm` detects go-mcp among the available MCP tools and uses it for
`bulk_import_tasks`; without it, the skill falls back to CSV import.

## Design

`_private/docs/goingson/plans/go-mcp-design.md`.