essay-stats-mcp 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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.

package/README.md

@@ -1,12 +1,26 @@
 # Essay Stats MCP
 
-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.
+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.
 
-It runs on your computer. There is no account, no API key and no network call. Your essay text never leaves your machine.
+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
 
-Add this to the MCP config of your app:
+For Claude Code, use the one line above. For other apps, add this to the MCP config:
 
 ```json
 {
@@ -24,7 +38,6 @@ 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`.
@@ -37,8 +50,9 @@ Where the config lives:
 | `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 four tools only read the text you give them. Each one returns a short written answer and the same numbers as structured fields.
+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
 
@@ -52,6 +66,12 @@ Input: `text`. The grades are roughly US school grades, so 12 is the end of high
 
 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.
@@ -63,6 +83,18 @@ Inputs: `text`, `limit`, and optional `minimum`, `tolerance_percent`, `exclude_r
 - "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
 

package/build/src/server.js

@@ -1,7 +1,7 @@
 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 const VERSION = "0.1.1";
 export function createServer() {
     const server = new McpServer({ name: "essay-stats-mcp", version: VERSION });
     registerTools(server, tools);

package/build/src/text.js

@@ -192,3 +192,18 @@ export function stripQuotes(text) {
     });
     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

@@ -1,15 +1,19 @@
 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) {
+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)) {
-        throw new Error("The text has no words in it. Paste the essay text and try again.");
+        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.",
+    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."),
@@ -29,7 +33,7 @@ const countText = {
         reading_minutes: z.number(),
     },
     run: ({ text, font = "times new roman", font_size = 12, spacing = "double" }) => {
-        requireText(text);
+        requireText(text, "count_text");
         const w = wordCount(text);
         const pages = round(pageEstimate(w, font, font_size, spacing), 1);
         const minutes = round(w / 238, 1);
@@ -69,7 +73,7 @@ function fleschLabel(score) {
 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.",
+    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(),
@@ -84,7 +88,7 @@ const readabilityScores = {
         smog_reliable: z.boolean(),
     },
     run: ({ text }) => {
-        requireText(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.");
@@ -117,7 +121,7 @@ const readabilityScores = {
 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.",
+    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."),
@@ -131,9 +135,10 @@ const styleFlags = {
         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);
+        requireText(text, "style_flags");
         const sentences = splitSentences(text);
         const passive = findPassive(sentences);
         const openers = findRepeatedOpeners(sentences);
@@ -142,12 +147,23 @@ const styleFlags = {
             .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"),
@@ -160,6 +176,7 @@ const styleFlags = {
                 filler_count: fillerCount,
                 long_sentences: long,
                 max_sentence_words,
+                sentence_list: sentenceList,
             },
         };
     },
@@ -167,7 +184,7 @@ const styleFlags = {
 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.",
+    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."),
@@ -189,9 +206,9 @@ const checkWordLimit = {
         words_over: z.number(),
     },
     run: ({ text, limit, minimum, tolerance_percent = 0, exclude_references = false, exclude_quotes = false }) => {
-        requireText(text);
+        requireText(text, "check_word_limit");
         if (minimum !== undefined && minimum > limit) {
-            throw new Error(`minimum (${minimum}) is above limit (${limit}). Check the two numbers.`);
+            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;
@@ -247,4 +264,34 @@ const checkWordLimit = {
         };
     },
 };
-export const tools = [countText, readabilityScores, styleFlags, checkWordLimit];
+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

@@ -28,6 +28,7 @@ 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
@@ -35,6 +36,7 @@ All tools are read only and work on text passed in the call.
 - "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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "essay-stats-mcp",
-  "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.",
+  "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": {
@@ -25,16 +25,20 @@
   },
   "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",