@mrsf/mcp

Model Context Protocol (MCP) server for Sidemark — the Markdown Review Sidecar Format (MRSF).

Exposes Sidemark and MRSF (Markdown Review Sidecar Format) operations as MCP tools and resources so that AI assistants (Claude Desktop, Cursor, VS Code Copilot, etc.) can review Markdown documents, inspect existing comment threads, add review feedback, resolve comments, validate sidecars, and re-anchor comments through the standard MCP protocol.

Installation

npm install -g @mrsf/mcp

Or use directly:

npx @mrsf/mcp

Quick Start — Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "mrsf": {
      "command": "npx",
      "args": ["-y", "@mrsf/mcp"]
    }
  }
}

Restart Claude Desktop — the MRSF tools will appear automatically.

Quick Start — VS Code / Cursor

Add to your project's .vscode/mcp.json:

{
  "servers": {
    "mrsf": {
      "command": "npx",
      "args": ["-y", "@mrsf/mcp"]
    }
  }
}

Transport Options

| Flag | Default | Description | | --- | --- | --- | | --transport stdio | ✔ | Standard I/O (Claude Desktop, Cursor, VS Code) | | --transport sse | | Server-Sent Events over HTTP | | --port <n> | 3001 | Port for SSE transport |

# Default — stdio
mrsf-mcp

# SSE on custom port
mrsf-mcp --transport sse --port 8080

Tools

The server exposes the following MCP tools:

| Tool | Description | | --- | --- | | mrsf_discover | Find the sidecar for a Markdown document | | mrsf_validate | Validate sidecars against the MRSF schema | | mrsf_reanchor | Re-anchor comments after a document has been edited | | mrsf_add | Add a new review comment to a sidecar | | mrsf_add_batch | Add multiple review comments in one atomic call | | mrsf_update | Update fields of an existing comment by ID | | mrsf_resolve | Resolve or unresolve comments by ID(s) or filters | | mrsf_list | List and filter comments (status, author, type, severity) with full or compact output | | mrsf_status | Check anchor health (fresh / stale / orphaned) | | mrsf_rename | Update a sidecar after its document has been renamed | | mrsf_delete | Delete a comment by ID (with optional cascade) | | mrsf_repair | Repair or reset a corrupted sidecar | | mrsf_help | List all tools and their parameter schemas |

Tool Details

mrsf_discover

Find the Sidemark (MRSF) sidecar for a Markdown document.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | document | string | ✔ | Path to the Markdown document | | cwd | string | | Working directory (defaults to process.cwd()) |

mrsf_validate

Validate one or more Sidemark (MRSF) sidecars.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | files | string[] | | Sidecar or Markdown file paths. If omitted, discovers all sidecars in the workspace. | | strict | boolean | | Treat warnings as errors | | cwd | string | | Working directory |

mrsf_reanchor

Re-anchor comments after document edits.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | files | string[] | | Sidecar or Markdown file paths. If omitted, discovers all sidecars. | | dryRun | boolean | | Report without modifying files | | threshold | number | | Fuzzy match threshold 0.0–1.0 (default 0.6) | | updateText | boolean | | Also replace selected_text with current document text | | force | boolean | | Firmly anchor high-confidence results: update commit to HEAD and clear audit fields | | cwd | string | | Working directory |

mrsf_add

Add a review comment to a Sidemark (MRSF) sidecar.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | document | string | ✔ | Path to the Markdown document | | text | string | ✔ | Comment text | | author | string | ✔ | Author identifier (e.g. 'Name (handle)') | | line | number | | Starting line number (1-based) | | end_line | number | | Ending line number (inclusive) | | start_column | number | | Starting column (0-based) | | end_column | number | | Ending column | | type | string | | Comment type: suggestion, issue, question, accuracy, style, clarity | | severity | "low" | "medium" | "high" | | Severity level | | reply_to | string | | Parent comment ID for threading | | extensions | object | | Tool-specific x_* extension fields; keys must start with x_ | | cwd | string | | Working directory |

mrsf_add_batch

Add multiple review comments to a Sidemark (MRSF) sidecar in one atomic write.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | document | string | ✔ | Path to the Markdown document | | comments | object[] | ✔ | Array of comments: each needs text and author, optional line, end_line, start_column, end_column, type, severity, reply_to, extensions | | cwd | string | | Working directory |

mrsf_update

Update fields of an existing comment by ID (only provided fields are changed).

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | document | string | ✔ | Path to the Markdown document or its sidecar | | id | string | ✔ | Comment ID to update | | text | string | | New comment text | | type | string | | New type: suggestion, issue, question, accuracy, style, clarity | | severity | "low" | "medium" | "high" | | New severity level | | line | number | | New starting line number (1-based) | | end_line | number | | New ending line number (inclusive) | | start_column | number | | New starting column (0-based) | | end_column | number | | New ending column | | extensions | object | | Merge tool-specific x_* fields into the comment | | cwd | string | | Working directory |

extensions values are stored on disk as flat x_* fields on the comment, not as a nested object.

mrsf_resolve

Resolve or unresolve comments. Provide a single id, an array of ids, or filters.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | document | string | ✔ | Path to the Markdown document or its sidecar | | id | string | | Single comment ID to resolve/unresolve | | ids | string[] | | Array of comment IDs to resolve/unresolve | | author | string | | Resolve all comments by this author | | type | string | | Resolve all comments of this type | | severity | "low" | "medium" | "high" | | Resolve all comments of this severity | | unresolve | boolean | | Set to true to unresolve instead | | cwd | string | | Working directory |

mrsf_list

List and filter comments across Sidemark (MRSF) sidecars.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | files | string[] | | Sidecar or Markdown file paths. If omitted, discovers all sidecars. | | open | boolean | | Only show unresolved comments | | resolved | boolean | | Only show resolved comments | | author | string | | Filter by author | | type | string | | Filter by type | | severity | "low" | "medium" | "high" | | Filter by severity | | format | "full" | "compact" | | Output format: full (JSON) or compact (text table) | | summary | boolean | | Return summary statistics instead of full comments | | cwd | string | | Working directory |

mrsf_status

Check anchor health of all comments in Sidemark (MRSF) sidecars.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | files | string[] | | Sidecar or Markdown file paths. If omitted, discovers all sidecars. | | cwd | string | | Working directory |

mrsf_rename

Update sidecar after a document rename/move.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | oldDocument | string | ✔ | Old path to the Markdown document | | newDocument | string | ✔ | New path to the Markdown document | | cwd | string | | Working directory |

mrsf_delete

Delete a comment by ID from a sidecar. By default, direct replies are promoted (they inherit the parent's anchor and their reply_to is re-pointed to the grandparent). Use cascade to delete direct replies along with the parent instead.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | document | string | ✔ | Path to the Markdown document or its sidecar | | id | string | ✔ | Comment ID to delete | | cascade | boolean | | When true, also remove direct replies instead of promoting them (default: false) | | cwd | string | | Working directory |

mrsf_repair

Repair or reset a corrupted sidecar. Use salvage strategy to attempt recovering parseable comments from a corrupted sidecar (rewrites it cleanly). Use reset strategy to delete the sidecar and start fresh with an empty comment list.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | document | string | ✔ | Path to the Markdown document or its sidecar | | strategy | "salvage" | "reset" | | Repair strategy: salvage (default) attempts to recover comments; reset starts fresh | | cwd | string | | Working directory |

mrsf_help

List all available Sidemark (MRSF) MCP tools with their parameter schemas. Optionally filter to a specific tool for detailed parameter info.

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | tool | string | | Tool name to get detailed help for (e.g. mrsf_add). Omit to list all tools. |

Resources

The server also exposes MCP resources for direct data access:

| URI Pattern | Description | | --- | --- | | mrsf://sidecar/{path} | Full parsed Sidemark (MRSF) sidecar as JSON | | mrsf://comment/{path}/{id} | A single review comment from a sidecar | | mrsf://anchors/{path} | Anchor health status for all comments in a sidecar |

Agent Skill Example

The repository includes a ready-to-use Agent Skill that teaches AI agents to review Markdown documents using the MCP server. See the skill on GitHub.

Copy it into your project:

cp -r examples/mrsf-review .agent/skills/

The skill instructs the agent to discover sidecars, add anchored comments with type and severity, validate results, and summarize findings — all through the MCP tools above.

Requirements

• Node.js ≥ 18
• @mrsf/cli (installed automatically as a dependency)

License

MIT