content-qa-mcp

An MCP (Model Context Protocol) server for editorial content QA. Point Claude at an article and get a findings report where every finding comes with the fix attached, so the report is usable instead of only correct.

The test suite checks that contract on a deliberately broken sample article: every finding the article triggers must carry a non-empty fix. In the source, each of the 20 finding paths is paired with a fix.

What it does

Four tools, one prompt, zero API keys. Everything runs locally.

Plus a qa_review prompt that drives the full report and asks the model for an editorial verdict without softening or inventing findings.

Every finding is one object:

{
  "check": "seo-onpage",
  "severity": "high",
  "excerpt": null,
  "finding": "No meta description.",
  "fix": "Add a 120-155 character meta description that states the article's payoff and includes the keyword once."
}

See a full run in samples/sample-report.md: 22 findings on the deliberately broken fixture article, regenerable with npm run sample.

Related MCP server: OpenSEO-Lite

Install and register in Claude Code

git clone https://github.com/Alvi-808/content-qa-mcp.git
cd content-qa-mcp
npm install
npm test        # 14 tests, includes a real MCP client/server handshake

Register (Claude Code CLI):

claude mcp add content-qa -- node /absolute/path/to/content-qa-mcp/src/server.js

Verified working:

content-qa: C:\Program Files\nodejs\node.exe C:\...\content-qa-mcp\src\server.js - √ Connected

Then, in a Claude Code session: "run qa_full_report on this article" or use the qa_review prompt.

Remove with claude mcp remove content-qa.

Windows note (the part most tutorials skip)

On Windows, register stdio MCP servers with the absolute path to node.exe and the script:

claude mcp add content-qa -- "C:\Program Files\nodejs\node.exe" "C:\path\to\content-qa-mcp\src\server.js"

Registrations that go through npx or a .cmd shim routinely fail to connect on Windows because the spawned process never attaches stdio correctly, and the failure is silent. Absolute node.exe plus the script path works every time. The end-to-end test in this repo uses the same pattern (process.execPath).

Design notes

• Checks are pure functions in src/checks/, importable without MCP. The server is a thin protocol layer over them, so the same checks can run in CI, a git hook, or a pipeline.

• The SEO check is scoped on purpose. It parses well-formed CMS article output (WordPress, Ghost, static-site generators) with regex extraction. It is not a general HTML parser and does not try to survive adversarial markup. Naming the boundary beats pretending there isn't one.

• Plain-text input skips the SEO check instead of reporting fake "missing tag" findings.

• The stock-phrase list bans classes, not strings. Each entry is a pattern, so one-word rewrites of a cliche still get caught.

Why this exists

This is the working method behind my paid editorial QA work, packaged as tools an agent can call. The rule it encodes: a QA report that says what is wrong without saying what to do next just moves the work to someone else's desk. Findings ship with fixes or they don't ship.

License

MIT