Skip to main content
Glama

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:

  1. 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).

  2. 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).

  3. 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--} when replacement_string is 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)
    Wraps search_string with 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 an AI AGENT response 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:

  1. 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_string and replacement_string scoped strictly to the specific phrase being modified.

  2. 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_comment anchored to the first 2–4 words of that sub-heading, paragraph, or table to critique the issue and very briefly outline a possible revision.

  3. 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.

  4. 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 tools
get_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

    A3.5/5.0

    Scored across 6 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      MIT