Skip to main content
Glama
wordsmith-mcp

wordsmith-mcp

by mirza1272

Wordsmith MCP

一个 MCP(Model Context Protocol)服务器,为任何兼容 MCP 的 AI 客户端提供一组离线文本分析与重写工具——统计、抽取式摘要、关键词提取、可读性评分、命名大小写转换、实体提取和文本差异比较。

无需 API 密钥。无需网络调用。不存储任何状态。所有操作都在你传入的文本上本地运行,因此它快速、免费,而且可以安全地处理私有文档。

基于 MCP Python SDK 构建。


为什么存在

语言模型擅长评判文本,但在测量文本时却出奇地不可靠——你问它确切的单词数或 Flesch 分数,它只会猜测。Wordsmith 为这类任务给模型提供了一个确定性的计算器,因此关于文档长度、难度和关键术语的答案都是计算出来的,而不是估算出来的。


Related MCP server: mhlabs-mcp-tools

工具

工具

功能

关键参数

text_stats

字符数、单词数、不重复单词数、句子数、段落数、行数、平均单词/句子长度、预计阅读时间

text

summarize_text

抽取式摘要——按实义词频率对句子评分,并按原始顺序返回最佳句子

text、max_sentences(1–20,默认 3)

extract_keywords

出现频率最高的实义词,附计数和相对频率;已过滤停用词

text、limit(1–50,默认 10)、min_length

readability

Flesch Reading Ease + Flesch–Kincaid 年级水平,并附通俗的解释

text

convert_case

转换为 snake、kebab、slug、camel、pascal、constant、title、sentence、upper、lower

text、style

extract_entities

提取电子邮件、URL、话题标签、提及、电话号码和独立数字

text

diff_texts

草稿与修订稿之间的统一逐行差异

before、after、context_lines

所有工具都标注了 readOnlyHint: true、openWorldHint: false——它们从不修改任何内容,也从不访问互联网。


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 .

运行:

wordsmith-mcp

服务器通过 stdio 使用 MCP 协议通信,并会一直等待客户端连接——这是正常行为,不是卡死。客户端会自行启动它;参见下文。

验证是否正常工作

python scripts/smoke_test.py

这会像真实的 MCP 客户端一样启动服务器,列出工具并逐一调用,然后打印结果。

运行单元测试

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

连接到客户端

Claude Desktop

编辑 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"
    }
  }
}

重启 Claude Desktop,然后可以问类似*“这段话的可读性如何?它的前 5 个关键词是什么?”*这样的问题。

Claude Code

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

Cursor / Windsurf / 其他客户端

任何接受 mcpServers 配置块的客户端,都采用与上方 Claude Desktop 示例相同的格式。

MCP Inspector(可视化调试)

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

会打开一个浏览器界面,你可以手动调用每个工具,并检查原始的 JSON-RPC 通信流量。


HTTP 模式(用于托管部署)

同一个服务器也支持streamable HTTP,托管市场使用的正是这种方式:

TRANSPORT=http PORT=8081 wordsmith-mcp

此时 MCP 端点位于 http://localhost:8081/mcp。

环境变量

默认值

含义

TRANSPORT

stdio

本地客户端使用 stdio,托管部署使用 http

HOST

0.0.0.0

HTTP 模式下的绑定地址

PORT

8081

HTTP 模式下的绑定端口

MCP_PATH

/mcp

MCP 端点所在的 HTTP 路径


部署

Smithery 的发布表单需要一个可用的 HTTPS MCP 端点,因此需要先托管服务器,然后再上架。为此提供了 Dockerfile 和 render.yaml;smithery.yaml 保留给直接构建容器的托管平台使用。

完整指南:DEPLOY.md。

简而言之:将容器部署到某个托管平台(Render、Railway、Fly.io——已包含 render.yaml),然后在 Smithery 上发布生成的 https://<host>/mcp URL。

先在本地构建容器是一个很好的自检方式:

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

项目结构

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 包含所有算法,且不导入任何来自 MCP 的内容,因此逻辑可以独立进行单元测试;server.py 是一个轻量协议层,负责向模型描述这些函数。


工作原理(60 秒了解 MCP)

MCP 是一种 JSON-RPC 协议,允许 AI 客户端发现并调用服务器暴露的工具。

  1. 客户端启动服务器(通过 stdio 以子进程方式运行,或通过 HTTP 连接)。

  2. 客户端与服务器交换 initialize 握手消息,声明协议版本和能力。

  3. 客户端调用 tools/list。SDK 根据 Python 类型提示和 Field(...) 描述为每个工具生成 JSON Schema,因此模型可以准确看到哪些参数是有效的。

  4. 当模型决定需要某个工具时,客户端发送带参数的 tools/call;服务器运行 Python 函数并返回结果——既包含人类可读的文本,也包含与声明的输出模式匹配的 structuredContent。

因此,添加一个工具只需编写一个带类型标注的 Python 函数,并用 @mcp.tool(...) 装饰即可。


本仓库中的延伸阅读

  • WRITEUP.md——我关于使用现有 MCP 服务器(Context7)的记录,以及构建本项目时学到的经验。

  • DEPLOY.md——在 Smithery 和 Glama 上发布此服务器的分步指南。


许可证

MIT——参见 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.

    Related MCP Connectors

    Related MCP Servers