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: armavita-originality-ai-mcp

Tools

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.

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.