readability-mcp-server

An MCP server that lets any AI agent check and improve the plain-language quality of its own text — before that text ever reaches a human. Fully local: no API key, no network call, no external service. It's a pure computation tool, so nothing you pass through it ever leaves the machine it's running on.

Unlike the other tools in this series (scamlens, clearread, clauselens), this one isn't a website a person opens — it's infrastructure for the AI agent ecosystem itself. Any MCP-compatible client (Claude Code, Claude Desktop, or any other) can call it directly.

Why

Agents generate a lot of text — replies, documentation, notices, error messages — and mostly have no way to check whether that text is actually easy for the recipient to read before sending it. This server gives any agent that self-check as a first-class tool call, using the same plain-language engine (sentence splitting + a vetted complex-to-plain word dictionary) already shipped and tested in clearread, the standalone web app in this series — here exposed for programmatic use instead of pasted by hand into a browser.

Tools

readability_score_text

Computes Flesch Reading Ease and Flesch-Kincaid Grade Level for a block of English text. Returns supported: false with structural counts only for non-Latin script, since the Flesch formulas assume English syllable patterns.

readability_simplify_text

Rewrites text in plainer language — splits overly long sentences at natural clause boundaries and substitutes common bureaucratic vocabulary for plainer equivalents — and reports the Flesch Reading Ease score before and after, so you can confirm the rewrite actually helped. English only, by design: word substitution is unreliable across languages with richer morphology, so non-Latin-script text is detected and passed through unchanged rather than risk broken grammar (see the note in src/services/simplify.ts about why a few tempting dictionary entries, like "accompanied" → "went with", were left out after they broke common fixed phrases like "must be accompanied by").

Install and configure

Clone and build:

git clone https://github.com/wedo911/readability-mcp-server.git
cd readability-mcp-server
npm install
npm run build

Add it to your MCP client's config (e.g. claude_desktop_config.json, or a project's .mcp.json for Claude Code):

{
  "mcpServers": {
    "readability": {
      "command": "node",
      "args": ["/absolute/path/to/readability-mcp-server/dist/index.js"]
    }
  }
}

Run the tests

npm run build
node --test tests/textStats.test.mjs tests/simplify.test.mjs

Try it without a client

The MCP Inspector can call tools directly from the command line:

npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name readability_simplify_text \
  --tool-arg text="Please utilize the enclosed form prior to the deadline."

License

MIT — see LICENSE.