criticmarkup
Provides tools for editorial review of Markdown documents, allowing AI agents to propose CriticMarkup track changes (replacements, deletions, global substitutions) and manage threaded comments.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@criticmarkup replace all instances of 'utilize' with 'use' in draft.md"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-criticmarkup
Token-efficient, non-destructive editorial review and asynchronous track-changes for Markdown via the Model Context Protocol (MCP).
Why?
If your project depends on your own critical input to succeed, and you want to actively review LLM changes without copying and pasting chat messages, you need a structured way for the model to propose edits.
mcp-criticmarkup provides a frictionless alternative to Git workflows when collaborating with LLMs on Markdown documents. Instead of full-file overwrites or raw git diffs, the LLM proposes revisions using native CriticMarkup and manages threaded discussions.
What it allows LLM agents to do:
Propose precise edits (CriticMarkup):
Replace a single excerpt or perform deletions (
request_changes).Batch multiple revisions in one call (
replace_multiple).Perform global terminology replacements with word-boundary safety (
replace_all).
Engage in threaded discussions:
Add new comments anchored to specific phrases or proposed diffs (
write_comment).Reply to existing discussion threads by ID (
reply_to_comment).
Inspect documents efficiently:
Read the document while stripping heavy comment payloads to save tokens (
get_md_contents).
Related MCP server: reader3000-mcp
What then?
Authors can open the modified .md file in editors with native CriticMarkup support, such as Monoleaf. LLM's edits then render as interactive track-changes that you can accept or reject like in Word. CriticMarkup extensions for VS Code, Positron, and Obsidian may work for this purpose, although they might not support the comment syntax.
Exporting & Typesetting
When editing is complete, the clean Markdown can be compiled into nicely formatted documents. The pipeline I use myself is:
$$\text{Markdown} \xrightarrow{\text{Pandoc}} \text{Typst} \xrightarrow{} \text{PDF}$$
(Zettlr export profiles can automate this in a single click, with alternate profiles for LaTeX PDF or HTML).
Note on friction: Markdown is occasionally not expressive enough for complex page layouts, requiring embedded raw typesetting blocks. For example, a Typst page break embedded inside Markdown:
#pagebreak()
Included Tools
Ingestion Tool
get_md_contents(filepath)
Reads the document. Simplifies bulky comment payloads by replacing them with an abbreviated, token-efficient thread summary ([UID] Author: Message). Inline anchors remain in place so the model knows where discussions are tethered.
Editing Tools
replace_multiple(filepath, edits)
The primary multi-section editing tool. Accepts an array of{"search_string": "...", "replacement_string": "..."}objects.Free from word-boundary restrictions: accepts multi-line prose, sentences, and punctuation.
Validates all targets upfront and applies edits in reverse document order (bottom-to-top) to prevent offset drift.
Automatically preserves and slides comment anchors to the perimeter of the edit.
request_changes(filepath, search_string, replacement_string)
Single-edit convenience wrapper. Emits{--old--}whenreplacement_stringis empty, and{~~old~>new~~}otherwise.replace_all(filepath, search_string, replacement_string)
Global terminology substitution. Applies strict word boundaries (\b) to alphanumeric targets to prevent substring accidents. Automatically skips code blocks, inline code, links, YAML frontmatter, and existing CriticMarkup.
Commenting Tools
write_comment(filepath, search_string, comment_text)
Wrapssearch_stringwith conflict-safe inline anchors (<!--c:{id}s-->...<!--c:{id}e-->) and appends a Monoleaf-compatible thread payload to the bottom of the file.reply_to_comment(filepath, thread_id, reply_text)
Appends anAI AGENTresponse to an existing thread payload by UID.
Document Settings
One setting is supported file via YAML frontmatter as of now:
---
reviewer:
max_lines: 100 # Truncates visible text to 100 lines
---Installation & Setup
First, you need Python, and the mcp package (install with pip install mcp in terminal)
Download the repo to a location of your choice, then import this .json in your MCP configuration:
{
"mcpServers": {
"criticmarkup": {
"command": "python",
"args": ["/ABSOLUTE/PATH/TO/mcp-criticmarkup/server/server.py"]
}
}
}You might want to use a path to a virtual python environment instead of using system python. For that, replace "python" with your actual path.
Example Prompt
You are an editorial assistant reviewing Markdown documents using the criticmarkup MCP tools.
CORE EDITORIAL DIRECTIVES:
MINIMAL TRACK CHANGES (PRECISE REPLACEMENTS ONLY):
Your goal is NOT to rewrite the author's text.
Use track changes (
replace_multiple,request_changes) strictly for minor, surgical fixes: typos, punctuation, conciseness, grammar, or word choices.NEVER replace entire paragraphs or multi-sentence blocks for small edits. Keep
search_stringandreplacement_stringscoped strictly to the specific phrase being modified.
REWRITE THRESHOLD:
If a paragraph, section, or table suffers from major structural, logical, or stylistic problems that would require replacing the entire block, DO NOT REWRITE IT unless the user explicitly commanded!
Instead, use
write_commentanchored to the first 2–4 words of that sub-heading, paragraph, or table to critique the issue and very briefly outline a possible revision.
BUNDLE EXECUTION:
Inspect the file with
get_md_contents.Plan all edits across the document first, then execute them in a single batch using
replace_multiple.Apply all text edits BEFORE adding discussion comments.
REPORT BACK
Show the user a brief report of what was added or adjusted.
You can not make use of the tool as it keeps producing errors? There are too many unresolved edits to properly work? Just stop and tell the user!
Available Tools
6 toolsget_md_contentsA
Reads a markdown file, returning prose up to the user-configured cutoff line (if set), followed by an abbreviated summary of discussion comment threads. YAML frontmatter is completely hidden from view.
Inputs: filepath (required). Returns: result
replace_allB
Globally replaces ALL instances of a word or phrase throughout the document body using CriticMarkup. Operates across the full document body regardless of cutoff line, while frontmatter, inline anchors, and JSON comment payloads remain strictly protected.
Inputs: filepath (required), search_string (required), replacement_string (required). Returns: result
replace_multipleB
Applies multiple targeted revisions across different sections in a single call using CriticMarkup. Edits are applied bottom-to-top to maintain offset stability. Targeted edits past the configured cutoff line are rejected.
Inputs: edits (required), filepath (required). Returns: result
reply_to_commentA
Replies to an existing discussion thread by its 4-character UID (e.g. 'o1b7'). Unaffected by the line cutoff.
Inputs: filepath (required), thread_id (required), reply_text (required). Returns: result
request_changesB
Applies a single targeted change or deletion using CriticMarkup. Targeted edits past the configured cutoff line are prohibited.
Inputs: filepath (required), search_string (required), replacement_string (required). Returns: result
write_commentB
Attaches an inline comment anchor around target text and creates an open discussion thread. Comments cannot be anchored past the configured cutoff line.
Inputs: filepath (required), comment_text (required), search_string (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Most tools have clearly distinct purposes: reading, targeted single/multiple edits, global replace, creating comments, and replying. However, request_changes applies a single edit despite a plural name that suggests multiple changes, and it overlaps somewhat with replace_multiple at different granularities, so an agent could momentarily confuse them.
All tool names use snake_case with a verb_noun structure (get_md_contents, replace_multiple, request_changes, replace_all, write_comment, reply_to_comment). The naming pattern is predictable throughout; the semantic oddity of request_changes does not break the naming convention.
Six tools is well-scoped for markdown reading, editing, and commenting. Each tool appears to earn its place without excessive granularity or redundancy in count.
Core read/edit/comment-creation workflows are covered, including single, multiple, and global edits plus replying to threads. But the discussion lifecycle is incomplete: there is no resolve, close, or delete comment-thread tool, and no accept/reject lifecycle for CriticMarkup changes, leaving agents at a dead end for closing or cleaning up discussions.
Related MCP Connectors
MarkupBase turns AI-generated Markdown and HTML into durable, versioned artifacts that people can review and discuss. Its MCP server lets agents publish new versions, preserve contextual comments, include hosted images, and respond to feedback through secure account-linked identities, creating a clear human review boundary without requiring real-time editing.
Versioned artifact review for people and AI agents, with contextual comments and human control.
Research-backed lint + generation for agent context files (CLAUDE.md, AGENTS.md) + prompt enhancer.
Markdown workspace for AI agents: read, write, organize, and share markdown documents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA local-first markdown review tool with MCP integration, enabling AI and humans to collaboratively annotate documents inline and generate revision prompts.1MIT
- AlicenseNot gradedqualityDmaintenanceEnables sharing Markdown documents for collaborative review with inline annotations and structured change requests.21 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables anchored comments in Markdown files that AI agents can propose changes for, with human approval before application, all managed via an MCP server.4MIT
- AlicenseNot gradedqualityBmaintenanceEnables interactive review of rendered Markdown documents by selecting passages, queueing line-anchored feedback, and submitting it in one batch to a coding agent that edits the original source file.10 npmMIT