@roughen/mcp 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Upforge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# @roughen/mcp
+
+A local MCP server that lets any AI tool check its own writing against measured human-writing baselines, then verify its rewrite. It runs on your machine over stdio. There are no network calls or model calls, and it never writes a file. Your model does the rewriting; Roughen measures before and after.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `roughen_check` | Checks a draft and returns a revision brief: which passages to rewrite, how many, why, and what must not change. `returnFixed: true` also returns the text with safe mechanical fixes applied. |
+| `roughen_check_file` | The same for a local file: Markdown, MDX, HTML, text, or the copy in a `.tsx`/`.jsx`/`.ts`/`.js` component. It uses the nearest `roughen.config`. |
+| `roughen_compare` | Compares an original with a revision. It checks that every figure, link, code sample, quotation and heading survived, that nothing was added, that length stayed within 15%, and that the flagged habits dropped. Then it says which version to use. |
+| `roughen_site` | For a Next.js app-router project, returns the copy pass plan: copy and findings per route and per file, copy no route ships, and work groups of files with no overlap. Pass a `group` id to get that group's revision briefs. Protected strings (H1s, titles, FAQ questions, keywords, quotes) are marked and never offered for rewriting. |
+| `roughen_verify` | Compares every changed file under a path with its version at a git commit (default `HEAD`). Fails on code changes, files that no longer parse, edited protected strings, lost or invented numbers and links, new banned characters, rewritten copy beyond 15% of its length, and habits that grew. |
+
+The `humanize` prompt runs the whole loop: check, revise what's flagged, compare, and return the accepted version. The `site_pass` prompt does the same for one work group of a site: plan, edit, verify. Every tool is read-only; `roughen_verify` reads old versions through git.
+
+## Set up
+
+Until the package is published, point clients at this checkout, after running `pnpm install` at the repo root. Node 22.13 or newer is required.
+
+**Claude Desktop.** Add this to `~/Library/Application Support/Claude/claude_desktop_config.json` and restart the app:
+
+```json
+{
+  "mcpServers": {
+    "roughen": {
+      "command": "node",
+      "args": ["/Volumes/Uptrade Media/GitHub/Upforge/roughen/packages/mcp/bin/roughen-mcp.mjs"]
+    }
+  }
+}
+```
+
+**Cursor.** Use the same `mcpServers` entry in `~/.cursor/mcp.json`.
+
+**Claude Code.** Register the server for all your projects:
+
+```bash
+claude mcp add --scope user roughen -- node "/Volumes/Uptrade Media/GitHub/Upforge/roughen/packages/mcp/bin/roughen-mcp.mjs"
+```
+
+In Claude Code, the [Roughen plugin](../../plugins/roughen/README.md) adds a hook that checks files as Claude writes them. The MCP server is for tools without hooks, and for checking copy you're drafting in chat.
+
+## What it checks
+
+Everything in [`@roughen/core`](../core/README.md). The rules that matter for generated copy are the ones measured against 110 human documents: list saturation, contrast frames, generalizing hedges, reveal frames, em-dash and semicolon density, long sentences, and flat rhythm. Each fires only above what 95% of human documents do. [baselines-001](../../research/corpus/reports/baselines-001.md) and [claude-001](../../research/corpus/reports/claude-001.md) have the numbers and their limits. MIT.

package/bin/roughen-mcp.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// Roughen's local MCP server over stdio. Stdout carries the protocol, so
+// diagnostics go to stderr only.
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer, serverVersion, coreVersion } from '../lib/server.mjs';
+
+if (process.argv.includes('--version')) {
+  process.stdout.write(`roughen-mcp ${serverVersion} (core ${coreVersion})\n`);
+} else {
+  await createServer().connect(new StdioServerTransport());
+  process.stderr.write(`roughen-mcp ${serverVersion} (core ${coreVersion}) ready on stdio\n`);
+}

package/lib/server.mjs

@@ -0,0 +1,191 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { judgeRevision, listRules, version as coreVersion } from '@roughen/core';
+import { loadConfig, included } from '@roughen/cli/lib/config.mjs';
+import { formatFor } from '@roughen/cli/lib/lint-file.mjs';
+import { review, mechanicalSummary } from '@roughen/cli/lib/review.mjs';
+import { planSite, renderPlan, renderGroupBrief } from '@roughen/cli/lib/site.mjs';
+import { verifyGit, renderVerify } from '@roughen/cli/lib/verify.mjs';
+
+export const serverVersion = '0.2.0';
+const proseFormat = z.enum(['md', 'mdx', 'html', 'text']).default('md').describe('How to read the text: Markdown (default), MDX, an HTML fragment, or plain text.');
+const readOnly = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+
+const text = (body) => ({ content: [{ type: 'text', text: body }] });
+const failure = (message) => ({ content: [{ type: 'text', text: message }], isError: true });
+
+/** The report every check tool returns: what to rewrite, and the mechanical fixes. */
+function report(subject, source, reviewed, { returnFixed = false } = {}) {
+  const { result, brief, mechanical, fixed } = reviewed;
+  const { metrics } = result;
+  const lines = [`Roughen checked ${subject}: ${metrics.wordCount} body words in ${metrics.sentenceCount} sentences${metrics.meanSentenceLength ? `, ${metrics.meanSentenceLength.toFixed(1)} words a sentence on average` : ''}.`];
+  if (!brief.needed && !mechanical.length) {
+    lines.push('', "Nothing to revise: no habit crossed Roughen's human-writing baselines.");
+    return text(lines.join('\n'));
+  }
+  if (brief.needed) lines.push('', brief.text);
+  if (mechanical.length) {
+    lines.push('', mechanicalSummary(mechanical));
+    if (fixed !== null && fixed !== source) {
+      lines.push(returnFixed ? `\nText with the mechanical fixes applied:\n\n${fixed}` : 'Call again with returnFixed: true to get the text with those fixes applied.');
+    }
+  }
+  if (brief.needed) lines.push('', 'After revising, call roughen_compare with the original and your revision to confirm the facts survived and the flagged habits dropped.');
+  return text(lines.join('\n'));
+}
+
+/**
+ * Roughen as an MCP server. Everything runs locally and deterministically:
+ * no network, no model calls, and no tool writes a file. The client's model
+ * does the rewriting; Roughen measures before and after.
+ */
+export function createServer() {
+  const server = new McpServer({ name: 'roughen', version: serverVersion }, {
+    instructions: 'Roughen checks AI-written copy against measured human-writing baselines. Use roughen_check (or roughen_check_file) on a draft, revise only what the brief flags, then roughen_compare the original and your revision before using it. For a whole Next.js site, roughen_site plans the pass in groups of files and roughen_verify checks the edited files against git. It never rewrites text itself and makes no authorship claims.',
+  });
+
+  server.registerTool('roughen_check', {
+    title: 'Check copy',
+    description: 'Check a draft for the habits that make AI writing read as generated (comma-list saturation, "X, not Y" frames, hedging, em-dash and semicolon density, long or flat sentences, assistant framing, invisible characters). Returns a revision brief: which passages to rewrite, how many, why, and what must not change. Local and deterministic.',
+    inputSchema: {
+      text: z.string().min(1).describe('The copy to check.'),
+      format: proseFormat,
+      returnFixed: z.boolean().default(false).describe('Also return the text with safe mechanical fixes applied (spacing, invisible characters, assistant framing).'),
+    },
+    annotations: { title: 'Check copy', ...readOnly },
+  }, async ({ text: source, format, returnFixed }) => report('the text', source, review(source, { format }), { returnFixed }));
+
+  server.registerTool('roughen_check_file', {
+    title: 'Check a file',
+    description: 'Check the copy in a local file: Markdown, MDX, HTML or text, or the JSX text and copy props of a .tsx/.jsx/.ts/.js component. Uses the nearest roughen.config for project voice rules. Reads the file; never writes it.',
+    inputSchema: {
+      path: z.string().min(1).describe('Absolute path to the file.'),
+      returnFixed: z.boolean().default(false).describe('For prose files, also return the text with safe mechanical fixes applied.'),
+    },
+    annotations: { title: 'Check a file', ...readOnly },
+  }, async ({ path: file, returnFixed }) => {
+    if (!path.isAbsolute(file)) return failure('Give an absolute path; this server has no working directory of its own.');
+    const format = formatFor(file);
+    if (!format) return failure(`Roughen reads .md, .mdx, .html, .htm, .txt, .tsx, .jsx, .ts and .js files, not ${path.extname(file) || 'files without an extension'}.`);
+    let source;
+    try { source = await readFile(file, 'utf8'); } catch (error) { return failure(`Couldn't read ${file}: ${error.code ?? error.message}`); }
+    const loaded = await loadConfig(file);
+    if (!included(file, loaded)) return text(`${file} is excluded by ${path.join(loaded.dir, 'roughen.config')}'s include/exclude globs, so Roughen didn't check it.`);
+    try {
+      return report(path.basename(file), source, review(source, { file, format, config: loaded.config }), { returnFixed });
+    } catch (error) {
+      return failure(`Roughen couldn't read the copy in ${file}: ${error.message}`);
+    }
+  });
+
+  server.registerTool('roughen_compare', {
+    title: 'Verify a revision',
+    description: 'Compare an original draft with your revision. Reports whether every figure, link, code sample, quotation and heading survived, whether anything was added, whether the length stayed in bounds, and whether the flagged habits decreased, then says which version to use.',
+    inputSchema: {
+      original: z.string().min(1).describe('The draft before revision.'),
+      revised: z.string().min(1).describe('Your revision.'),
+      format: proseFormat,
+    },
+    annotations: { title: 'Verify a revision', ...readOnly },
+  }, async ({ original, revised, format }) => {
+    const judgment = judgeRevision(original, revised, { format });
+    const after = review(revised, { format });
+    const lines = [
+      judgment.accepted ? 'Use the revision.' : 'Keep the original, or fix the revision and compare again.',
+      '',
+      `Facts: ${judgment.preservation.ok ? 'every figure, link, code sample, quotation and heading survived, and nothing was added' : judgment.preservation.reasons.join(' ')}`,
+      `Length: ${judgment.preservation.lengthRatio.toFixed(2)}× the original's body text.`,
+      judgment.rules.length
+        ? `Flagged habits: ${judgment.flaggedBefore} before, ${judgment.flaggedAfter} after (${judgment.rules.join(', ')}).`
+        : 'Flagged habits: the original had none that asked for a rewrite.',
+    ];
+    if (after.brief.needed) lines.push('', 'Still flagged in the revision:', '', after.brief.text);
+    return text(lines.join('\n'));
+  });
+
+  server.registerTool('roughen_site', {
+    title: 'Plan a site copy pass',
+    description: 'For a Next.js app-router project: which copy each route ships (following imports and tsconfig paths), the findings per route and per file, copy no route ships, and a work plan of file groups with no overlap. Pass a group id to get that group\'s revision briefs instead. Protected strings (H1s, titles, FAQ questions, keywords, quotes) are marked and never offered for rewriting. Reads files; never writes.',
+    inputSchema: {
+      path: z.string().min(1).describe('Absolute path to the project root (the directory holding app/ or src/app/).'),
+      group: z.string().optional().describe('A work-group id from the plan, such as "services-2". Returns that group\'s files with a revision brief for each.'),
+      groupWords: z.number().int().min(100).default(6000).describe('Editable words per work group.'),
+    },
+    annotations: { title: 'Plan a site copy pass', ...readOnly },
+  }, async ({ path: root, group, groupWords }) => {
+    if (!path.isAbsolute(root)) return failure('Give an absolute path; this server has no working directory of its own.');
+    let site;
+    try { site = await planSite(root, { groupWords }); } catch (error) { return failure(error.message); }
+    if (!group) return text(`${renderPlan(site)}\nCall roughen_site again with a group id to get its revision briefs. After editing a group, call roughen_verify on the project.`);
+    const found = site.plan.find((item) => item.id === group);
+    if (!found) return failure(`No work group "${group}". Groups: ${site.plan.map((item) => item.id).join(', ')}.`);
+    return text(`${renderGroupBrief(site, found)}\nWhen you're done, call roughen_verify on ${root} to check the edits kept their facts and left the code alone.`);
+  });
+
+  server.registerTool('roughen_verify', {
+    title: 'Verify copy edits against git',
+    description: 'Compare every changed file under a path with its version at a git commit (default HEAD). Fails on code changes, files that no longer parse, edited protected strings (H1s, titles, FAQ questions, keywords, quotes), lost or invented numbers and links, new banned characters, rewritten copy beyond 15% of its length, and habits that grew. Read-only: it reads files and asks git for the old versions.',
+    inputSchema: {
+      path: z.string().min(1).describe('Absolute path to a file or directory inside a git repository.'),
+      ref: z.string().min(1).default('HEAD').describe('The commit to compare against.'),
+    },
+    annotations: { title: 'Verify copy edits against git', ...readOnly },
+  }, async ({ path: target, ref }) => {
+    if (!path.isAbsolute(target)) return failure('Give an absolute path; this server has no working directory of its own.');
+    let result;
+    try { result = await verifyGit({ paths: [target], ref }); } catch (error) { return failure(error.message); }
+    return text(`${result.ok ? 'Verified: no errors.' : 'Not verified: fix the errors below and verify again.'}\n\n${renderVerify(result)}`);
+  });
+
+  server.registerPrompt('site_pass', {
+    title: 'Revise a site\'s copy',
+    description: 'Revise one work group of a Next.js site\'s copy so it reads like a person wrote it, then verify the edits.',
+    argsSchema: { path: z.string().describe('Absolute path to the project root.'), group: z.string().optional().describe('The work group to take. Leave empty to plan first.') },
+  }, ({ path: root, group }) => ({
+    messages: [{
+      role: 'user',
+      content: {
+        type: 'text',
+        text: `Revise the copy of the Next.js site at ${root} so it reads like a person wrote it.
+
+1. ${group ? `Call roughen_site with path ${root} and group "${group}".` : `Call roughen_site with path ${root} to see the plan, pick a work group, then call it again with that group id.`}
+2. Edit only the files in that group, and only the text inside strings and JSX. Never change keys, imports, class names, links or the number of items. Leave protected strings exactly as written: H1s, titles and headlines, FAQ questions, keywords, schema names, quotations and citations.
+3. Fix what each brief asks for. Keep every number, price, date, name and link exactly as written, don't add claims, and keep each string within about 15% of its length.
+4. Call roughen_verify with path ${root}. Fix every error it names and verify again, at most twice.
+5. Report the files you changed, what verify said, and anything you left alone on purpose.`,
+      },
+    }],
+  }));
+
+  server.registerPrompt('humanize', {
+    title: 'Make copy read human',
+    description: 'Revise copy so it reads like a person wrote it, using Roughen to check and verify.',
+    argsSchema: { text: z.string().optional().describe('The copy to revise. Leave empty to revise the copy in the conversation.') },
+  }, ({ text: source }) => {
+    const habits = listRules().filter((rule) => rule.severity !== 'info').map((rule) => `- ${rule.id}: ${rule.description}`).join('\n');
+    return {
+      messages: [{
+        role: 'user',
+        content: {
+          type: 'text',
+          text: `Revise this copy so it reads like a person wrote it.
+
+1. Call roughen_check on it.
+2. Rewrite only the passages the brief flags, as many as it asks. Keep every number, price, date, name, link, quotation and code sample exactly as written. Don't add facts or examples; if a hedge hides a specific you don't have, cut the hedge.
+3. Call roughen_compare with the original and your revision. If it says to keep the original, fix what it names and compare again, at most twice.
+4. Return the version roughen_compare accepted, and say in one line what changed.
+
+Roughen checks these habits against 110 human-written documents:
+${habits}
+${source ? `\nThe copy:\n\n${source}` : ''}`,
+        },
+      }],
+    };
+  });
+
+  return server;
+}
+
+export { coreVersion };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@roughen/mcp",
+  "version": "0.2.0",
+  "description": "Local MCP server that checks AI writing against human baselines and verifies rewrites. No network, no model calls.",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "prose",
+    "linter",
+    "writing",
+    "ai-writing",
+    "copy"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.13"
+  },
+  "bin": {
+    "roughen-mcp": "./bin/roughen-mcp.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "zod": "^4.6.5",
+    "@roughen/cli": "^0.3.0",
+    "@roughen/core": "^0.3.0"
+  },
+  "scripts": {
+    "build": "node --check bin/roughen-mcp.mjs && node --check lib/server.mjs"
+  }
+}