Wordsmith MCP

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

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

基于 MCP Python SDK 构建。

为什么存在

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

Related MCP server: armavita-originality-ai-mcp

工具

所有工具都标注了 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。

部署

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。