GW-032: Complete MCP descriptions, annotations, structured results, and errors

[trippyogi]

Outcome

Complete Gitworthy's MCP surface as the primary agent-facing product contract: clear tool descriptions, safe annotations, validated structured results, protocol-correct errors, cancellation/progress support, and parity with the CLI/core.

An MCP host should be able to discover the right tool, understand whether it is read-only/idempotent, call it with validated input, and act on structured output without parsing prose.

Why this matters

Cursor, ChatGPT, Hermes, and other agents are already the main way Gitworthy is used. Thin tool registration and ordinary-text error responses leave too much interpretation to the host agent and make integrations brittle.

Scope

• Retain current tool names through 1.0 unless a documented compatibility migration is unavoidable.
• Add concise descriptions, intended use, examples, cost/budget notes, and read-only/idempotent annotations where supported.
• Use the same input schemas as the CLI.
• Validate results before serialization.
• Return structured content where the pinned SDK supports it, with JSON text as compatibility representation.
• Mark operational failures as MCP errors rather than successful ordinary content.
• Include schema version, Gitworthy version, run ID, decision ID, retryability, required capability, and partial status where applicable.
• Add cancellation and progress for long-running scan/hunt/recheck operations where supported.
• Guarantee no logs, diagnostics, or telemetry contaminate stdio stdout.
• Document primary onboarding tools versus advanced evidence/debug tools.

Primary onboarding tools

• doctor
• worth_check
• hunt
• brief
• outcome_record

Advanced provider tools remain available but should be labeled as evidence/debug surfaces rather than final decisions.

Non-goals

• No proprietary agent protocol replacing MCP.
• No write actions against external repositories.
• No requirement that every host support progress or rich structured content identically.
• No prose parsing by machine consumers.

Dependencies and readiness

• Depends on GW-007 / issue GW-007: Add strict input validation and structured CLI/MCP errors #16, completed by PR GW-007: Strict CLI/MCP input validation and structured errors #54.
• Depends on GW-028 / issue GW-028: Add complete compact hunt decisions, partial persistence, and resume #37.
• Contributor readiness: BLOCKED until GW-028: Add complete compact hunt decisions, partial persistence, and resume #37 lands. Tool metadata and error-contract design can proceed earlier.

Acceptance criteria

• Every primary tool has accurate descriptions, examples, annotations, and input/output schemas.
• CLI and MCP contract fixtures match for the same core call, excluding transport-only metadata.
• Operational failures set MCP error semantics and retain structured error details.
• Results include stable version/run/decision identifiers where applicable.
• Long-running tools honor cancellation and preserve partial progress.
• Progress notifications never corrupt stdio transport.
• Advanced tools are clearly distinguished from verdict-bearing tools.
• MCP list/call self-test runs from the packed package in release CI.
• No token, secret, or diagnostic text is emitted to stdout.

Tests and validation

• Tool-list metadata snapshots.
• Input validation parity with CLI.
• Structured success/error/partial result fixtures.
• Cancellation and progress tests.
• stdio contamination tests under verbose/telemetry/error conditions.
• Packed-package MCP self-test.
• Compatibility tests against at least Cursor and one generic MCP client/harness.

Likely implementation areas

• src/mcp/server.ts registration and handlers.
• Shared schemas and serializers.
• Cancellation/run-budget plumbing from hunt.
• MCP integration docs and example host configs.

Compatibility

Treat tool names, input schemas, and structured output as public 1.0 surfaces. Any unavoidable change needs an alias/deprecation period and explicit migration documentation.

[trippyogi]

Initial GW-032 slice in draft #76 (descriptions, annotations, structuredContent, mcp self-test). Cancellation/progress and fuller host compatibility still open.

[trippyogi]

Shipped in #76. Remaining GW-032 items (cancellation/progress, broader host harnesses) stay open if needed.