md-feedback

MCP server for markdown annotation review — AI agents read your annotations directly.

What is this?

md-feedback is an MCP server that lets AI agents (Claude Code, Cursor, Copilot, etc.) read your markdown review annotations, mark memos done, evaluate quality gates, and generate session handoffs — all automatically.

This is the MCP server component. For the VS Code extension, see MD Feedback on VS Code Marketplace.

Quick Start

Add to your MCP client config (Claude Code, Cursor, etc.):

{
  "mcpServers": {
    "md-feedback": {
      "command": "npx",
      "args": ["-y", "md-feedback"]
    }
  }
}

That's it. No install, no setup — npx handles everything.

Workspace override — if your MCP client doesn't set cwd to the project folder:

{
  "mcpServers": {
    "md-feedback": {
      "command": "npx",
      "args": ["-y", "md-feedback", "--workspace=/path/to/project"]
    }
  }
}

Resolution order: --workspace= CLI arg > MD_FEEDBACK_WORKSPACE env > cwd

26 MCP Tools

| Tool | Description | |------|-------------| | get_document_structure | Full review state: memos, gates, cursor, sections, summary, metrics | | list_annotations | All annotations with type/status/owner/color | | get_review_status | Annotation counts and session status | | create_annotation | Create annotation programmatically with anchor search | | respond_to_memo | Add AI response to an annotation | | update_memo_status | Mark a memo as open/in_progress/needs_review/answered/done/failed/wontfix | | update_cursor | Set plan cursor position (task ID, step, next action) | | evaluate_gates | Check if merge/release/implement conditions are met | | export_review | Export for a specific AI tool format | | create_checkpoint | Save review progress snapshot | | get_checkpoints | List all checkpoints | | generate_handoff | Generate structured handoff document | | pickup_handoff | Parse existing handoff for session resumption | | apply_memo | Apply implementation (text_replace, file_patch, file_create) with dry-run | | link_artifacts | Link source files to a memo | | update_memo_progress | Update progress with status and message | | rollback_memo | Rollback the latest implementation for a memo | | batch_apply | Apply multiple operations in a single transaction | | get_memo_changes | Get implementation history and progress for a memo | | get_policy_status | Get current workflow enforcement mode and policy | | get_workflow_status | Get workflow phase, transitions, and pending approvals | | get_severity_status | Get memo severity overrides and unresolved blocking memos | | advance_workflow_phase | Advance to the next workflow phase (scope → root_cause → implementation → verification) | | set_memo_severity | Override a memo's severity (blocking / non_blocking) | | request_approval_checkpoint | Request human approval before a high-risk operation | | approve_checkpoint | Approve a pending approval checkpoint |

Safety & Reliability

• File mutex — concurrent MCP tool calls are serialized per-file, preventing data corruption
• Improved anchor matching — annotations find their intended location more reliably, even with multiple matches

How It Works

1. You annotate a markdown plan in the VS Code extension
2. AI agent reads annotations via MCP — no export needed
3. Agent implements fixes, marks memos done
4. Gates auto-evaluate — agent knows when it's safe to merge
5. Agent generates handoff — next session picks up where you left off

CLI

md-feedback                          # Start MCP server (stdio)
md-feedback --workspace=/path/to/dir # Set workspace root explicitly
md-feedback --version                # Print version
md-feedback --help                   # Show help

Who Is This For?

Developers and team leads who use AI coding agents (Claude Code, Cursor, Copilot) and want to review AI-generated plans before implementation — not after.

Links

• VS Code Extension
• GitHub
• Documentation

License

SUL-1.0 — Free for personal and non-commercial use.