Readable MCP resource responses — implementation record
Typed reads now lead with concise human state and reveal detail, history, raw storage, or schema only when explicitly requested. Existing callers retain their exact response shape.
Problem and locked contract
The legacy read_plan envelope repeats identity fields and exposes resolved history, option maps, empty storage fields, and full prompts even when a caller only needs current status. Project discovery and audit responses compound that cost by returning every record in one payload.
The existing three-tool surface remains intact. A new resource selector carries project, type, id, and optional archive identity. Typed calls default to summary; detail, history, raw, and schema are explicit. Calls omitting both resource and view retain the exact legacy result.
Implementation
| Layer | Purpose | Payload discipline |
|---|---|---|
summary | Human title, compact state, blockers, open decisions, and next action | No resolved workflow or full prompts |
detail | Current metadata, relationships, unresolved workflow, and composed sprint items | Prompts remain opt-in |
history | Resolved decisions, followups, questions, or timeline events | Deterministic bounded cursor pages |
raw | Lossless state for version-safe writes and compatibility diagnosis | Explicit opt-in |
schema | Stable response shape, storage schema, operation vocabulary, and authoring guidance | Explicit opt-in |
reckon/mcp_views.py owns view validation, typed identity, pagination, human summaries, and common structured errors. reckon/mcp.py routes opt-in progressive reads without changing the legacy branch. The audit tool exposes summary, paginated detail, schema, and raw views through optional arguments.
Typed identity and cursor inputs are length-bounded and validated before filesystem resolution or decoding. Pending, blocked, and missing prerequisites appear in the summary's blocking list; shipped and done prerequisites do not.
Every storage type has an accurate schema and every response layer has a complete machine-readable shape. Summary discovery places concise sprint cards first in the same bounded cursor stream as plan/research/evidence cards. Before distributed activation, named project-state reads are safe projections of the canonical legacy index; writes continue through that index until explicit migration.
Compatibility and agent guidance
The FastMCP-generated schema advertises every new argument as optional. Tests assert the old plan and audit shapes exactly, typed/archive selection, prompt opt-in, cursor behavior, resource errors, live sprint composition, and representative response budgets.
Successful edits now return a clear human sentence plus the affected typed resource. Version conflicts name the resource and requested operation, report expected and current versions, and give the smallest corrective action.
The bundled status skill now begins with summary views. Edit, sprint-write, and ship workflows request raw explicitly before versioned writes. The public README, format reference, tool descriptions, and repository guidance document the same contract.
Verification
| Representative call | Legacy bytes | Summary bytes | Reduction |
|---|---|---|---|
| Plan | 4,241 | 564 | 86.7% |
| Sprint | 3,668 | 576 | 84.3% |
| Project discovery | 56,470 | 4,747 | 91.6% |
| Audit | 18,057 | 481 | 97.3% |
- Complete suite: 1,373 passed in 28.53 seconds.
- Ruff lint and format checks: clean.
- Implementation commits:
8cc940f,c9e14f2. - Detailed evidence: verified landing record.