article-review-mcp

A visual MCP App for reviewing explicit article patches with categorized comments.

The editing agent does not hand the server a silently rewritten manuscript. It submits:

unchanged base document
+ explicit patches against that base
+ one or more categorized rationale comments per patch

The server validates and applies those patches deterministically, opens an interactive review UI, records human decisions, and safely assembles the final article.

Why patch-first

A full-document diff can show what changed, but it loses the agent's original intent. In this project, a patch is the atomic review object:

Patch
├── exact target in the original document
├── replace / delete / insert_before / insert_after
├── proposed text
├── categorized comments explaining why
└── human decision: pending / accepted / rejected / edited

Every comment has exactly one primary topicId. A patch may contain multiple comments across different topics.

Current capabilities

• Explicit PatchSet submission against an immutable base document
• replace, delete, insert_before, and insert_after
• Base SHA-256 verification
• Exact-anchor resolution with optional contextBefore and contextAfter
• Rejection of ambiguous anchors and overlapping patches
• Required categorized rationale comments for every patch
• Custom topic taxonomies per review session
• Topic tabs with per-topic patch/comment counts
• Two topic review modes:
  • keep all patches visible and dim unrelated patches
  • show only patches containing the selected topic
• Split, unified, and complete Final views
• Word-level insertion/deletion highlighting for English and Chinese
• Accept, reject, reset, manually edit, and bulk-decide visible patches
• Add, reply to, resolve, and filter reviewer comments
• Compact topic-filtered feedback for the editing agent
• Immutable revision rounds with exact-patch decision carry-over
• JSON persistence, optimistic concurrency, and idempotency
• MCP App plus token-protected localhost browser viewer
• Safe preview, write-new-file, guarded overwrite, and static HTML export
• Legacy base + full proposal tools retained as deprecated compatibility aliases

Requirements

• Node.js 20 or newer
• No runtime dependency installation is required

Validate

npm run check

The suite runs syntax checks and 13 tests, including a real stdio MCP exchange and localhost viewer calls.

Run as an MCP server

node src/cli.mjs \
  --stdio \
  --workspace /absolute/path/to/your/writing-workspace

Example client configuration:

{
  "mcpServers": {
    "article-review": {
      "command": "node",
      "args": [
        "/absolute/path/to/article-review-mcp/src/cli.mjs",
        "--stdio",
        "--workspace",
        "/absolute/path/to/your/writing-workspace"
      ]
    }
  }
}

Primary agent call

Call article_review_submit_patchset:

{
  "title": "Introduction revision",
  "format": "markdown",
  "base": {
    "type": "workspace_file",
    "path": "manuscript.md"
  },
  "baseHash": "optional-sha256-of-the-base",
  "topics": [
    {
      "id": "architecture",
      "label": "架构与叙事",
      "description": "章节组织、研究主线和段落衔接"
    },
    {
      "id": "logic",
      "label": "逻辑与论证"
    },
    {
      "id": "clarity",
      "label": "表达与清晰度"
    }
  ],
  "patchSet": {
    "id": "revision-001",
    "summary": "补齐 Section 1 到 Section 2 的理论过渡",
    "patches": [
      {
        "id": "selection-pressure-bridge",
        "operation": "replace",
        "target": {
          "oldText": "The later experiments therefore held the candidate text fixed...",
          "contextBefore": "These results support Prediction 1...",
          "contextAfter": "LLM judge reliability varies..."
        },
        "newText": "Collectively, Section 1 establishes that...",
        "comments": [
          {
            "topicId": "architecture",
            "kind": "proposal_rationale",
            "title": "补齐 Section 1 → Section 2 的逻辑桥梁",
            "body": "原文从多智能体失败直接跳到 Judge reliability，缺少为什么需要 Judge 的理论过渡。",
            "severity": "major"
          },
          {
            "topicId": "logic",
            "kind": "proposal_rationale",
            "title": "明确研究问题递进关系",
            "body": "先证明系统存在选择失败，再验证 Judge 是否能够提供可靠信号。"
          }
        ]
      }
    ]
  }
}

Patch rules

• All patches target the same unchanged base document.
• Every patch must include at least one categorized comment.
• Every comment has one and only one primary topicId.
• target.oldText must resolve to exactly one location.
• Use contextBefore and contextAfter when the same text appears repeatedly.
• Overlapping patches and multiple insertions at an unsafe shared boundary are rejected.
• The server derives the proposal; the agent does not submit a second complete manuscript in the primary workflow.

Typical validation errors:

BASE_HASH_MISMATCH
ANCHOR_NOT_FOUND
ANCHOR_AMBIGUOUS
PATCH_OVERLAP
MISSING_PATCH_COMMENT
UNKNOWN_COMMENT_TOPIC

Topic-focused review

The UI shows topic tabs such as:

全部主题 12
架构与叙事 4
逻辑与论证 3
证据与引用 2
方法与统计 1
表达与清晰度 2

Selecting one topic filters the right-side comments to that topic. The manuscript pane can either:

• retain all patches and dim unrelated ones, or
• hide unrelated patches completely.

J and K navigate only the patches relevant to the active topic.

Local viewer fallback

For clients that do not render MCP Apps:

node src/cli.mjs \
  --viewer 4173 \
  --workspace /absolute/path/to/your/writing-workspace

The viewer binds to 127.0.0.1 and prints a random token-protected URL.

Synthetic demo:

npm run demo

Main tools

Model-facing workflow:

article_review_submit_patchset
article_review_open
article_review_get_feedback
article_review_add_comments
article_review_update_patchset
article_review_finalize

App-only review operations:

article_review_get_page
article_review_get_document
article_review_set_patch_decision
article_review_bulk_decide
article_review_edit_patch
article_review_add_comment
article_review_reply_comment
article_review_resolve_comment

Deprecated compatibility aliases:

article_review_create
article_review_get_summary
article_review_update_proposal
article_review_set_decision
article_review_edit_hunk

Safety invariants

• The base document is reconstructed byte-for-byte from raw segments.
• Applying every patch reconstructs the derived proposal byte-for-byte.
• CRLF, whitespace, Markdown, Chinese, English, and basic LaTeX are not normalized.
• Manuscript text is rendered as inert text nodes, never through innerHTML.
• Absolute paths, .. traversal, and directory symlink escape are rejected.
• Mutations require expectedVersion and idempotencyKey.
• Source overwrite requires explicit confirmation, source SHA-256 validation, and a backup.

Documentation

• Usage and workflow
• PatchSet protocol
• Editing-agent prompt
• Implemented architecture

Deferred scope

• DOCX Track Changes
• PDF editing
• Word-level partial acceptance
• Real-time multi-user collaboration
• Google Docs synchronization