MCP tools

The tracker exposes a two-tier MCP surface: a small set of essential tools always loaded plus a larger catalog of extended tools discoverable via getTools and executable via runTool. This page covers the shape of each tier so you know what the agent sees.

Essential tools — always loaded

These are in the agent’s context on every session. They cover the hot path: start, work, end.

Tool	What it does
`briefMe`	One-shot session primer — handoff, diff, top work, blockers, recent decisions, pulse.
`saveHandoff`	Session wrap-up — saves handoff, links commits, reports touched cards, returns resume prompt.
`createCard`	Create a card in a column (by name).
`updateCard`	Update card fields; optional `intent`.
`moveCard`	Move a card to a column. Requires `intent`.
`addComment`	Add a markdown comment to a card. Surfaces in `getCardContext` for future agents.
`registerRepo`	Bind a git repo path to a project (call after briefMe returns needsRegistration).
`checkOnboarding`	Detect DB state, list projects/boards, session-start discovery.
`getTools`	Browse extended tools by category.
`runTool`	Execute any extended tool by name.

That’s the entire baseline agent context. Everything else is one runTool call away.

Extended tools — on demand

Browsed via getTools({ category }) and executed via runTool({ tool, params }).

Category	Count	Tools
`activity`	1	`listActivity`
`cards`	5	`bulkCreateCards`, `bulkMoveCards`, `bulkUpdateCards`, `createCardFromTemplate`, `deleteCard`
`checklist`	3	`addChecklistItem`, `bulkAddChecklistItems`, `toggleChecklistItem`
`comments`	1	`listComments`
`context`	13	`getActivityWindow`, `getCardContext`, `getMilestoneContext`, `getTagContext`, `listClaims`, `listFacts`, `planCard`, `publishEdition`, `queryKnowledge`, `rebuildKnowledgeIndex`, `saveClaim`, `saveFact`, `squawk`
`decisions`	3	`getDecisions`, `recordDecision`, `updateDecision`
`diagnostics`	1	`doctor`
`discovery`	13	`auditBoard`, `getBoard`, `getCard`, `getRoadmap`, `getStats`, `getToolUsageStats`, `getWorkNextSuggestion`, `listBoards`, `listProjects`, `listWorkflows`, `queryCards`, `renderStatus`, `searchCards`
`git`	3	`getCommitSummary`, `getGitLog`, `syncGitActivity`
`milestones`	4	`createMilestone`, `listMilestones`, `mergeMilestones`, `updateMilestone`
`notes`	3	`createNote`, `listNotes`, `updateNote`
`relations`	3	`getBlockers`, `linkCards`, `unlinkCards`
`session`	6	`attributeSession`, `listHandoffs`, `loadHandoff`, `recalibrateBaseline`, `recordTokenUsage`, `recordTokenUsageFromTranscript`
`setup`	4	`createColumn`, `createProject`, `seedTutorial`, `setRepoPath`
`tags`	5	`createTag`, `deleteTag`, `listTags`, `mergeTags`, `renameTag`

How categories compose

flowchart LR
	A[Session start] --> B[briefMe]
	B --> C{Need more?}
	C -->|drill into card| D[runTool getCardContext]
	C -->|plan a sprint| E[runTool getRoadmap]
	C -->|search| F[runTool searchCards]
	C -->|work| G[moveCard / updateCard / addComment]
	G --> H[saveHandoff]

Most sessions never reach past briefMe + the essentials + one or two runTool calls.

Prompts (7)

MCP prompts are reusable session openers. Useful when you want to trigger a specific workflow.

Prompt	Purpose
`resume-board`	Loads board state + last handoff + diff. Alternative to `briefMe`. (Renamed from `resume-session` in #169 to avoid collision with Claude Code’s built-in `/resume`.)
`onboarding`	Guided setup — `tutorial` seeds a sample project, `quickstart` creates a real one.
`deep-dive`	Loads focused context for deep work on a specific card.
`sprint-review`	Velocity, milestone progress, stale cards, blockers.
`plan-work`	Template for breaking work into cards + checklists.
`setup-project`	Step-by-step guide for setting up a new project on the tracker.
`holistic-review`	Reviews the board against the actual codebase — syncs state with reality.

Resources (5)

MCP resources are read-only URIs the agent can reference without a tool call.

Resource URI	Provides
`tracker://board/{boardId}`	Full board state
`tracker://board/{boardId}/card/{number}`	Single card with all details
`tracker://board/{boardId}/handoff`	Latest session handoff
`tracker://project/{projectId}/decisions`	All project decisions
`status://project/{slug}`	Board-derived project status (replaces STATUS.md)

Card references

Cards get sequential numbers per project (#1, #2, #3). Reference them naturally — “working on #7”, “move #12 to Done” — and the agent resolves them automatically against the board scope.

Data model at a glance

flowchart LR
	P[Project] --> B[Board]
	B --> C[Card]
	C --> CM[Comment]
	C --> CK[ChecklistItem]
	C --> CR[CardRelation]
	C --> CN[Note]
	B --> H[Handoff]
	P --> M[Milestone]
	M --> C
	P --> CL[Claim]
	B --> G[GitLink]

Cards are the primary unit of work.
Notes + Claims are the two knowledge primitives — see docs/archive/RFC-NOTE-CLAIM-PRIMITIVES.md for the shape.
Session handoffs live in their own Handoff table (Project + Board scoped, append-only, indexed by createdAt); saveHandoff writes them and briefMe reads the latest. (Pre-v6.0.0 they rode on Note(kind="handoff"); the rows were migrated and the kind retired in #179 Phase 2.)
Architectural decisions are stored as Claim rows with kind=decision.
GitLink connects commits to cards via #N references.

Extending the surface

If you want to add a tool, the pattern is:

Add the handler in src/mcp/tools/<domain>.ts following ToolHandler<ParamsSchema>.
Register it in src/mcp/tool-registry.ts with a category, description, and schema.
Bump SCHEMA_VERSION in src/mcp/utils.ts if you changed the data model.
Run npm run docs:check to keep the README tables honest (they’re auto-generated from the registry).

The repo’s AGENTS.md has the longer contributor guide.