essay-stats-mcp 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.3
+
+- New tool sentence_variety shows how much sentence lengths change in an essay, with short, medium and long counts and runs of sentences that are about the same length.
+- All five tools are now marked read only, idempotent and closed world, so clients can run them without asking you first.
+
 ## 0.1.2
 
 - Add worked examples to word_frequency and style_flags errors

package/README.md

@@ -1,4 +1,4 @@
-# Essay Stats MCP
+# Essay Stats MCP: Essay Word Count and Writing Checker
 
 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.
 
@@ -20,7 +20,11 @@ There is no account, no API key and no network call. Your essay text never leave
 
 ## Quick start
 
-For Claude Code, use the one line above. For other apps, add this to the MCP config:
+Claude Code users can use the one line above. For other apps, copy the snippet for your client. It needs Node.js 20 or newer.
+
+### Claude Desktop
+
+Open Settings, Developer, Edit Config, and add this to `claude_desktop_config.json`. Then restart Claude Desktop.
 
 ```json
 {
@@ -33,14 +37,40 @@ For Claude Code, use the one line above. For other apps, add this to the MCP con
 }
 ```
 
-It needs Node.js 20 or newer.
+### Cursor
+
+Add this to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for all projects.
+
+```json
+{
+  "mcpServers": {
+    "essay-stats": {
+      "command": "npx",
+      "args": ["-y", "essay-stats-mcp"]
+    }
+  }
+}
+```
 
-Where the config lives:
+### VS Code
 
-- 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`.
+Add this to `.vscode/mcp.json` in your workspace. VS Code uses a `servers` key instead of `mcpServers`.
+
+```json
+{
+  "servers": {
+    "essay-stats": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "essay-stats-mcp"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+Use the same snippet as Claude Desktop in `~/.codeium/windsurf/mcp_config.json`.
 
 ## Tools
 
@@ -49,10 +79,11 @@ Where the config lives:
 | `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. |
+| `sentence_variety` | How much sentence lengths change, with short, medium and long counts and runs of similar length. |
 | `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.
+All six tools only read the text you give them. Each one returns a short written answer and the same numbers as structured fields.
 
 ### count_text
 
@@ -68,6 +99,10 @@ Inputs: `text` and optional `max_sentence_words` (default 30). The checks are si
 
 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.
 
+### sentence_variety
+
+Input: `text`. Returns the shortest, longest and average sentence length in words, the standard deviation, and how many sentences are short (under 10 words), medium (10 to 24) or long (25 or more). It also lists runs of 3 or more sentences in a row whose lengths are within 3 words of the first one in the run, with their sentence numbers. Sentence numbers start at 1 and follow the order of the text.
+
 ### 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.
@@ -76,6 +111,28 @@ Inputs: `text`, and optional `top` (how many words to list, default 10), `min_co
 
 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.
 
+## FAQ: how words and pages are counted
+
+### How does it count a word?
+
+It splits the text on spaces and line breaks and counts each piece that has at least one letter or digit in it. That is the same idea Word and Google Docs use. A hyphenated word such as well known counts as one word when written with a hyphen, and a number like 2024 counts as one word.
+
+### Why can my count differ from Word?
+
+Mostly because of what gets pasted. A dash or symbol standing alone between spaces is counted by Word but not here, since it has no letter or digit. Footnotes, headers, footers and text boxes only count if you paste them in. If the two numbers differ by a few words, check those first.
+
+### How is the page number worked out?
+
+`count_text` divides the word count by a fixed words per page figure for the font you pick, then adjusts for font size and line spacing. It is an estimate, not a layout. It does not know your margins, headings, title page, tables or images, so Word can show a different page count. For a hard page rule, trust the page count in your own document.
+
+### What does check_word_limit leave out?
+
+Nothing unless you ask. With `exclude_references` it drops everything from a heading line such as References, Works Cited or Bibliography to the end. With `exclude_quotes` it drops lines starting with `>` and text inside double quotes. The answer shows the total, the counted words and how many words were left out, so you can match it to what your instructor counts.
+
+### Does the tolerance change the word count?
+
+No. The count stays the same. `tolerance_percent` only widens the allowed limit, so a limit of 1500 with 10 percent tolerance allows up to 1650 words. The answer says when you are over the limit but inside the tolerance.
+
 ## Example prompts
 
 - "Count the words in this essay and tell me how many pages it is in Arial 11 point with 1.5 spacing."
@@ -83,6 +140,7 @@ 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?"
+- "Do my sentences all sound the same length?"
 - "Which words do I overuse in this essay?"
 
 ## How it compares

package/build/src/core/tools.js

@@ -15,7 +15,7 @@ export function registerTools(server, tools) {
             description: tool.description,
             inputSchema: tool.inputSchema,
             outputSchema: tool.outputSchema,
-            annotations: { readOnlyHint: true, openWorldHint: false },
+            annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
         }, async (args) => runTool(tool, args));
     }
 }

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

package/build/src/text.js

@@ -207,3 +207,69 @@ export function wordFrequency(text, includeCommon = false) {
         .sort((a, b) => b.count - a.count || a.word.localeCompare(b.word));
     return { total: all.length, unique: new Set(all).size, hits };
 }
+export function sentenceLengths(sentences) {
+    return sentences.map((s) => wordCount(s));
+}
+/** Mean, median, longest, shortest and spread (longest minus shortest) of sentence length in words. */
+export function sentenceLengthStats(sentences) {
+    const lengths = sentenceLengths(sentences);
+    if (lengths.length === 0) {
+        return { count: 0, mean: 0, median: 0, longest: 0, shortest: 0, spread: 0 };
+    }
+    const sorted = [...lengths].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    const median = sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+    const longest = sorted[sorted.length - 1];
+    const shortest = sorted[0];
+    return {
+        count: sorted.length,
+        mean: round(sorted.reduce((a, b) => a + b, 0) / sorted.length, 1),
+        median,
+        longest,
+        shortest,
+        spread: longest - shortest,
+    };
+}
+const TRANSITION_PHRASES = [
+    "for example", "for instance", "in addition", "in contrast", "in conclusion", "in summary",
+    "on the other hand", "as a result", "in other words", "on the contrary", "as well as",
+    "in fact", "above all", "after all", "even though", "at the same time", "for this reason",
+    "to begin with", "in particular", "of course",
+    "however", "therefore", "moreover", "furthermore", "consequently", "nevertheless", "nonetheless",
+    "meanwhile", "similarly", "likewise", "finally", "additionally", "thus", "hence", "otherwise",
+    "instead", "although", "whereas", "because", "since", "first", "second", "third", "next", "then",
+    "also", "still", "yet",
+].sort((a, b) => b.length - a.length);
+/** Counts transition words and phrases in each sentence and lists the sentence numbers that have none. */
+export function transitionWords(sentences) {
+    const hits = [];
+    const without = [];
+    let total = 0;
+    sentences.forEach((s, i) => {
+        let rest = s.toLowerCase();
+        const found = [];
+        for (const p of TRANSITION_PHRASES) {
+            const re = new RegExp(`\\b${p.replace(/ /g, "\\s+")}\\b`, "g");
+            const n = (rest.match(re) ?? []).length;
+            for (let k = 0; k < n; k++)
+                found.push(p);
+            if (n > 0)
+                rest = rest.replace(re, " ");
+        }
+        if (found.length > 0) {
+            hits.push({ sentence: i + 1, found });
+            total += found.length;
+        }
+        else {
+            without.push(i + 1);
+        }
+    });
+    return {
+        sentences: sentences.length,
+        withTransitions: hits.length,
+        total,
+        perSentence: sentences.length ? round(total / sentences.length, 2) : 0,
+        hits,
+        withoutTransitions: without,
+    };
+}

package/build/src/tools.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { counts, findFiller, findPassive, findRepeatedOpeners, pageEstimate, round, splitParagraphs, splitSentences, stripQuotes, stripReferences, wordCount, wordFrequency, } from "./text.js";
+import { counts, findFiller, findPassive, findRepeatedOpeners, pageEstimate, round, sentenceLengths, 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) {
@@ -8,6 +8,7 @@ function requireText(text, toolName) {
             check_word_limit: `{ "text": "Your essay content here.", "limit": 1500, "exclude_references": true }`,
             word_frequency: `{ "text": "Your essay content here.", "top": 10, "min_count": 2 }`,
             style_flags: `{ "text": "Your essay content here.", "max_sentence_words": 30 }`,
+            sentence_variety: `{ "text": "Your essay content here." }`,
         };
         const example = examples[toolName] ?? `{ "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}`);
@@ -16,7 +17,7 @@ function requireText(text, toolName) {
 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.",
+    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."),
@@ -76,7 +77,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. Example: \"Give me the Flesch Kincaid, Gunning Fog and SMOG scores for this paper.",
+    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(),
@@ -124,7 +125,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. 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.",
+    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."),
@@ -187,7 +188,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. Example: \"Is this under 2000 words if I leave out the works cited and quotes?.",
+    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."),
@@ -270,7 +271,7 @@ const 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?.",
+    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."),
@@ -297,4 +298,67 @@ const wordFrequencyTool = {
         };
     },
 };
-export const tools = [countText, readabilityScores, styleFlags, checkWordLimit, wordFrequencyTool];
+const sentenceVariety = {
+    name: "sentence_variety",
+    title: "Sentence variety",
+    description: "Show how much the sentence lengths in an essay change, since a good rhythm mixes short, medium and long sentences. Input: text. Returns the shortest, longest and average sentence length in words, the standard deviation, how many sentences are short (under 10 words), medium (10 to 24) and long (25 or more), and any runs of 3 or more sentences in a row whose lengths are within 3 words of the first one in the run, with their sentence numbers. Sentence numbers start at 1 and follow the order of the text. This is a simple measure of rhythm, so treat it as a prompt to reread. Example: \"Do my sentences all sound the same length?\"",
+    inputSchema: { text: textInput },
+    outputSchema: {
+        sentences: z.number(),
+        shortest_words: z.number(),
+        longest_words: z.number(),
+        average_words: z.number(),
+        std_dev_words: z.number(),
+        short_count: z.number(),
+        medium_count: z.number(),
+        long_count: z.number(),
+        similar_runs: z.array(z.object({ first: z.number(), last: z.number(), words: z.number() })),
+        lengths: z.array(z.number()),
+    },
+    run: ({ text }) => {
+        requireText(text, "sentence_variety");
+        const lengths = sentenceLengths(splitSentences(text));
+        if (lengths.length === 0) {
+            throw new Error("The text needs at least one sentence to measure.");
+        }
+        const n = lengths.length;
+        const avg = lengths.reduce((a, b) => a + b, 0) / n;
+        const sd = Math.sqrt(lengths.reduce((a, b) => a + (b - avg) ** 2, 0) / n);
+        const shortCount = lengths.filter((l) => l < 10).length;
+        const longCount = lengths.filter((l) => l >= 25).length;
+        const runs = [];
+        let i = 0;
+        while (i < n) {
+            let j = i;
+            while (j + 1 < n && Math.abs(lengths[j + 1] - lengths[i]) <= 3)
+                j++;
+            if (j - i + 1 >= 3) {
+                runs.push({ first: i + 1, last: j + 1, words: lengths[i] });
+                i = j + 1;
+            }
+            else {
+                i++;
+            }
+        }
+        const result = {
+            sentences: n,
+            shortest_words: Math.min(...lengths),
+            longest_words: Math.max(...lengths),
+            average_words: round(avg, 1),
+            std_dev_words: round(sd, 1),
+            short_count: shortCount,
+            medium_count: n - shortCount - longCount,
+            long_count: longCount,
+            similar_runs: runs,
+            lengths,
+        };
+        const runText = runs.length
+            ? runs.map((r) => `sentences ${r.first} to ${r.last} (about ${r.words} words each)`).join(", ")
+            : "none";
+        return {
+            text: `${n} sentences, from ${result.shortest_words} to ${result.longest_words} words, averaging ${result.average_words} with a standard deviation of ${result.std_dev_words}. ${shortCount} short, ${result.medium_count} medium and ${longCount} long. Runs of similar length: ${runText}.`,
+            structured: result,
+        };
+    },
+};
+export const tools = [countText, readabilityScores, styleFlags, sentenceVariety, checkWordLimit, wordFrequencyTool];

package/llms.txt

@@ -30,6 +30,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).
+- sentence_variety: how much sentence lengths change: shortest, longest, average, standard deviation, counts of short (under 10 words), medium and long (25 or more) sentences, and runs of 3 or more sentences of similar length. Input: text.
 - 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.
 
@@ -50,6 +51,7 @@ All tools are read only and work on text passed in the call.
 - count_text: "Count the words in this essay and tell me how many pages it is in Arial 11 point with 1.5 spacing." Uses font arial, font_size 11 and spacing 1.5.
 - readability_scores: "Give me the Flesch Kincaid, Gunning Fog and SMOG scores for this paper." Grades are roughly US school grades.
 - style_flags: "Which sentences are over 25 words long?" Uses max_sentence_words 25. Sentence numbers start at 1.
+- sentence_variety: "Do my sentences all sound the same length?" Sentence numbers in similar_runs start at 1.
 - word_frequency: "Show my 15 most used words." Uses top 15.
 - check_word_limit: "My limit is 1500 words, not counting the works cited or quotes." Uses limit 1500 with exclude_references and exclude_quotes set to true.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "essay-stats-mcp",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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",
@@ -26,6 +26,7 @@
   "keywords": [
     "essay stats mcp",
     "essay stats",
+    "essay word count",
     "essay word counter",
     "word counter",
     "word count",