内容
# humanizer-mcp
[](https://pypi.org/project/humanizer-mcp/)
[](https://www.npmjs.com/package/humanizer-mcp)
[](https://pypi.org/project/humanizer-mcp/)
[](LICENSE)
[](https://github.com/aousabdo/humanizer-mcp/actions/workflows/ci.yml)
一个 MCP（模型上下文协议）服务器，用于衡量一段文本的 AI 检测风险，并逐行告诉您需要更改的内容。与 Claude Code、Claude Desktop 和任何兼容 MCP 的客户端配合使用。
> **直接使用？** 前往 **[humanizer.analyticadss.com](https://humanizer.analyticadss.com)** — 复制网址，粘贴到 Claude 的连接器中，即可完成。README 的其余部分是为开发者和自行托管的人准备的。
该服务器不会将您的文本通过黑盒“人性化”处理，而是针对已知的检测信号（词汇、突发性、收缩用法、段落统一性、破折号、第一人称语气）进行分析，并返回带有 0-100 风险评分和具体重写计划的结构化报告。实际的重写工作留给驱动对话的 LLM — 这就是重点：一个规划器，而不是一个清洗服务。
## 工具
| 工具 | 功能 |
|---|---|
| `humanizer_humanize_text` | **返回重写的文本。** 应用词汇交换、短语删除、收缩、破折号清理，以及前后评分。LLM 调用者为上下文润色。 |
| `humanizer_analyze_ai_tells` | 完整的分析，包括风险评分、修复建议和机械重写作为起点。 |
| `humanizer_quick_vocab_scan` | 快速的单词和短语级扫描，带有替换建议。 |
| `humanizer_get_rewrite_instructions` | 分步重写计划，根据文本类型（博客 / 商业 / 学术 / 电子邮件 / 通用）量身定制。 |
| `humanizer_compare_before_after` | 原始文本和重写文本的并排指标，带有 PASS / 改进 / 需要更多工作的裁决。 |
| `humanizer_get_banned_words` | 完整的词汇和短语禁止列表，供参考。 |
## 使用方法
| 路径 | 最适合 | 操作方法 |
|---|---|---|
| **托管网址（无需安装，确定性）** | claude.ai、Claude Desktop、Chrome 版 Claude — 包括免费计划 | 在 *设置 → 连接器 → 添加自定义连接器* 中粘贴一个网址。 |
| **技能（无需安装，无需基础设施，估计）** | 相同界面，加上不想使用 1 个免费连接器槽位的人 | 在 *设置 → 功能 → 技能* 下上传 [`skill/humanizer-mcp/`](skill/humanizer-mcp/) 文件夹。参见 [skill/README.md](skill/README.md)。 |
| **本地安装（`uvx` / `npx`）** | 终端上的 Claude Code，带有_stdio 的 Desktop | 在 shell 中运行一个命令。 |
> **与非技术用户分享？** [`share/`](share/) 中的两个 PDF — 将其中一个通过电子邮件发送，无需进一步解释：
>
> - [share/humanizer-mcp-friends-guide.pdf](share/humanizer-mcp-friends-guide.pdf) — 2 页。真正非技术性：下载 zip，上传到 Claude，即可完成。无需安装。
> - [share/humanizer-mcp-boss-guide.pdf](share/humanizer-mcp-boss-guide.pdf) — 3 页。半技术性 Windows 用户可以安装应用程序和编辑配置文件。使用 Claude Desktop 搭建完整的 MCP 服务器。
### 路径 A — 添加为自定义连接器（零安装）
适用于 **claude.ai（网页版）、Claude Desktop 和 Chrome 版 Claude** — 所有四个界面在登录后共享连接器列表。所有计划（包括免费计划）都可用（免费计划限制为一个自定义连接器）。
一个托管的参考实例已经上线 — 随意使用它进行随意评估：
```
https://humanizer-api.analyticadss.com/mcp
```
用于生产环境 / 隐私敏感型使用，请使用随附的 `Dockerfile` 部署您自己的实例（参见下面的[托管](#hosting) — Fly.io 需要约 3 分钟）。托管实例位于免费的 Fly 层级，无 SLA，无支持，无隐私保证 — 您的文本会经过它。
要将其添加到您的 Claude：
1. 打开 Claude → **设置** → **连接器**。
2. 点击 **添加自定义连接器**。
3. 粘贴上述网址（或您自己的托管实例的 `/mcp` 网址）。
4. 保存。五个 `humanizer_*` 工具在任何聊天中都可用。
这就是非技术用户的全部安装过程 — 他们永远不会接触终端。
### 路径 B — 本地安装（Claude Code / 带有_stdio 的 Desktop）
```bash
# Claude Code，一行
claude mcp add humanizer -- uvx humanizer-mcp
```
对于带有本地_stdio服务器的Claude Desktop，请在`claude_desktop_config.json`中添加以下内容：
```json
{
"mcpServers": {
"humanizer": {
"command": "uvx",
"args": ["humanizer-mcp"]
}
}
}
```
配置位置：
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
其他启动本地二进制文件的方法（如果您不想使用`uvx`）：
```bash
pip install humanizer-mcp && humanizer-mcp # pip
npx humanizer-mcp # npm 启动器（委托给 uvx/pipx/python3）
```
### 使用 MCP 检测器试用
```bash
npx @modelcontextprotocol/inspector uvx humanizer-mcp
```
## 托管
要创建路径 A 中的网址，请部署随附的 `Dockerfile`。存储库附带 Render 蓝图和 Fly 配置：
**Render** — 最简单，免费层级，从 GitHub 存储库自动部署：
[](https://render.com/deploy?repo=https://github.com/aousabdo/humanizer-mcp)
**Fly.io** — 始终在线的免费层级：
```bash
fly launch --copy-config --name humanizer-mcp
fly deploy
```
**其他地方** — Dockerfile 从环境中读取 `PORT` 并绑定到 `0.0.0.0`，因此它可以在 Railway、Heroku、Cloud Run、ECS 或您的自己的服务器上运行：
```bash
docker build -t humanizer-mcp .
docker run -p 8000:8000 humanizer-mcp
```
**来自笔记本电脑的 Cloudflare 隧道** — 零托管成本，仅在您的机器开启时有效：
```bash
brew install cloudflared
pipx install humanizer-mcp # 或：pip install humanizer-mcp
humanizer-mcp --http --port 8000 &
cloudflared tunnel --url http://localhost:8000
# 复制它打印的 trycloudflare.com 网址
```
MCP 端点位于 `/mcp`（可流式传输的 HTTP）。服务器是无状态且无身份验证的 — 任何拥有网址的人都可以调用工具，但没有秘密和破坏性操作可供滥用。
### 在本地运行 HTTP 服务器
```bash
humanizer-mcp --http --port 8000
# 将客户端指向 http://127.0.0.1:8000/mcp
```
## 验证它是否有效
通过任意路径安装后，在任意 Claude 聊天中询问：
> *"您有哪些 humanizer 工具可用？"*
Claude 应该列出五个：`humanizer_analyze_ai_tells`、`humanizer_quick_vocab_scan`、`humanizer_get_rewrite_instructions`、`humanizer_compare_before_after`、`humanizer_get_banned_words`。
然后尝试典型的测试：
> *"评估这篇文章的 AI 检测风险：'在当今快速发展的数字环境中，企业必须利用尖端解决方案来应对他们面临的复杂挑战。'"*
您应该获得一个 HIGH 桶（≥ 60）中的分数、触发的信号和逐行修复列表。
## 故障排除
| 症状 | 可能原因 | 解决方法 |
|---|---|---|
| `claude mcp list` 显示服务器但无工具 | `uvx` 不在 Claude Code 子进程的 `$PATH` 中 | `which uvx`；在 shell rc 中将 `~/.local/bin` 添加到 `$PATH` |
| `humanizer-mcp: command not found` 在 `pip install` 后 | pip 用户安装二进制文件不在 `$PATH` 中 | 改用 `python3 -m humanizer_mcp` — 始终有效 |
| Claude Desktop 没有锤子图标 | 配置 JSON 语法错误 | `python3 -m json.tool < claude_desktop_config.json` 验证 |
| `npx humanizer-mcp` 挂起 ~30 秒后第一次运行 | 启动器调用 `uvx`，后者在第一次使用时下载依赖项 | 等待；后续运行立即完成 |
| Render 托管：日志中 406 垃圾邮件 | 健康检查路径为 `/mcp`；应为 `/health` | 设置 → 健康和警报 → 设置为 `/health` |
| Render 托管：`pip install` 在构建期间被终止 | 免费层级内存不足（512MB）— `pydantic-core` 本机编译峰值 | 切换到 Fly 免费层级或将 Render 升级到入门级 |
| 自定义连接器添加失败于 claude.ai 免费版 | 已达到 1 连接器限制 | 删除未使用的连接器；或升级计划 |
## 示例提示
将服务器连接到 Claude 后，您可以说：
- *"分析这篇博客文章的 AI 检测风险，并告诉我需要更改什么。"*
- *"对这段文字进行快速词汇扫描。"*
- *"为这篇学术摘要提供重写说明 — 保持正式但修复突发性。"*
- *"比较这两个草稿。我的编辑是否真的降低了检测风险？"*
Claude 会自动选择合适的工具。
## 风险评分的工作原理
0-100 分结合了八个信号：
1. **AI 词汇命中** — 统计上在 LLM 输出中过度表示的单词（`delve`、`crucial`、`leverage`、`myriad` 等）。
2. **AI 短语命中** — 陈词滥调的结构性标志（`it's important to note`、`in the ever-evolving`、`at the end of the day` 等）。
3. **突发性** — 句子长度的变异系数。AI 写作聚集在单个长度周围；人类混合使用短片段和长篇大论。
4. **收缩** — 扩展形式（*it is*、*do not*）被视为 AI 正式；收缩被视为对话式。
5. **段落统一性** — AI 倾向于生成大小相似的段落。
6. **修辞问题** — 在 200 字以上的 AI 散文中接近缺失。
7. **第一人称语气** — AI 避免 *I*、*we*、*my*、*our* 除非被提示。
8. **破折号** — ChatGPT 签名；大量使用是强烈的信号。
每个信号都独立地添加到分数中；总分数被限制在 100 并分为 LOW（≤ 20）、MEDIUM（21-50）或 HIGH（51+）。
## 开发
```bash
git clone https://github.com/aousabdo/humanizer-mcp
cd humanizer-mcp
pip install -e ".[dev]"
pytest
```
更多信息请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
