@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

Working with live editor buffers

When an editor has unsaved Markdown changes, pass documentText to mrsf_add, mrsf_add_batch, mrsf_update, or mrsf_reanchor. The server uses that inline text for selected_text population and anchoring instead of reading the document from disk. For mrsf_reanchor, documentText requires exactly one target sidecar/document.

Mutating tools return a sidecar content hash as version. Pass the latest value back as expectedVersion on the next write to reject stale edits:

{
  "document": "guide.md",
  "id": "c-123",
  "text": "Updated comment",
  "expectedVersion": "last-observed-sha256"
}

If the sidecar changed, the tool returns isError: true with:

{
  "status": "conflict",
  "code": "version-mismatch",
  "currentVersion": "new-sha256",
  "expectedVersion": "last-observed-sha256"
}

Recommended client pattern: read or discover the sidecar to get version, make one mutation with expectedVersion, then re-read or use the returned version before any follow-up mutation.

Concurrency & write-conflict semantics

When an interactive editor and an agent (this MCP server) can both write the same sidecar, the following contract applies.

Within a single process (the @mrsf/cli library writeSidecar):

• Writes to the same sidecar path are serialized through a per-file queue, so concurrent calls never interleave a read-modify-write cycle.
• Every write is atomic (write to a temp file in the same directory, then rename), so readers never observe a half-written file.
• The YAML writer round-trips at the CST level, preserving unrelated formatting/comments, but it persists the writer's full in-memory document — there is no field-level merge of concurrent edits. At this layer the effective semantics are last-write-wins for the document state held in memory.

Across processes (editor ⇄ MCP agent) — optimistic concurrency:

• The library itself has no cross-process expectedVersion/etag guard; two separate processes doing read-modify-write can still race and lose comments.
• The MCP tools add an optimistic-concurrency guard on top: every read/mutation returns a version (a SHA-256 hash of the sidecar contents). Pass the last-observed value back as expectedVersion on the next mutation. If the on-disk sidecar changed in the meantime, the tool returns isError: true with { "status": "conflict", "code": "version-mismatch", "currentVersion", "expectedVersion" } and performs no write.
• The library does not merge concurrent comment additions; reconciliation is the caller's responsibility, driven by version.

Recommended pattern for a host that both watches and writes the sidecar:

1. Track the latest version you have observed for each sidecar.
2. Watch the sidecar file for external changes (e.g. the agent writing) and reload your in-memory document when it changes, adopting the new version.
3. Always send expectedVersion on MCP mutations (mrsf_add, mrsf_add_batch, mrsf_update, mrsf_resolve, mrsf_rename, mrsf_delete, and single-target mrsf_reanchor).
4. On a version-mismatch, reload the sidecar, re-apply your pending change against the fresh state, and retry with the new expectedVersion.
5. Serialize your own writes (editor save vs. agent action) rather than firing both concurrently; the version guard turns an unavoidable race into a detectable conflict rather than silent data loss.

expectedVersion is honored only when a mutation targets exactly one sidecar. For batch/multi-target mrsf_reanchor it is ignored (the response notes this), so coordinate those per-file.

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())

Returns version, the current sidecar content hash.

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
documentText	string		Inline document content for unsaved editor buffers (single target only)
expectedVersion	string		Reject write if the current sidecar hash differs
cwd	string		Working directory

Returns version for each processed sidecar.

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_
documentText	string		Inline document content for unsaved editor buffers
expectedVersion	string		Reject write if the current sidecar hash differs
cwd	string		Working directory

Returns version, the new sidecar content hash.

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
documentText	string		Inline document content for unsaved editor buffers
expectedVersion	string		Reject write if the current sidecar hash differs
cwd	string		Working directory

Returns version, the new sidecar content hash.

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
documentText	string		Inline document content for unsaved editor buffers when line anchors change
expectedVersion	string		Reject write if the current sidecar hash differs
cwd	string		Working directory

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

Returns version, the new sidecar content hash.

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
expectedVersion	string		Reject write if the current sidecar hash differs
cwd	string		Working directory

Returns version, the current sidecar content hash.

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

Full and summary JSON outputs include each sidecar's version.

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

Returns sidecar version values in the files array.

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
expectedVersion	string		Reject write if the current old sidecar hash differs
cwd	string		Working directory

Returns version, the new sidecar content hash.

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)
expectedVersion	string		Reject write if the current sidecar hash differs
cwd	string		Working directory

Returns version, the new sidecar content hash.

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
expectedVersion	string		Reject write if the current sidecar hash differs
cwd	string		Working directory

Returns version, the new sidecar content hash.

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