essay-stats-mcp 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0
+
+- First version.
+- count_text counts words, characters, sentences and paragraphs, and estimates pages for a font, font size and line spacing.
+- readability_scores returns Flesch Kincaid grade, Flesch reading ease, Gunning Fog and SMOG.
+- style_flags finds passive voice, repeated sentence openers, filler words and long sentences.
+- check_word_limit compares a text with a word limit, with an optional minimum, a tolerance, and the option to leave out references and quotes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AnonymousOnyx22
+
+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

@@ -1,3 +1,81 @@
-# Temporary Holding Version
+# Essay Stats MCP
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Offline writing metrics for essays. It covers word and page counts, readability, passive voice, repeated words and reading time, so you can check your work against assignment requirements before you hand it in.
+
+It runs on your computer. There is no account, no API key and no network call. Your essay text never leaves your machine.
+
+## Quick start
+
+Add this to the MCP config of your app:
+
+```json
+{
+  "mcpServers": {
+    "essay-stats": {
+      "command": "npx",
+      "args": ["-y", "essay-stats-mcp"]
+    }
+  }
+}
+```
+
+It needs Node.js 20 or newer.
+
+Where the config lives:
+
+- Claude Desktop: Settings, Developer, Edit Config (`claude_desktop_config.json`).
+- Claude Code: run `claude mcp add essay-stats -- npx -y essay-stats-mcp`.
+- Cursor: Settings, MCP, or `.cursor/mcp.json` in your project.
+- VS Code: `.vscode/mcp.json`. VS Code uses a `servers` key instead of `mcpServers`.
+- Windsurf: `~/.codeium/windsurf/mcp_config.json`.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `count_text` | Words, characters, sentences, paragraphs, reading time and an estimated page count for a font, size and line spacing. |
+| `readability_scores` | Flesch Kincaid grade, Flesch reading ease, Gunning Fog and SMOG. |
+| `style_flags` | Passive voice, repeated sentence openers, filler words and long sentences. |
+| `check_word_limit` | Compares the text with a word limit. Optional minimum, tolerance, and leaving out references and quotes. |
+
+All four tools only read the text you give them. Each one returns a short written answer and the same numbers as structured fields.
+
+### count_text
+
+Inputs: `text`, and optional `font` (times new roman, arial, calibri, georgia, courier new or verdana), `font_size` in points (default 12) and `spacing` (single, 1.5 or double, default double). The page count is an estimate from typical words per page, so Word or Google Docs may differ by a little.
+
+### readability_scores
+
+Input: `text`. The grades are roughly US school grades, so 12 is the end of high school. SMOG is designed for 30 sentences or more, so on a short text the result is marked as less reliable.
+
+### style_flags
+
+Inputs: `text` and optional `max_sentence_words` (default 30). The checks are simple pattern rules. Use them as a prompt to reread a sentence, not as proof of a mistake.
+
+### check_word_limit
+
+Inputs: `text`, `limit`, and optional `minimum`, `tolerance_percent`, `exclude_references` and `exclude_quotes`. References are cut from a heading line such as References, Works Cited or Bibliography to the end. Quotes are lines starting with `>` and text inside double quotes.
+
+## Example prompts
+
+- "Count the words in this essay and tell me how many pages it is in Arial 11 point with 1.5 spacing."
+- "What reading level is this essay? Give me the Flesch Kincaid, Gunning Fog and SMOG scores."
+- "Find the passive voice and filler words in my draft."
+- "My limit is 1500 words, not counting the works cited or quotes. Am I over?"
+- "Which sentences are over 25 words long?"
+
+## Privacy
+
+Everything is calculated locally by a small Node.js program talking to your app over standard input and output. It makes no network requests, stores nothing and needs no keys or passwords. The text you paste is used for the one call and then dropped.
+
+## Development
+
+```
+npm install
+npm run build
+npm test
+```
+
+## License
+
+MIT

package/build/src/core/tools.js

@@ -0,0 +1,21 @@
+export function runTool(tool, args) {
+    try {
+        const out = tool.run(args);
+        return { content: [{ type: "text", text: out.text }], structuredContent: out.structured };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: msg }], isError: true };
+    }
+}
+export function registerTools(server, tools) {
+    for (const tool of tools) {
+        server.registerTool(tool.name, {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            outputSchema: tool.outputSchema,
+            annotations: { readOnlyHint: true, openWorldHint: false },
+        }, async (args) => runTool(tool, args));
+    }
+}

package/build/src/index.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer, VERSION } from "./server.js";
+function usage() {
+    console.log(`essay-stats-mcp ${VERSION}
+
+Offline writing metrics for essays: word and page counts, readability, style flags and word limit checks.
+
+Add it to your MCP app's config with command "npx" and args ["-y", "essay-stats-mcp"].
+
+  --help, --version`);
+}
+async function main() {
+    const cmd = process.argv[2];
+    if (cmd === "--help" || cmd === "-h")
+        return usage();
+    if (cmd === "--version" || cmd === "-v")
+        return console.log(VERSION);
+    await createServer().connect(new StdioServerTransport());
+    console.error(`essay-stats-mcp ${VERSION} running`);
+}
+main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+});

package/build/src/server.js

@@ -0,0 +1,9 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerTools } from "./core/tools.js";
+import { tools } from "./tools.js";
+export const VERSION = "0.1.0";
+export function createServer() {
+    const server = new McpServer({ name: "essay-stats-mcp", version: VERSION });
+    registerTools(server, tools);
+    return server;
+}

package/build/src/text.js

@@ -0,0 +1,194 @@
+/** Text analysis helpers. Everything here is pure and works offline. */
+const ABBREVIATIONS = new Set([
+    "mr", "mrs", "ms", "dr", "prof", "sr", "jr", "st", "vs", "etc", "e.g", "i.e", "fig", "no", "al",
+]);
+export function words(text) {
+    return text.match(/[A-Za-z0-9]+(?:['’][A-Za-z]+)*(?:-[A-Za-z0-9]+)*/g) ?? [];
+}
+/** Whitespace separated word count, which is how word processors count. */
+export function wordCount(text) {
+    const t = text.trim();
+    return t === "" ? 0 : t.split(/\s+/).filter((w) => /[A-Za-z0-9]/.test(w)).length;
+}
+export function splitSentences(text) {
+    const out = [];
+    const flat = text.replace(/\s+/g, " ").trim();
+    if (!flat)
+        return out;
+    let start = 0;
+    const re = /[.!?]+["'”’)\]]*\s+/g;
+    let m;
+    while ((m = re.exec(flat))) {
+        const end = m.index + m[0].length;
+        const before = flat.slice(start, m.index + 1);
+        const lastWord = (before.match(/([A-Za-z.]+)\.$/)?.[1] ?? "").toLowerCase().replace(/\.$/, "");
+        const next = flat[end] ?? "";
+        const isAbbrev = m[0].startsWith(".") && ABBREVIATIONS.has(lastWord);
+        const isInitial = /(^|\s)[A-Z]\.$/.test(before.trim());
+        if (isAbbrev || isInitial || (m[0].startsWith(".") && /[a-z]/.test(next)))
+            continue;
+        out.push(flat.slice(start, end).trim());
+        start = end;
+    }
+    const rest = flat.slice(start).trim();
+    if (rest)
+        out.push(rest);
+    return out.filter((s) => /[A-Za-z0-9]/.test(s));
+}
+export function splitParagraphs(text) {
+    return text
+        .split(/\r?\n\s*\r?\n/)
+        .map((p) => p.trim())
+        .filter((p) => /[A-Za-z0-9]/.test(p));
+}
+export function syllables(word) {
+    let w = word.toLowerCase().replace(/[^a-z]/g, "");
+    if (!w)
+        return 0;
+    if (w.length <= 3)
+        return 1;
+    w = w.replace(/(?:[^laeiouy]es|ed|[^laeiouy]e)$/, "").replace(/^y/, "");
+    const groups = w.match(/[aeiouy]{1,2}/g);
+    return Math.max(1, groups ? groups.length : 1);
+}
+export const round = (n, places = 1) => {
+    const f = 10 ** places;
+    return Math.round(n * f) / f;
+};
+/** Words per page for double and single spacing at common fonts and sizes. */
+const FONT_WORDS_PER_PAGE = {
+    "times new roman": 550,
+    arial: 500,
+    calibri: 520,
+    georgia: 480,
+    "courier new": 400,
+    verdana: 430,
+};
+export const FONTS = Object.keys(FONT_WORDS_PER_PAGE);
+export function pageEstimate(wordTotal, font, fontSize, spacing) {
+    const base = FONT_WORDS_PER_PAGE[font.trim().toLowerCase()];
+    if (base === undefined) {
+        throw new Error(`Unknown font "${font}". Use one of: ${FONTS.join(", ")}.`);
+    }
+    const sizeFactor = 12 / fontSize;
+    const spacingFactor = spacing === "single" ? 1 : spacing === "1.5" ? 1 / 1.5 : 0.5;
+    const perPage = base * sizeFactor * sizeFactor * spacingFactor;
+    return wordTotal / perPage;
+}
+export function counts(text) {
+    const ws = words(text);
+    let syl = 0;
+    let complex = 0;
+    for (const w of ws) {
+        const s = syllables(w);
+        syl += s;
+        if (s >= 3)
+            complex += 1;
+    }
+    return {
+        words: ws.length,
+        sentences: splitSentences(text).length,
+        syllables: syl,
+        complexWords: complex,
+        polysyllables: complex,
+    };
+}
+const IRREGULAR_PARTICIPLES = new Set([
+    "done", "made", "given", "taken", "seen", "known", "shown", "written", "chosen", "found", "held",
+    "built", "sent", "kept", "left", "lost", "paid", "read", "said", "sold", "told", "thought",
+    "brought", "caught", "taught", "bought", "begun", "broken", "driven", "eaten", "fallen", "forgotten",
+    "gotten", "grown", "hidden", "ridden", "spoken", "stolen", "thrown", "worn", "won", "set", "put",
+    "cut", "hit", "let", "led", "met", "understood", "drawn", "born", "run", "become", "gone",
+]);
+const NOT_PARTICIPLES = new Set([
+    "need", "indeed", "speed", "feed", "seed", "red", "bed", "hundred", "embed",
+    // Adjectives that look like participles and usually describe a state.
+    "tired", "excited", "interested", "worried", "bored", "scared", "surprised", "pleased", "concerned",
+    "confused", "relaxed", "exhausted", "satisfied", "disappointed", "amazed", "shocked", "annoyed",
+    "supposed", "used", "married", "prepared", "ashamed", "afraid", "determined", "talented", "advanced",
+]);
+export function findPassive(sentences) {
+    const hits = [];
+    const re = /\b(am|is|are|was|were|be|been|being)\s+(?:(?:not|also|often|always|never|already|still|just|really|then|even|first|later|usually|generally)\s+)*([a-z]+)\b/gi;
+    for (const s of sentences) {
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(s))) {
+            const part = m[2].toLowerCase();
+            if (NOT_PARTICIPLES.has(part))
+                continue;
+            const regular = part.length > 3 && part.endsWith("ed");
+            if (regular || IRREGULAR_PARTICIPLES.has(part)) {
+                hits.push({ sentence: s, phrase: m[0] });
+                break;
+            }
+        }
+    }
+    return hits;
+}
+const FILLER_WORDS = [
+    "very", "really", "just", "quite", "actually", "basically", "literally", "totally", "simply",
+    "rather", "somewhat", "definitely", "extremely", "certainly", "essentially", "virtually",
+];
+const FILLER_PHRASES = [
+    "in order to", "due to the fact that", "at the end of the day", "it is important to note that",
+    "in my opinion", "a lot of", "kind of", "sort of", "needless to say", "for all intents and purposes",
+    "the fact that", "in the event that", "at this point in time",
+];
+export function findFiller(text) {
+    const lower = text.toLowerCase();
+    const found = [];
+    for (const item of [...FILLER_PHRASES, ...FILLER_WORDS]) {
+        const re = new RegExp(`\\b${item.replace(/ /g, "\\s+")}\\b`, "g");
+        const n = (lower.match(re) ?? []).length;
+        if (n > 0)
+            found.push({ text: item, count: n });
+    }
+    return found.sort((a, b) => b.count - a.count || a.text.localeCompare(b.text));
+}
+/** Words that start 3 or more sentences, or 2 or more in a row. */
+export function findRepeatedOpeners(sentences, minRun = 2) {
+    const openers = sentences.map((s) => (words(s)[0] ?? "").toLowerCase());
+    const byWord = new Map();
+    openers.forEach((w, i) => {
+        if (!w)
+            return;
+        byWord.set(w, [...(byWord.get(w) ?? []), i + 1]);
+    });
+    const hits = [];
+    for (const [word, idx] of byWord) {
+        let run = 1;
+        let longest = 1;
+        for (let i = 1; i < idx.length; i++) {
+            run = idx[i] === idx[i - 1] + 1 ? run + 1 : 1;
+            longest = Math.max(longest, run);
+        }
+        if (idx.length >= 3 || longest >= minRun)
+            hits.push({ word, count: idx.length, sentences: idx });
+    }
+    return hits.sort((a, b) => b.count - a.count || a.word.localeCompare(b.word));
+}
+/**
+ * Cuts out a references section (everything from a heading such as "References",
+ * "Works Cited" or "Bibliography" on its own line) and returns what is left.
+ */
+export function stripReferences(text) {
+    const re = /^[ \t]*(references|works cited|bibliography|reference list|sources)[ \t]*:?[ \t]*$/im;
+    const m = re.exec(text);
+    if (!m)
+        return { body: text, removed: "" };
+    return { body: text.slice(0, m.index), removed: text.slice(m.index) };
+}
+/** Removes quoted passages: block quotes starting with ">" and text inside double quotes. */
+export function stripQuotes(text) {
+    const removed = [];
+    let body = text.replace(/^[ \t]*>.*$/gm, (m) => {
+        removed.push(m);
+        return "";
+    });
+    body = body.replace(/["“]([^"“”\n]{2,}?)["”]/g, (m) => {
+        removed.push(m);
+        return " ";
+    });
+    return { body, removed: removed.join("\n") };
+}

package/build/src/tools.js

@@ -0,0 +1,250 @@
+import { z } from "zod";
+import { counts, findFiller, findPassive, findRepeatedOpeners, pageEstimate, round, splitParagraphs, splitSentences, stripQuotes, stripReferences, wordCount, } from "./text.js";
+const textInput = z.string().min(1, "text is empty. Paste the essay text to analyse.");
+function requireText(text) {
+    if (!/[A-Za-z0-9]/.test(text)) {
+        throw new Error("The text has no words in it. Paste the essay text and try again.");
+    }
+}
+const countText = {
+    name: "count_text",
+    title: "Count words, sentences and pages",
+    description: "Count the words, characters, sentences and paragraphs in a text, and estimate how many pages it fills at a given font, font size and line spacing. Inputs: text, and optional font (times new roman, arial, calibri, georgia, courier new or verdana, default times new roman), font_size in points (default 12) and spacing (single, 1.5 or double, default double). The page count is an estimate from typical words per page, so a word processor may differ by a little. Also returns an estimated reading time at 238 words per minute.",
+    inputSchema: {
+        text: textInput,
+        font: z.string().optional().describe("Font name. Default times new roman."),
+        font_size: z.number().min(6).max(72).optional().describe("Font size in points. Default 12."),
+        spacing: z.enum(["single", "1.5", "double"]).optional().describe("Line spacing. Default double."),
+    },
+    outputSchema: {
+        words: z.number(),
+        characters: z.number(),
+        characters_no_spaces: z.number(),
+        sentences: z.number(),
+        paragraphs: z.number(),
+        estimated_pages: z.number(),
+        font: z.string(),
+        font_size: z.number(),
+        spacing: z.string(),
+        reading_minutes: z.number(),
+    },
+    run: ({ text, font = "times new roman", font_size = 12, spacing = "double" }) => {
+        requireText(text);
+        const w = wordCount(text);
+        const pages = round(pageEstimate(w, font, font_size, spacing), 1);
+        const minutes = round(w / 238, 1);
+        const result = {
+            words: w,
+            characters: text.length,
+            characters_no_spaces: text.replace(/\s/g, "").length,
+            sentences: splitSentences(text).length,
+            paragraphs: splitParagraphs(text).length,
+            estimated_pages: pages,
+            font: font.trim().toLowerCase(),
+            font_size,
+            spacing,
+            reading_minutes: minutes,
+        };
+        return {
+            text: `${w} words, ${result.characters} characters (${result.characters_no_spaces} without spaces), ${result.sentences} sentences and ${result.paragraphs} paragraphs. About ${pages} pages in ${result.font} ${font_size} point with ${spacing} spacing. Reading time is about ${minutes} minutes.`,
+            structured: result,
+        };
+    },
+};
+function fleschLabel(score) {
+    if (score >= 90)
+        return "very easy";
+    if (score >= 80)
+        return "easy";
+    if (score >= 70)
+        return "fairly easy";
+    if (score >= 60)
+        return "plain English";
+    if (score >= 50)
+        return "fairly hard";
+    if (score >= 30)
+        return "hard";
+    return "very hard";
+}
+const readabilityScores = {
+    name: "readability_scores",
+    title: "Readability scores",
+    description: "Score how hard a text is to read with three standard formulas: Flesch Kincaid grade level (plus the Flesch reading ease score), Gunning Fog index and SMOG index. Each grade is roughly a US school grade, so 12 is the end of high school and 16 is a college degree. Input: text. SMOG is built for samples of 30 sentences or more, so on shorter text the tool still returns a number but marks it as less reliable.",
+    inputSchema: { text: textInput },
+    outputSchema: {
+        words: z.number(),
+        sentences: z.number(),
+        syllables: z.number(),
+        complex_words: z.number(),
+        flesch_kincaid_grade: z.number(),
+        flesch_reading_ease: z.number(),
+        reading_ease_label: z.string(),
+        gunning_fog: z.number(),
+        smog: z.number(),
+        smog_reliable: z.boolean(),
+    },
+    run: ({ text }) => {
+        requireText(text);
+        const c = counts(text);
+        if (c.words === 0 || c.sentences === 0) {
+            throw new Error("The text needs at least one word and one sentence to score.");
+        }
+        const wps = c.words / c.sentences;
+        const spw = c.syllables / c.words;
+        const fk = 0.39 * wps + 11.8 * spw - 15.59;
+        const ease = 206.835 - 1.015 * wps - 84.6 * spw;
+        const fog = 0.4 * (wps + 100 * (c.complexWords / c.words));
+        const smog = 1.043 * Math.sqrt(c.polysyllables * (30 / c.sentences)) + 3.1291;
+        const reliable = c.sentences >= 30;
+        const result = {
+            words: c.words,
+            sentences: c.sentences,
+            syllables: c.syllables,
+            complex_words: c.complexWords,
+            flesch_kincaid_grade: round(fk),
+            flesch_reading_ease: round(ease),
+            reading_ease_label: fleschLabel(ease),
+            gunning_fog: round(fog),
+            smog: round(smog),
+            smog_reliable: reliable,
+        };
+        return {
+            text: `Flesch Kincaid grade ${result.flesch_kincaid_grade} (reading ease ${result.flesch_reading_ease}, ${result.reading_ease_label}). Gunning Fog ${result.gunning_fog}. SMOG ${result.smog}${reliable ? "" : ", less reliable because the text has fewer than 30 sentences"}. Based on ${c.words} words, ${c.sentences} sentences and ${c.complexWords} complex words.`,
+            structured: result,
+        };
+    },
+};
+const styleFlags = {
+    name: "style_flags",
+    title: "Style flags",
+    description: "Flag common style problems in an essay: sentences in the passive voice, sentences that start with the same word as a neighbour (or three or more times), filler words and phrases such as very, just, in order to, and sentences that are too long. Inputs: text, and optional max_sentence_words (default 30), the length above which a sentence counts as long. The checks are simple pattern rules, so treat them as prompts to reread, not as errors.",
+    inputSchema: {
+        text: textInput,
+        max_sentence_words: z.number().int().min(5).max(200).optional().describe("Sentence length that counts as long. Default 30."),
+    },
+    outputSchema: {
+        sentences: z.number(),
+        passive_count: z.number(),
+        passive_sentences: z.array(z.object({ phrase: z.string(), sentence: z.string() })),
+        repeated_openers: z.array(z.object({ word: z.string(), count: z.number(), sentences: z.array(z.number()) })),
+        filler: z.array(z.object({ text: z.string(), count: z.number() })),
+        filler_count: z.number(),
+        long_sentences: z.array(z.object({ number: z.number(), words: z.number(), sentence: z.string() })),
+        max_sentence_words: z.number(),
+    },
+    run: ({ text, max_sentence_words = 30 }) => {
+        requireText(text);
+        const sentences = splitSentences(text);
+        const passive = findPassive(sentences);
+        const openers = findRepeatedOpeners(sentences);
+        const filler = findFiller(text);
+        const long = sentences
+            .map((s, i) => ({ number: i + 1, words: wordCount(s), sentence: s }))
+            .filter((s) => s.words > max_sentence_words);
+        const fillerCount = filler.reduce((n, f) => n + f.count, 0);
+        const lines = [
+            `${sentences.length} sentences checked.`,
+            `Passive voice: ${passive.length}${passive.length ? " (" + passive.slice(0, 3).map((p) => `"${p.phrase}"`).join(", ") + (passive.length > 3 ? ", ..." : "") + ")" : ""}.`,
+            `Repeated openers: ${openers.length ? openers.map((o) => `"${o.word}" x${o.count}`).join(", ") : "none"}.`,
+            `Filler: ${fillerCount ? filler.map((f) => `"${f.text}" x${f.count}`).join(", ") : "none"}.`,
+            `Long sentences over ${max_sentence_words} words: ${long.length ? long.map((l) => `#${l.number} (${l.words} words)`).join(", ") : "none"}.`,
+        ];
+        return {
+            text: lines.join("\n"),
+            structured: {
+                sentences: sentences.length,
+                passive_count: passive.length,
+                passive_sentences: passive.map((p) => ({ phrase: p.phrase, sentence: p.sentence })),
+                repeated_openers: openers,
+                filler,
+                filler_count: fillerCount,
+                long_sentences: long,
+                max_sentence_words,
+            },
+        };
+    },
+};
+const checkWordLimit = {
+    name: "check_word_limit",
+    title: "Check a word limit",
+    description: "Compare an essay against a word limit. Inputs: text, limit (the maximum word count), optional minimum (a lower bound), optional tolerance_percent (how far over the limit is still acceptable, default 0, a common rule is 10), optional exclude_references (cut everything from a heading line such as References, Works Cited or Bibliography to the end) and optional exclude_quotes (leave out block quotes that start with > and text inside double quotes). Returns the counted words, how many are left or over, and what was excluded.",
+    inputSchema: {
+        text: textInput,
+        limit: z.number().int().positive().describe("Maximum number of words."),
+        minimum: z.number().int().min(0).optional().describe("Minimum number of words."),
+        tolerance_percent: z.number().min(0).max(100).optional().describe("Percent over the limit that is still fine. Default 0."),
+        exclude_references: z.boolean().optional().describe("Leave out the references section. Default false."),
+        exclude_quotes: z.boolean().optional().describe("Leave out quoted passages. Default false."),
+    },
+    outputSchema: {
+        status: z.enum(["under_minimum", "within_limit", "within_tolerance", "over_limit"]),
+        total_words: z.number(),
+        counted_words: z.number(),
+        excluded_reference_words: z.number(),
+        excluded_quote_words: z.number(),
+        limit: z.number(),
+        minimum: z.number().nullable(),
+        allowed_maximum: z.number(),
+        words_remaining: z.number(),
+        words_over: z.number(),
+    },
+    run: ({ text, limit, minimum, tolerance_percent = 0, exclude_references = false, exclude_quotes = false }) => {
+        requireText(text);
+        if (minimum !== undefined && minimum > limit) {
+            throw new Error(`minimum (${minimum}) is above limit (${limit}). Check the two numbers.`);
+        }
+        const total = wordCount(text);
+        let body = text;
+        let refWords = 0;
+        let quoteWords = 0;
+        if (exclude_references) {
+            const r = stripReferences(body);
+            body = r.body;
+            refWords = wordCount(r.removed);
+        }
+        if (exclude_quotes) {
+            const q = stripQuotes(body);
+            body = q.body;
+            quoteWords = wordCount(q.removed);
+        }
+        const counted = wordCount(body);
+        const allowed = Math.floor(limit * (1 + tolerance_percent / 100));
+        let status;
+        if (minimum !== undefined && counted < minimum)
+            status = "under_minimum";
+        else if (counted <= limit)
+            status = "within_limit";
+        else if (counted <= allowed)
+            status = "within_tolerance";
+        else
+            status = "over_limit";
+        const remaining = Math.max(0, limit - counted);
+        const over = Math.max(0, counted - limit);
+        const summary = {
+            under_minimum: `Under the minimum. ${counted} words counted, ${minimum - counted} short of ${minimum}.`,
+            within_limit: `Within the limit. ${counted} of ${limit} words, ${remaining} left.`,
+            within_tolerance: `Over the limit of ${limit} by ${over} words, but inside the ${tolerance_percent} percent tolerance (up to ${allowed}).`,
+            over_limit: `Over the limit. ${counted} words counted against ${limit}, so ${over} to cut${tolerance_percent ? ` (tolerance allows up to ${allowed})` : ""}.`,
+        };
+        const excluded = [
+            exclude_references ? `${refWords} reference words left out` : "",
+            exclude_quotes ? `${quoteWords} quote words left out` : "",
+        ].filter(Boolean);
+        return {
+            text: summary[status] + (excluded.length ? ` (${total} words in total, ${excluded.join(", ")}.)` : ""),
+            structured: {
+                status,
+                total_words: total,
+                counted_words: counted,
+                excluded_reference_words: refWords,
+                excluded_quote_words: quoteWords,
+                limit,
+                minimum: minimum ?? null,
+                allowed_maximum: allowed,
+                words_remaining: remaining,
+                words_over: over,
+            },
+        };
+    },
+};
+export const tools = [countText, readabilityScores, styleFlags, checkWordLimit];

package/llms.txt

@@ -0,0 +1,47 @@
+# Essay Stats MCP
+
+> An MCP server with offline writing metrics for essays. It counts words and pages, scores readability, flags style problems and checks word limits. No account, no API key, no network.
+
+Package: essay-stats-mcp (npm). Registry name: io.github.AnonymousOnyx22/essay-stats-mcp. Runs over stdio. Needs Node.js 20 or newer.
+
+## Install
+
+Add this to the MCP config of Claude Desktop, Claude Code, Cursor, VS Code or Windsurf:
+
+```json
+{
+  "mcpServers": {
+    "essay-stats": {
+      "command": "npx",
+      "args": ["-y", "essay-stats-mcp"]
+    }
+  }
+}
+```
+
+VS Code uses a `servers` key instead of `mcpServers`.
+
+## Tools
+
+All tools are read only and work on text passed in the call.
+
+- count_text: words, characters, sentences, paragraphs, reading time and estimated pages. Inputs: text, optional font (times new roman, arial, calibri, georgia, courier new, verdana), font_size (default 12) and spacing (single, 1.5, double; default double).
+- readability_scores: Flesch Kincaid grade, Flesch reading ease, Gunning Fog and SMOG. Input: text. SMOG is marked less reliable under 30 sentences.
+- style_flags: passive voice, repeated sentence openers, filler words and long sentences. Inputs: text, optional max_sentence_words (default 30).
+- check_word_limit: compares text with a limit. Inputs: text, limit, optional minimum, tolerance_percent, exclude_references and exclude_quotes. Returns a status of under_minimum, within_limit, within_tolerance or over_limit.
+
+## Example prompts
+
+- "Count the words in this essay and estimate the pages in Times New Roman 12 double spaced."
+- "Give me the Flesch Kincaid, Gunning Fog and SMOG scores for this paper."
+- "Flag passive voice and filler words in my draft."
+- "Is this under 2000 words if I leave out the works cited and quotes?"
+
+## Privacy
+
+Everything runs locally. The server makes no network requests and stores nothing. No keys or passwords are needed.
+
+## Links
+
+- Source: https://github.com/AnonymousOnyx22/essay-stats-mcp
+- License: MIT

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "essay-stats-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Offline writing metrics for essays. Word and page counts, readability scores, passive voice, repeated openers, filler words, long sentences and word limit checks, so students can check their work against assignment requirements. No account, no network.",
+  "type": "module",
+  "main": "build/src/index.js",
+  "bin": {
+    "essay-stats-mcp": "build/src/index.js"
+  },
+  "files": [
+    "build/src",
+    "README.md",
+    "llms.txt",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').chmodSync('build/src/index.js', 0o755)\"",
+    "test": "vitest run",
+    "start": "node build/src/index.js",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "essay stats mcp",
+    "essay word counter",
+    "word count",
+    "page count",
+    "readability",
+    "flesch kincaid",
+    "gunning fog",
+    "smog index",
+    "passive voice",
+    "writing metrics",
+    "word limit",
+    "reading time",
+    "style checker",
+    "student writing",
+    "mcp",
+    "mcp server",
+    "model context protocol",
+    "claude desktop",
+    "cursor"
+  ],
+  "author": "AnonymousOnyx22",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AnonymousOnyx22/essay-stats-mcp.git"
+  },
+  "homepage": "https://github.com/AnonymousOnyx22/essay-stats-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/AnonymousOnyx22/essay-stats-mcp/issues"
+  },
+  "mcpName": "io.github.AnonymousOnyx22/essay-stats-mcp",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.5"
+  }
+}