essay-stats-mcp 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.1
+
+- Tool descriptions now include example prompts, so clients can show what to ask each tool.
+- New tool word_frequency lists the most used words, with counts and share of the text, to spot overused terms.
+- style_flags now returns a sentence_list with the number of each passive or long sentence, and says that sentence numbers follow the order of the text.
+- Error messages for empty or wordless text and for a minimum above the limit now include a worked example call so a client can fix its input.
+
+## 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,113 @@
-# 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.
+You are about to hand in an essay and you are not sure if it is over the word limit, or how many pages it is. A chat assistant tends to guess at word counts. This server counts them properly, on your computer, so your assistant can give you real numbers.
+
+Install it in Claude Code with one line:
+
+```
+claude mcp add essay-stats -- npx -y essay-stats-mcp
+```
+
+Then ask things like:
+
+- "My limit is 1500 words, not counting the works cited or quotes. Am I over?"
+- "How many pages is this essay in Arial 11 point with 1.5 spacing?"
+- "Find the passive voice and filler words in my draft."
+
+Essay Stats MCP is an essay word counter and writing checker that runs offline. It counts words and pages, gives a readability score, and flags passive voice, filler words, long sentences and repeated sentence openers. It also gives the reading time.
+
+There is no account, no API key and no network call. Your essay text never leaves your machine.
+
+## Quick start
+
+For Claude Code, use the one line above. For other apps, add this to the MCP config:
+
+```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`).
+- 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. |
+| `word_frequency` | The words used most often, with counts and share of the text, to spot overused terms. |
+
+All five 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.
+
+Sentence numbers start at 1 and follow the order of the text. The `sentence_list` field gives each passive or long sentence with its number, and the text summary ends with a line listing those numbers, so a reply can point you to the right sentence.
+
+### word_frequency
+
+Inputs: `text`, and optional `top` (how many words to list, default 10), `min_count` (fewest uses for a word to be listed, default 2) and `include_common_words` (also count small words such as the, and, of and to, default false). Case is ignored, and words under 3 letters are skipped unless `include_common_words` is true.
+
+### 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?"
+- "Which words do I overuse in this essay?"
+
+## Works well with
+
+If your school uses Brightspace, you can run [brightspace-d2l-mcp](https://www.npmjs.com/package/brightspace-d2l-mcp) next to Essay Stats MCP in the same app. That server has its own setup, so follow its README to install and sign in. Essay Stats MCP does not talk to it and does not need it.
+
+With both added to your MCP config, you can ask your assistant to look up the word limit in your assignment details, then pass that number to `check_word_limit` along with your draft. For example:
+
+- "Find the word limit for my history essay in Brightspace, then check this draft against it, leaving out the works cited."
+- "Look up my assignment instructions, then tell me if this draft is under the limit and how many pages it is."
+
+The assignment details come from the other server. The counting and checking happen here, on your machine, and Essay Stats MCP makes no network calls.
+
+## 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.1";
+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,209 @@
+/** 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") };
+}
+const COMMON_WORDS = new Set("a about after all also an and any are as at be because been but by can could did do does for from had has have he her his how i if in into is it its may more most my no not of on one or our out she so some than that the their them then there these they this to up was we were what when which who will with would you your".split(" "));
+/** Counts how often each word is used, ignoring case. Common small words are skipped unless asked for. */
+export function wordFrequency(text, includeCommon = false) {
+    const all = words(text).map((w) => w.toLowerCase().replace(/['’]s$/, ""));
+    const counted = new Map();
+    for (const w of all) {
+        if (!includeCommon && (COMMON_WORDS.has(w) || w.length < 3))
+            continue;
+        counted.set(w, (counted.get(w) ?? 0) + 1);
+    }
+    const hits = [...counted.entries()]
+        .map(([word, count]) => ({ word, count, percent: round((count / all.length) * 100, 2) }))
+        .sort((a, b) => b.count - a.count || a.word.localeCompare(b.word));
+    return { total: all.length, unique: new Set(all).size, hits };
+}

package/build/src/tools.js

@@ -0,0 +1,297 @@
+import { z } from "zod";
+import { counts, findFiller, findPassive, findRepeatedOpeners, pageEstimate, round, splitParagraphs, splitSentences, stripQuotes, stripReferences, wordCount, wordFrequency, } from "./text.js";
+const EMPTY_TEXT_HINT = `text is empty. Paste the essay text to analyse. Worked example: { "text": "Your essay content here." }`;
+const textInput = z.string().min(1, EMPTY_TEXT_HINT);
+function requireText(text, toolName) {
+    if (!/[A-Za-z0-9]/.test(text)) {
+        const example = toolName === "check_word_limit"
+            ? `{ "text": "Your essay content here.", "limit": 1500, "exclude_references": true }`
+            : `{ "text": "Your essay content here." }`;
+        throw new Error(`The text has no words in it. Paste the essay text and try again. Worked example for ${toolName}: ${example}`);
+    }
+}
+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. Example: \"Count the words in this essay and estimate the pages in Times New Roman 12 double spaced.",
+    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, "count_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. Example: \"Give me the Flesch Kincaid, Gunning Fog and SMOG scores for this paper.",
+    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, "readability_scores");
+        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. Sentence numbers start at 1 and follow the order of the text, so number 3 is the third sentence. The sentence_list field gives each passive or long sentence with its number, and the text summary ends with a line listing those numbers.     The checks are simple pattern rules, so treat them as prompts to reread, not as errors. Example: \"Flag passive voice and filler words in my draft.",
+    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(),
+        sentence_list: z.array(z.object({ number: z.number(), passive: z.boolean(), long: z.boolean(), sentence: z.string() })),
+    },
+    run: ({ text, max_sentence_words = 30 }) => {
+        requireText(text, "style_flags");
+        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);
+        let next = 0;
+        const longNumbers = new Set(long.map((l) => l.number));
+        const sentenceList = sentences
+            .map((s, i) => {
+            const isPassive = next < passive.length && passive[next].sentence === s;
+            if (isPassive)
+                next++;
+            return { number: i + 1, passive: isPassive, long: longNumbers.has(i + 1), sentence: s };
+        })
+            .filter((s) => s.passive || s.long);
+        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"}.`,
+            `Passive or long sentence numbers, in text order: ${sentenceList.length ? sentenceList.map((s) => s.number).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,
+                sentence_list: sentenceList,
+            },
+        };
+    },
+};
+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. Example: \"Is this under 2000 words if I leave out the works cited and quotes?.",
+    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, "check_word_limit");
+        if (minimum !== undefined && minimum > limit) {
+            throw new Error(`minimum (${minimum}) is above limit (${limit}). Set minimum to at most the limit. Worked example: { "text": "Your essay content here.", "limit": 1500, "minimum": 1200 }`);
+        }
+        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,
+            },
+        };
+    },
+};
+const wordFrequencyTool = {
+    name: "word_frequency",
+    title: "Word frequency",
+    description: "Find the words an essay uses most, to spot overused or repeated terms. Inputs: text, and optional top (how many words to list, default 10), min_count (fewest uses for a word to be listed, default 2) and include_common_words (also count small words such as the, and, of and to, default false).     Case is ignored, and words under 3 letters are skipped unless include_common_words is true. Each word comes with its count and its share of all the words in the text. Example: \"Which words do I overuse in this essay?.",
+    inputSchema: {
+        text: textInput,
+        top: z.number().int().min(1).max(100).optional().describe("How many words to list. Default 10."),
+        min_count: z.number().int().min(1).optional().describe("Fewest uses for a word to be listed. Default 2."),
+        include_common_words: z.boolean().optional().describe("Also count small common words. Default false."),
+    },
+    outputSchema: {
+        total_words: z.number(),
+        unique_words: z.number(),
+        words: z.array(z.object({ word: z.string(), count: z.number(), percent: z.number() })),
+        top: z.number(),
+        min_count: z.number(),
+    },
+    run: ({ text, top = 10, min_count = 2, include_common_words = false }) => {
+        requireText(text, "word_frequency");
+        const f = wordFrequency(text, include_common_words);
+        const list = f.hits.filter((h) => h.count >= min_count).slice(0, top);
+        const summary = list.length
+            ? `Most used words: ${list.map((h) => `"${h.word}" x${h.count} (${h.percent} percent)`).join(", ")}.`
+            : `No word is used ${min_count} or more times.`;
+        return {
+            text: `${f.total} words, ${f.unique} different. ${summary}`,
+            structured: { total_words: f.total, unique_words: f.unique, words: list, top, min_count },
+        };
+    },
+};
+export const tools = [countText, readabilityScores, styleFlags, checkWordLimit, wordFrequencyTool];

package/llms.txt

@@ -0,0 +1,49 @@
+# 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).
+- word_frequency: the most used words with counts and share of the text, to spot overused terms. Inputs: text, optional top (default 10), min_count (default 2) and include_common_words (default false).
+- 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."
+- "Which words do I overuse in this essay?"
+- "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,71 @@
 {
   "name": "essay-stats-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Essay Stats MCP counts words and pages offline for essays, scores readability, flags passive voice and filler words, and checks word limits 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 stats",
+    "essay word counter",
+    "word counter",
+    "word count",
+    "page count",
+    "readability",
+    "readability score",
+    "flesch kincaid",
+    "gunning fog",
+    "smog index",
+    "passive voice",
+    "writing metrics",
+    "word limit",
+    "word frequency",
+    "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"
+  }
+}