# External MCP — CRUD Extensions

**Date:** 2026-04-25
**Status:** Approved

## Goal

Give a normal (non-planning) Claude CLI session full control over the ClaudeDo task inbox via the existing always-on `ExternalMcpService`. Primary use case: when a chat session produces scope-creep work, Claude can spin up a fully-formed task — title, description, tags (including the `agent` tag for auto-execution) — without leaving the session.

The work is purely additive: the `ExternalMcpService` endpoint is already wired, authenticated by the optional `X-ClaudeDo-Key` header, and exposes `ListTaskLists`, `ListTasks`, `GetTask`, `AddTask`, `UpdateTaskStatus`, `RunTaskNow`, `CancelTask`. Missing for "full CRUD" are tag handling, content updates, deletion, and tag discovery.

## Scope

| Tool | Status | Notes |
|---|---|---|
| `ListTaskLists` | exists | unchanged |
| `ListTasks` | exists | unchanged |
| `GetTask` | exists | unchanged |
| `AddTask` | extend | add optional `tags` parameter |
| `UpdateTaskStatus` | exists | unchanged (Manual ↔ Queued) |
| `RunTaskNow` | exists | unchanged |
| `CancelTask` | exists | unchanged |
| `UpdateTask` | new | patch title/description/commitType/tags |
| `DeleteTask` | new | delete a task (cascades) |
| `SetTaskTags` | new | replace the full tag set on a task |
| `ListTags` | new | enumerate all known tag names |

Out of scope:
- List CRUD (creating/renaming/deleting lists) — out of scope for this iteration; UI remains the source of truth for list management.
- ListConfig / agent settings overrides — handled by the UI, not surfaced via MCP here.
- Tag CRUD beyond auto-creation during `AddTask` / `UpdateTask` / `SetTaskTags`. There is no `DeleteTag` tool; tag rows live as long as some task references them.

## Authentication

No change. The endpoint continues to be gated by `ExternalMcpAuthMiddleware` — if `WorkerConfig.ExternalMcpApiKey` is set, callers must include `X-ClaudeDo-Key`; otherwise the loopback-only worker is open to local processes.

## Tool specifications

### `AddTask` (extended)

```
AddTask(
    listId: string,
    title: string,
    description: string?,
    createdBy: string,
    queueImmediately: bool,
    tags: string[]?,
    cancellationToken)
    -> TaskDto
```

Behavior:
- Existing behavior preserved. New `tags` parameter, when non-null, attaches the named tags to the new task.
- Tag names are matched case-insensitively against existing rows; missing tag rows are auto-created (mirrors `TaskRepository.CreateChildAsync`).
- Empty/whitespace tag names are skipped; duplicates are deduplicated.
- `tags` is the LAST parameter before `CancellationToken` so existing positional callers are unaffected (CancellationToken is bound by name in MCP runtime; defensive — see Migration).

### `UpdateTask` (new)

```
UpdateTask(
    taskId: string,
    title: string?,
    description: string?,
    commitType: string?,
    tags: string[]?,
    cancellationToken)
    -> TaskDto
```

Behavior:
- Loads the task; throws `InvalidOperationException` if not found.
- **Refuses if status is `Running`** — protects in-flight worktrees and the streaming log.
- Does NOT change status (use `UpdateTaskStatus`) and does NOT change `createdBy`, `listId`, or `parentTaskId` (audit + structural fields, immutable here).
- For each non-null parameter, applies the update. Null means "leave unchanged".
- `tags` semantics: full replacement of the tag set (same as `SetTaskTags`). Auto-creates missing tag rows.
- Broadcasts `TaskUpdated` on the SignalR hub on success.

### `DeleteTask` (new)

```
DeleteTask(taskId: string, cancellationToken) -> void
```

Behavior:
- Loads the task; throws if not found.
- **Refuses if status is `Running`** — caller must `CancelTask` first.
- Calls `TaskRepository.DeleteAsync` (FK cascades remove `task_tags`, `worktrees`, `task_runs`, `subtasks`).
- Broadcasts `TaskUpdated(taskId)` so UIs drop the row.

### `SetTaskTags` (new)

```
SetTaskTags(taskId: string, tags: string[], cancellationToken) -> TaskDto
```

Behavior:
- Convenience wrapper for "I just want to (re)set tags". Equivalent to `UpdateTask(taskId, null, null, null, tags)`.
- Same validation: refuses if `Running`.
- Returns the updated `TaskDto` (with status; tags are not included in `TaskDto` today — see Open Decisions).

### `ListTags` (new)

```
ListTags(cancellationToken) -> { Id: long, Name: string }[]
```

Behavior:
- Returns every row in the `tags` table. No filter, no pagination — the table is small (seed values + user-defined).
- Lets Claude discover existing tag names (`agent`, `manual`, plus any user-defined) before tagging, avoiding duplicates that differ only by case/whitespace.

## Repository changes

`src/ClaudeDo.Data/Repositories/TaskRepository.cs`:

- Add `public Task SetTagsAsync(string taskId, IReadOnlyList<string> tagNames, CancellationToken ct = default)` — replaces the tag set, auto-creates missing rows. Implementation pattern matches the tag block already inside `CreateChildAsync` and the new `UpdateChildAsync` from the planning-MCP work; consider extracting a private helper `ApplyTagsAsync(TaskEntity, IReadOnlyList<string>, CancellationToken)` shared by both.

`src/ClaudeDo.Data/Repositories/TagRepository.cs`:

- Add `public Task<List<TagEntity>> GetAllAsync(CancellationToken ct = default)` if it does not already exist. (Matches `ListRepository.GetAllAsync` style.)

No new tables, no migrations.

## Service changes

`src/ClaudeDo.Worker/External/ExternalMcpService.cs`:

- Add `TagRepository` to the constructor (DI registration is already in place since the planning service uses it).
- Extend `AddTask` signature with `IReadOnlyList<string>? tags` and apply via the repository.
- Add `UpdateTask`, `DeleteTask`, `SetTaskTags`, `ListTags` methods, each annotated `[McpServerTool, Description("…")]`.
- Each new mutating tool calls `_broadcaster.TaskUpdated(taskId)` on success (matches existing pattern in this file).

DI: `ExternalMcpService` is already registered. If `TagRepository` is not already registered (it is — used by `ListRepository`), no change. If a constructor parameter is added, `Program.cs` does not need changes because services are scoped/transient.

## Error handling

All errors raised as `InvalidOperationException` with a human-readable message — matches the existing pattern in `ExternalMcpService` and `PlanningMcpService`. The MCP SDK serializes these to the JSON-RPC error channel; Claude sees the message text directly.

Specific cases:
- Task not found → `"Task {id} not found."`
- Running-task guard → `"Cannot {update|delete} a running task. Cancel it first."`
- Unknown status (in `UpdateTaskStatus`, unchanged) → `"Unknown status '{x}'."`

## Testing

Add `tests/ClaudeDo.Worker.Tests/External/ExternalMcpServiceTests.cs` (or extend if it exists) with:

| Test | Asserts |
|---|---|
| `AddTask_WithTags_AttachesTags` | `tags` param creates and attaches tag rows |
| `AddTask_WithUnknownTag_AutoCreatesTagRow` | new tag name produces a row in `tags` table |
| `UpdateTask_PatchesNonNullFields` | only non-null fields change |
| `UpdateTask_OnRunning_Throws` | `InvalidOperationException` |
| `UpdateTask_BroadcastsTaskUpdated` | hub broadcast received |
| `UpdateTask_TagsReplaceFullSet` | passing tags=[…] replaces existing tags wholesale |
| `DeleteTask_RemovesTaskAndTagJoins` | task and `task_tags` rows gone |
| `DeleteTask_OnRunning_Throws` | `InvalidOperationException` |
| `SetTaskTags_ReplacesAndBroadcasts` | replacement semantics + broadcast |
| `ListTags_ReturnsSeedAndCustomTags` | `agent` + `manual` + any user-defined |

Existing test infrastructure (`DbFixture`, `FakeHubContext`) is reused. No new fakes required.

**Caveat:** the test assembly currently fails to compile on `main` because of pre-existing in-progress work on `PlanningChainCoordinator` (missing constructor argument in `WorkerHub`/`TaskRunner` test instantiations). Tests will pass only after that work lands; do not block this design on it.

## Open decisions (defaults chosen, easy to flip)

1. **`TaskDto` does not currently include tags.** For consistency, the spec keeps `TaskDto` as-is and ships a separate `ListTags` tool. If preferred, we could add `Tags: string[]` to `TaskDto` so every tool response includes them — small DB cost (one extra `SelectMany`), one struct field added. Default: leave `TaskDto` alone, defer.
2. **Per-tag `AddTaskTag` / `RemoveTaskTag` micro-tools.** Skipped — `SetTaskTags` covers the use case, and it's idempotent. Add later if granular ops are wanted.
3. **List CRUD via MCP.** Out of scope. UI owns lists.

## Migration / compatibility

`AddTask` gains an optional parameter. The MCP server SDK sends parameters by name in JSON-RPC `params`, so existing clients that omit `tags` continue to work without code changes. No version bump required.