backlog-mcp

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 single acceptance criterion as checked (- [ ] → - [x]) in a story file. Identify the target by criterion_index (0-based) or criterion_text (case-insensitive exact match). Exactly one must be provided. Returns {story_id, criterion, checked, path}. Errors if the story is not found, the criterion is not found, or it is already checked.

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. If some criteria are unchecked, incomplete_items is required with one explanation per unchecked item (in the order they appear). On success, removes the story from backlog.md and returns {story_id, completed_at, backlog_removed}.

Create a new epic. Assigns the next EPIC-NNN ID, creates the epic directory and epic.md file, and registers it in requirements-index.md with status draft. Returns {epic_id, path}.

Create a new story under an existing epic. Assigns the next STORY-NNN ID, writes the story file, and registers it in requirements-index.md and backlog.md with status draft. The story is appended to the end of the backlog. Returns {story_id, path}.

Get a high-level summary of all epics and their story counts broken down by status. Useful for situational awareness at the start of a session, without reading every file. Returns an array of {epic_id, title, status, counts: {status: n}, stories: [{story_id, status}]}.

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.

Reconcile the ## Stories section in an epic.md file with the story files on disk and the requirements index. Adds missing entries, removes entries for story files that no longer exist, and refreshes titles and done/undone markers. Returns {epic_id, added, removed, updated, unchanged}.

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.

Replace the acceptance criteria section of a story file. Each string in the criteria array becomes a - [ ] ... checklist line. Idempotent: calling again replaces the previous AC entirely. Acceptance criteria must be set before a story can be completed with complete_story. Returns {story_id, criteria_count, path}.

Update the status of a story to draft, in-progress, or blocked. 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}.