circe-mcp

An MCP server that checks text against the Circe Editorial Standard (CES) v0.3 and returns each violation with its rule ID, line and column, severity, confidence, and a suggested fix. Every check is deterministic pattern matching. The server makes no LLM calls, so a check costs nothing to run and gives the same answer every time.

The standard catches the writing patterns that read as machine-generated: em dashes, hedges, hollow intensifiers, trailing contrast clauses, negate-then-elevate constructions, throat-clearing openers, and the rest. This server is the standard's automated reviewer. The standard is a working draft by Avalynn Circe; explain_rule carries the text of every rule the server enforces.

Install

The server runs with npx, so there is nothing to install.

Claude Code

claude mcp add circe-mcp -- npx -y circe-mcp

Claude Desktop

Add the server to claude_desktop_config.json:

{
  "mcpServers": {
    "circe-mcp": {
      "command": "npx",
      "args": ["-y", "circe-mcp"]
    }
  }
}

Cursor, Windsurf, and other stdio clients use the same command and arguments. For a hosted deployment, npx circe-mcp http --port 3000 serves the same tools over Streamable HTTP at /mcp.

Node.js 20 or later is required.

Related MCP server: PromptWall MCP Server

Tools

Each tool returns a readable report as text and the full result as structured content, so a client can show one and a model can parse the other.

An example

Input to check_text:

It's not just code, it's craft. We built it in practice.

Output:

1:6      error      CES-C-008: Trailing contrast clause 'not just'. End the sentence at the positive point.  (also CES-Q-001, CES-C-001)
1:45     error      CES-V-007: Flourish 'in practice'. Delete it or make the claim as a plain statement.

2 error(s), 0 warning(s), 0 suggestion(s).

When violations overlap, the most severe one is reported and the others are listed under related. The first sentence trips three rules in one span; the report shows it once.

Rules

Severity follows the standard's tiers. MUST AVOID rules report as error, SHOULD AVOID rules as warning. Each violation also carries a confidence level, because a token match is sometimes a guess.

Two rules are off by default because they guess more than the others. Pass includeOptional: true to run them, or name them in rules.

The sub-forms of a rule come back in the form field. An inferior baseline reports as CES-V-007 with form: inferior-baseline, which is where the standard files it.

What it misses

Pattern matching catches stock phrasing. It cannot judge whether a short declarative is a pronouncement or the one line that states a paragraph's point (CES-C-007), whether a contrast carries facts the reader needs, or whether a paragraph is vague perfection (CES-V-004). The flourish and sass detectors catch the signature phrases and will miss cases that need a reader. measure_text reports the numbers behind the judgment calls and leaves the call to the writer.

Rules that need a human stay out of check_text: the deletion test for CES-C-003 through CES-C-007 beyond their stock forms, manufactured intimacy (CES-V-002), scene-painting (CES-V-003), and the sections of the standard that cover factual accuracy, document structure, and typography.

Exceptions

A contrast that carries facts the reader needs is allowed under CES-C-008, such as a migration from one database to another. Mark a justified exception with an inline directive in an HTML comment, which renders as nothing:

<!-- ces ignore CES-C-008 -->
The team moved the reports from MS Access to SQL Server rather than rewriting them.
<!-- ces end -->

A directive takes one or more rule IDs, in any case, separated by spaces or commas. Without an end marker it runs to the end of the text. <!-- ces end CES-C-008 --> closes one rule and leaves the others open. <!-- ces off --> and <!-- ces on --> silence every rule for a section. For a single call, pass the rule IDs to skip in the ignore parameter.

Markdown

Fenced code blocks, inline code, link destinations, HTML tags, and comments are skipped. Front matter is checked, because a page description is prose. Pass checkCode: true to lint code comments too (CES-K-003). Line and column numbers refer to the original text.

Fixes

fix_text applies the fixes that have one safe answer. An em dash becomes a comma, with the spaces around it absorbed. A hedge or hollow intensifier is deleted along with one adjacent space, and the next word is capitalized when the deleted word opened the sentence. A fixable word inside a larger construction is left in place, because the construction needs a rewrite, not a deletion. Review an em dash fix that joins two independent clauses; the standard allows a semicolon or a new sentence there, and the fixer cannot tell which.

Every other rule is report-only.

The rules file

rules/ces.yaml is the single source of truth. Each rule carries its ID, severity, description, message, suggestion, exception, a before/after example, and its tokens with per-token severity and confidence. Heuristic rules name a detector in src/detectors.ts. The server loads the file at startup and validates every entry, so a typo in a rule fails fast with a message that names the rule and the field.

Adding a rule is one YAML entry plus a fixture with a text it flags and a text it passes. The test suite refuses a rule without a fixture and a fixture without a rule.

Command line

circe-mcp                        # MCP server on stdio
circe-mcp http --port 3000       # MCP server over Streamable HTTP
circe-mcp check README.md docs/  # lint files; exit 1 on an error-level hit
circe-mcp fix draft.md --write   # apply the safe fixes in place
circe-mcp measure draft.md       # statistics as JSON

check takes --fail-on warning to make warnings fail too, --include-optional to run the optional rules, and --json for machine-readable output.

Development

npm install
npm test             # Vitest: fixtures per rule, positions, exceptions, fixes, MCP round trip
npm run typecheck
npm run build        # compiles to dist/; the server reads rules/ces.yaml from the package root
npm run check        # typecheck, test, build

Every rule has at least one fixture that it flags and one that it passes, and its own before/after example from the standard is tested the same way. The README and the tool descriptions are checked against the standard in the test suite and in CI, so this file passes check_text with zero violations, optional rules included. A 10,000-word check completes in under 200 ms.

DECISIONS.md records the design decisions and the reasoning behind them, including where each rule's ID comes from and why two rules ship off by default.

License

MIT. See LICENSE.