# readability-mcp-server

[![Glama score](https://glama.ai/mcp/servers/wedo911/readability-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/wedo911/readability-mcp-server)

An [MCP](https://modelcontextprotocol.io) 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](https://github.com/wedo911/scamlens),
[clearread](https://github.com/wedo911/clearread), [clauselens](https://github.com/wedo911/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](https://github.com/wedo911/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:

```bash
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):

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

## Run the tests

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

## Try it without a client

The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) can
call tools directly from the command line:

```bash
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](LICENSE).