MCP server for managing project requirements, epics, and stories in markdown format with support for acceptance criteria, status tracking, and backlog management
Server has 5 tools with basic schemas and descriptions, but significant gaps limit production readiness. Tool names follow verb_noun convention (list_, get_, set_, add_, complete_). Descriptions exist but are verbose (200+ chars) and include implementation details rather than LLM-optimized guidance. Schemas present but incomplete: parameters lack enums for constrained values (status, story_type), and output schemas are not formally documented. Error handling is minimal, no recovery guidance or actionable error messages. The complete_story tool description is truncated in source, making it impossible to verify full schema. No tool annotations (readOnlyHint, destructiveHint) despite clear read/write distinctions.
Append a timestamped note to a story file. Use to record progress, decisions made, or blockers encountered. Notes are appended under a '## Notes' section with an ISO 8601 timestamp. Returns {story_id, appended_at, path}.
Mark a story done and append a mandatory completion summary note in one atomic call. Validates acceptance criteria before completing: if the AC section has not been set (contains only the placeholder), completion is blocked — call set_acceptance_criteria first. IMPORTANT: if a criterion is actually done, mark it [x] in the story file via set_acceptance_criteria BEFORE calling this tool — do not leave it unchecked. If criteria remain unchecked (genuinely not done), incomplete_items is required with on
Get the full markdown content and metadata for a single story. Returns {story_id, title, status, epic_id, path, content} where content is the raw markdown of the story file. Set include_notes=false to omit the '## Notes' section (and everything after it) from content — use this when you only need current status, goal, or acceptance criteria and want to avoid paying for a long accumulated note history.
List stories from the project index, optionally filtered by epic, status, or type. Returns an array of {story_id, title, status, epic_id, story_type} objects. With no filters, returns all stories across all epics. Other tools in this server: get_story, get_index_summary, create_epic, create_story, set_story_status, set_epic_status, add_story_note, set_acceptance_criteria, check_acceptance_criterion, complete_story, bulk_update_stories, bulk_update_epics, bulk_update_acceptance_criteria, groom_epic, reorder_backlog.
complete_story tool definition is truncated in source code, input schema cannot be verified. Description cuts off mid-sentence ('If criteria remain unchecked (genuinely not done), incomplete_items is required with on'). Cannot assess completeness.
Parameters accept free-form strings where enums should be used. 'status' param in list_stories and set_story_status lists valid values in description ('draft, in-progress, done, blocked') but does not declare them as JSON Schema enum. LLMs will hallucinate invalid values.
Output schemas are not formally documented. Tools return structured JSON (e.g., list_stories returns array of {story_id, title, status, epic_id, story_type}) but no schema definition is provided to the LLM. Agents cannot plan downstream calls with confidence.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 53 | 2026-07-28+ | v2 |
Update the status of a story to draft, in-progress, blocked, or deferred. To mark a story done, use complete_story instead — it enforces acceptance criteria, appends a summary note, and removes the story from the backlog. Returns {story_id, old_status, new_status, backlog_updated}.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear semantic differences. list_stories and get_story are read-only; set_story_status, add_story_note, complete_story are destructive writes. Annotations enable safer agent planning.
Error handling lacks recovery guidance. Code returns toolError(err) with raw Go error messages (e.g., 'finding story file: <error>'). LLMs receive no actionable next steps, should suggest alternative tools or user corrections.