Score text readability (Flesch, SMOG, ARI, grade level) via mcp-readability (npx)

Recipe: Text readability scoring via mcp-readability

Server

• Package: mcp-readability (npm, v1.0.0)
• Launch: npx mcp-readability (stdio, NDJSON framing)
• Engine: pure in-process calculation — no external API, no network calls
• Auth: none
• Tools: analyze_readability — one tool that returns all four standard indices

Tool schema

analyze_readability

• text (string, required) — the text to analyze, minimum ~2 sentences for reliable scores
• include_suggestions (boolean, optional, default true) — when true, returns improvement suggestions

Output structure

{
  "scores": {
    "flesch_reading_ease": -17.5,
    "flesch_kincaid_grade": 19.1,
    "smog_index": 15.6,
    "ari": 17.7
  },
  "reading_level": "Graduate (17th grade+)",
  "audience": "Graduate students / specialists",
  "stats": {
    "word_count": 41,
    "sentence_count": 3,
    "syllable_count": 102,
    "avg_words_per_sentence": 13.7,
    "avg_syllables_per_word": 2.49
  },
  "summary": "Flesch Reading Ease: -17.5 | FK Grade: 19.1 | SMOG: 15.6 | ARI: 17.7 — Graduate (17th grade+)",
  "suggestions": [
    "9 words have 5+ syllables — consider simpler alternatives: epistemological, ramifications, poststructuralist, fundamentally, incomprehensible"
  ]
}

Reading level scale

Elementary → Middle School → High School → College → Graduate (17th grade+)

Use cases

• Pre-publish check: ensure blog posts target 8th-grade level (Flesch RE ≥ 60)
• Documentation audit: verify API docs stay under college level
• Legal/compliance: flag text exceeding mandated readability thresholds
• A/B content: compare readability of two versions before shipping

Gotchas

• NDJSON framing (not Content-Length) — MCP SDK 1.29.0
• macOS /tmp → /private/tmp symlink requires realpath for the import.meta.url guard
• Flesch Reading Ease can go negative for extremely complex text (academic prose)
• Minimum ~2 sentences for reliable scores; single sentences may produce skewed results

Verified trace

→ {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"analyze_readability","arguments":{"text":"The quick brown fox jumps over the lazy dog. This is a simple sentence that most people can understand easily. However, the epistemological ramifications of poststructuralist deconstruction remain fundamentally incomprehensible to the uninitiated layperson, necessitating a comprehensive pedagogical framework for elucidation."}}}

← {"result":{"content":[{"type":"text","text":"{\"scores\":{\"flesch_reading_ease\":-17.5,\"flesch_kincaid_grade\":19.1,\"smog_index\":15.6,\"ari\":17.7},\"reading_level\":\"Graduate (17th grade+)\",\"audience\":\"Graduate students / specialists\",\"stats\":{\"word_count\":41,\"sentence_count\":3,\"syllable_count\":102,\"avg_words_per_sentence\":13.7,\"avg_syllables_per_word\":2.49},\"summary\":\"Flesch Reading Ease: -17.5 | FK Grade: 19.1 | SMOG: 15.6 | ARI: 17.7 — Graduate (17th grade+) (41 words, 3 sentences)\",\"suggestions\":[\"9 words have 5+ syllables — consider simpler alternatives: epistemological, ramifications, poststructuralist, fundamentally, incomprehensible\"]}"}]},"jsonrpc":"2.0","id":3}

Response time: under 5ms after server warm-up. Total handshake in ~4.8s including Node.js startup.