Skip to main content
Glama
wordsmith-mcp

wordsmith-mcp

by mirza1272

Wordsmith MCP

An MCP (Model Context Protocol) server that gives any MCP-compatible AI client a set of offline text analysis and rewriting tools — statistics, extractive summaries, keyword extraction, readability scoring, naming-case conversion, entity extraction and text diffing.

No API keys. No network calls. No state stored anywhere. Everything runs locally on the text you pass in, which makes it fast, free, and safe to point at private documents.

Built with the MCP Python SDK.


Why this exists

Language models are great at judging text but surprisingly unreliable at measuring it — ask one for an exact word count or a Flesch score and it will guess. Wordsmith hands the model a deterministic calculator for those jobs, so answers about a document's length, difficulty and key terms are computed rather than estimated.


Related MCP server: mhlabs-mcp-tools

Tools

Tool

What it does

Key parameters

text_stats

Characters, words, unique words, sentences, paragraphs, lines, average word/sentence length, estimated reading time

text

summarize_text

Extractive summary — scores sentences by meaningful-word frequency and returns the best ones in original order

text, max_sentences (1–20, default 3)

extract_keywords

Most frequent meaningful words with counts and relative frequency; stopwords filtered

text, limit (1–50, default 10), min_length

readability

Flesch Reading Ease + Flesch–Kincaid grade level, with a plain-language interpretation

text

convert_case

Converts to snake, kebab, slug, camel, pascal, constant, title, sentence, upper, lower

text, style

extract_entities

Pulls out emails, URLs, hashtags, mentions, phone numbers and standalone numbers

text

diff_texts

Unified line-by-line diff between a draft and a revision

before, after, context_lines

All tools are annotated readOnlyHint: true, openWorldHint: false — they never mutate anything and never reach out to the internet.


Quick start (local, stdio)

git clone https://github.com/mirza1272/wordsmith-mcp.git
cd wordsmith-mcp
python3 -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -e .

Run it:

wordsmith-mcp

The server speaks MCP over stdio and will sit there waiting for a client — that is correct behaviour, not a hang. Clients start it themselves; see below.

Verify it works

python scripts/smoke_test.py

This spins up the server as a real MCP client would, lists the tools and calls every one of them, printing the results.

Run the unit tests

pip install -e ".[dev]"
pytest -q

Connecting it to a client

Claude Desktop

Edit claude_desktop_config.json:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "wordsmith": {
      "command": "/absolute/path/to/wordsmith-mcp/.venv/bin/wordsmith-mcp"
    }
  }
}

Restart Claude Desktop, then ask something like "How readable is this paragraph, and what are its top 5 keywords?"

Claude Code

claude mcp add wordsmith -- /absolute/path/to/wordsmith-mcp/.venv/bin/wordsmith-mcp

Cursor / Windsurf / other clients

Any client that accepts an mcpServers block uses the same shape as the Claude Desktop example above.

MCP Inspector (visual debugging)

npx @modelcontextprotocol/inspector .venv/bin/wordsmith-mcp

Opens a browser UI where each tool can be called by hand and the raw JSON-RPC traffic inspected.


HTTP mode (for hosted deployments)

The same server also speaks streamable HTTP, which is what hosted marketplaces use:

TRANSPORT=http PORT=8081 wordsmith-mcp

The MCP endpoint is then at http://localhost:8081/mcp.

Env var

Default

Meaning

TRANSPORT

stdio

stdio for local clients, http for hosted

HOST

0.0.0.0

Bind address in HTTP mode

PORT

8081

Bind port in HTTP mode

MCP_PATH

/mcp

HTTP path the MCP endpoint is served on


Deploying

Smithery's publish form takes a live HTTPS MCP endpoint, so the server is hosted first and then listed. Dockerfile and render.yaml are included for that; smithery.yaml is kept for hosts that build the container directly.

Full walkthrough: DEPLOY.md.

In short: deploy the container to a host (Render, Railway, Fly.io — render.yaml is included), then publish the resulting https://<host>/mcp URL on Smithery.

Building the container locally first is a good sanity check:

docker build -t wordsmith-mcp .
docker run --rm -p 8081:8081 wordsmith-mcp

Project structure

wordsmith-mcp/
├── src/wordsmith_mcp/
│   ├── __init__.py        # package exports
│   ├── __main__.py        # python -m wordsmith_mcp
│   ├── server.py          # MCP server: tool definitions and schemas
│   └── textutils.py       # pure text logic, no MCP imports
├── scripts/smoke_test.py  # end-to-end client that exercises every tool
├── tests/test_textutils.py
├── examples/claude_desktop_config.json
├── Dockerfile
├── smithery.yaml
├── pyproject.toml
└── README.md

textutils.py holds the algorithms and imports nothing from MCP, so the logic is unit-testable on its own; server.py is a thin protocol layer that describes those functions to the model.


How it works (a 60-second tour of MCP)

MCP is a JSON-RPC protocol that lets an AI client discover and call tools exposed by a server.

  1. The client launches the server (as a subprocess over stdio, or connects over HTTP).

  2. Client and server exchange an initialize handshake announcing protocol version and capabilities.

  3. The client calls tools/list. The SDK generates each tool's JSON Schema from the Python type hints and Field(...) descriptions, so the model sees exactly what arguments are valid.

  4. When the model decides a tool is needed, the client sends tools/call with arguments; the server runs the Python function and returns the result — both as human-readable text and as structuredContent matching the declared output schema.

Adding a tool is therefore just writing a typed Python function and decorating it with @mcp.tool(...).


Further reading in this repo

  • WRITEUP.md — my write-up on using an existing MCP server (Context7) and what I learned building this one.

  • DEPLOY.md — step-by-step guide to publishing this server on Smithery and Glama.


License

MIT — see LICENSE.

Available Tools

7 tools
convert_caseConvert text caseA
Read-onlyIdempotent

Rewrite text into a naming convention: snake_case, kebab-case, slug, camelCase, PascalCase, CONSTANT_CASE, Title Case, Sentence case, UPPER or lower. Handles input that is already in any of these styles.

Inputs: text (required), style (required). Returns: result

diff_textsDiff two textsA
Read-onlyIdempotent

Return a unified diff between two versions of a text, line by line, so edits between a draft and a revision can be reviewed precisely. Returns a note when the two inputs are identical.

Inputs: after (required), before (required), context_lines. Returns: result

extract_entitiesExtract entitiesA
Read-onlyIdempotent

Pull structured items out of free text: email addresses, URLs, #hashtags, @mentions, phone numbers and standalone numbers. Results are de-duplicated and returned in the order they first appear.

Inputs: text (required). Returns: Structured items pulled out of free text.

extract_keywordsExtract keywordsA
Read-onlyIdempotent

Return the most frequent meaningful words in the text, with counts and relative frequency. Common English stopwords and very short tokens are filtered out. Useful for tagging, SEO checks or spotting what a document is actually about.

Inputs: text (required), limit, min_length. Returns: result

readabilityScore readabilityA
Read-onlyIdempotent

Compute Flesch Reading Ease and Flesch-Kincaid grade level for the text, with a plain-language interpretation. Use it to check whether a draft matches its intended audience before publishing.

Inputs: text (required). Returns: Flesch-family readability scores.

summarize_textSummarize textA
Read-onlyIdempotent

Produce an extractive summary by scoring each sentence on the frequency of the meaningful words it contains and returning the highest-scoring sentences in their original order. Works fully offline; no model call is made.

Inputs: text (required), max_sentences. Returns: result

text_statsAnalyze text statisticsA
Read-onlyIdempotent

Count characters, words, unique words, sentences, paragraphs and lines in a piece of text, plus average word/sentence length and an estimated reading time. Use this to check length limits or to profile a draft before editing.

Inputs: text (required). Returns: Structural counts for a piece of text.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: statistics, summarization, keywords, readability, case conversion, entity extraction, and diffing. While several tools analyze text, their outputs are different enough that an agent should not confuse them.

    Naming Consistency4/5

    Most tools follow a verb_noun pattern such as summarize_text, extract_keywords, convert_case, and diff_texts. text_stats and readability are minor deviations that are still readable and predictable.

    Tool Count5/5

    Seven tools is a well-scoped size for a text analysis and transformation server. Each tool covers a distinct utility without unnecessary overlap or bloat.

    Completeness4/5

    The toolkit covers the core text-analysis workflow: profiling, summarizing, keyword extraction, readability, transformations, entity extraction, and diffing. Minor gaps like sentiment analysis or language detection are common additions but not clearly required for the stated purpose.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers