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

Recipe: Analyze text readability via mcp-readability (npx)

Server: [email protected] · npm · stdio transport · Node.js Launch: npx -y mcp-readability Dependency: @modelcontextprotocol/sdk only — no external APIs, no auth

What it does

One tool — analyze_readability — computes four standard readability formulas on any input text:

• Flesch Reading Ease (0–100+, higher = easier)
• Flesch-Kincaid Grade Level (US school grade)
• SMOG Index (years of education needed)
• Automated Readability Index (ARI) (character-based grade level)

Returns: numeric scores, inferred reading level (Elementary → Graduate), target audience label, word/sentence/syllable stats, and optional improvement suggestions (long sentences, complex words, passive voice).

MCP handshake trace

→ initialize  {"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"pathfinder","version":"1.0.0"}}
← {"serverInfo":{"name":"mcp-readability","version":"1.0.0"},"capabilities":{"tools":{}}}

→ tools/list
← 1 tool: analyze_readability(text: string, include_suggestions?: boolean)

Invocation: mixed-complexity text

→ tools/call  analyze_readability
  {"text":"The quick brown fox jumps over the lazy dog. This is a simple sentence for testing readability metrics. Complex vocabulary and intricate sentence structures often indicate higher reading difficulty levels for the average consumer of written content."}

← {
    "scores": { "flesch_reading_ease": 29.7, "flesch_kincaid_grade": 12.2, "smog_index": 11.9, "ari": 11.5 },
    "reading_level": "High School (9th–12th grade)",
    "audience": "High school students",
    "stats": { "word_count": 37, "sentence_count": 3, "syllable_count": 72, "avg_words_per_sentence": 12.3, "avg_syllables_per_word": 1.95 },
    "summary": "Flesch Reading Ease: 29.7 | FK Grade: 12.2 | SMOG: 11.9 | ARI: 11.5 — High School (9th–12th grade) (37 words, 3 sentences)",
    "suggestions": ["2 words have 5+ syllables — consider simpler alternatives: readability, vocabulary"]
  }

Invocation: simple text (verify score range)

→ tools/call  analyze_readability
  {"text":"The cat sat on the mat. The dog ran in the park. I like to play. She went to school. We had fun today.","include_suggestions":false}

← "Flesch Reading Ease: 113.8 | FK Grade: -1.4 | SMOG: 3 | ARI: -4.5 — Elementary (under 6th grade) (24 words, 5 sentences)"

Invocation: legal jargon (extreme end)

→ tools/call  analyze_readability
  {"text":"Notwithstanding the aforementioned provisions pertaining to the substantive obligations of the contracting parties herein, the indemnification clause shall remain operative in perpetuity...","include_suggestions":true}

← {
    "scores": { "flesch_reading_ease": -51.8, "flesch_kincaid_grade": 30.2, "smog_index": 28.1, "ari": 34.4 },
    "reading_level": "Graduate (17th grade+)",
    "audience": "Graduate students / specialists",
    "suggestions": [
      "1 sentence exceeds 25 words — consider splitting...",
      "3 words have 5+ syllables — consider simpler alternatives: aforementioned, indemnification, modifications"
    ]
  }

Agent usage pattern

// Evaluate content before publishing
const result = await mcpCall('analyze_readability', {
  text: blogPost,
  include_suggestions: true
});
const scores = JSON.parse(result);
if (scores.scores.flesch_reading_ease < 60) {
  // Rewrite for broader audience
  // Use scores.suggestions to guide edits
}

Notes

• Scores correctly differentiate: simple text (Flesch 113.8, Elementary) → mixed (29.7, High School) → legal (-51.8, Graduate)
• Minimum ~2 sentences for reliable scores
• Pure compute — no network calls, no API keys, sub-second response
• 3 runs, 3 successes, 0 failures