# wechat-writer-mcp

<div align="center">

<!-- 核心信息徽章 -->
<div style="margin-bottom: 8px;">
  <a href="https://www.npmjs.com/package/wechat-writer-mcp">
    <img src="https://img.shields.io/npm/v/wechat-writer-mcp?style=flat-square&logo=npm&color=cb3837" alt="NPM Version" />
  </a>
  <a href="https://github.com/datoushiwo/wechat-writer-mcp/blob/main/LICENSE">
    <img src="https://img.shields.io/npm/l/wechat-writer-mcp?style=flat-square&color=green" alt="License" />
  </a>
  <a href="https://www.npmjs.com/package/wechat-writer-mcp">
    <img src="https://img.shields.io/npm/dm/wechat-writer-mcp?style=flat-square&logo=npm&color=blue" alt="Downloads" />
  </a>
</div>

<!-- 技术栈徽章 -->
<div>
  <a href="https://nodejs.org/">
    <img src="https://img.shields.io/node/v/wechat-writer-mcp?style=flat-square&logo=node.js&color=339933" alt="Node.js" />
  </a>
  <a href="https://www.typescriptlang.org/">
    <img src="https://img.shields.io/badge/TypeScript-5.0+-blue?style=flat-square&logo=typescript" alt="TypeScript" />
  </a>
  <a href="https://modelcontextprotocol.io/">
    <img src="https://img.shields.io/badge/MCP-1.1.3-purple?style=flat-square" alt="MCP" />
  </a>
  <a href="https://developers.weixin.qq.com/doc/offiaccount/Draft_Box/Add_draft.html">
    <img src="https://img.shields.io/badge/微信公众号-官方API-07c160?style=flat-square" alt="WeChat" />
  </a>
</div>

</div>

面向技术博主的 AI 内容加工流水线 MCP —— 从原始素材到公众号草稿箱，**只存草稿，不自动发布**。

## ⚡ 快速开始

### 一键启动

```bash
npx wechat-writer-mcp
```

### MCP 配置

```json
{
  "mcpServers": {
    "wechat-writer": {
      "command": "npx",
      "args": ["wechat-writer-mcp"],
      "env": {
        "WECHAT_APP_ID": "your_app_id",
        "WECHAT_APP_SECRET": "your_app_secret"
      }
    }
  }
}
```

### 立即体验

```text
AI指令: "导入 ./my-article.md，帮我排版成公众号格式，检查原创度后存入草稿箱"
```

## 🛠️ 核心功能

- **4 个专业工具** - 导入素材、智能排版、原创检测、存入草稿箱
- **官方 API** - 基于微信公众号草稿箱 API，完全合规
- **内容加工** - 段落切分、代码块处理、超链接转脚注、头尾模板、标题候选
- **安全第一** - 永远只存草稿箱，永远不自动群发/发布
- **即插即用** - 支持 Claude Code、Cursor、Claude Desktop

## 📦 工具列表

| 工具 | 说明 | 输入 | 输出 |
|------|------|------|------|
| `import_source` | 导入原始内容 | 本地 markdown 文件或网页 URL | raw_markdown + 标题/字数等元数据 |
| `transform_for_wechat` | 公众号智能排版 | markdown 内容 | 适配 HTML + 3 个标题候选 + 摘要建议 |
| `estimate_originality` | 原创度自评 | 文章内容 | 原创度评分 + 与历史草稿的相似段落 |
| `save_to_wechat_draft` | 存入草稿箱 | 标题 + HTML 内容 | media_id + 后台链接 |

## 💡 使用流程

```
用户: 导入 ./my-article.md
AI:   [调 import_source] 已读入 838 字 markdown
      标题识别：《我用 Claude Code 三周做了一个 MCP Server》

用户: 帮我按公众号风格排版
AI:   [调 transform_for_wechat]
      - 代码块已处理为公众号可显示格式
      - 已应用头尾模板
      - 3 个标题候选：
        1. 我用 Claude Code 三周做了一个 MCP Server
        2. 我用 Claude Code 三周做了一个 MCP Server：完整实践指南
        3. 一文读懂我用 Claude Code 三周做了一个 MCP Server
      要哪个？

用户: 用 1，检查下原创度
AI:   [调 estimate_originality]
      深度原创（92/100）
      建议：可以标记"原创"
      历史比对：无重复内容

用户: OK 存草稿箱
AI:   [调 save_to_wechat_draft]
      ✅ 已存入公众号草稿箱
      → 请前往 mp.weixin.qq.com → 内容管理 → 草稿箱 手动发送
```

## ⚙️ 安装配置

### 方式一：npx 直接运行（推荐）

```bash
npx wechat-writer-mcp
```

### 方式二：本地安装

```bash
git clone https://github.com/datoushiwo/wechat-writer-mcp.git
cd wechat-writer-mcp
npm install
npm run build
```

### 环境变量

```bash
cp .env.example .env
```

| 变量 | 必填 | 说明 |
|------|------|------|
| `WECHAT_APP_ID` | ✅ | 公众号 AppID |
| `WECHAT_APP_SECRET` | ✅ | 公众号 AppSecret |
| `WECHAT_COVERS_DIR` | | 封面图片目录，默认 `~/Pictures/wechat-covers` |
| `WECHAT_DEFAULT_AUTHOR` | | 默认作者名 |
| `WECHAT_API_TIMEOUT` | | API 超时毫秒数，默认 15000 |

### 前置条件

1. **公众号 AppID/AppSecret**：mp.weixin.qq.com → 开发 → 基本配置
2. **IP 白名单**：将你的出口 IP 添加到公众号后台 → 开发 → 基本配置 → IP 白名单

### 客户端配置

<details>
<summary><b>Claude Code</b></summary>

在 `~/.claude/mcp.json` 或项目下 `.claude/mcp.json` 中添加：

```json
{
  "mcpServers": {
    "wechat-writer": {
      "command": "npx",
      "args": ["wechat-writer-mcp"],
      "env": {
        "WECHAT_APP_ID": "your_app_id",
        "WECHAT_APP_SECRET": "your_app_secret"
      }
    }
  }
}
```

</details>

<details>
<summary><b>Cursor</b></summary>

在 Cursor Settings → MCP 中添加，配置同上。

</details>

<details>
<summary><b>Claude Desktop</b></summary>

编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "wechat-writer": {
      "command": "npx",
      "args": ["wechat-writer-mcp"],
      "env": {
        "WECHAT_APP_ID": "your_app_id",
        "WECHAT_APP_SECRET": "your_app_secret"
      }
    }
  }
}
```

</details>

## ⚠️ 注意事项

- **安全**：AppSecret 永远不要提交到 Git，`.env` 已在 `.gitignore` 中
- **权限**：只调用 `draft/add`，永远不调用 `freepublish/submit` 或 `mass/send`
- **查重**：`estimate_originality` 只与你自己的历史草稿比对，**不能替代微信官方查重**
- **封面**：默认从 `~/Pictures/wechat-covers/` 随机选取，无封面时自动生成占位图
- **模板**：可自定义 `templates/wechat-header.html` 和 `templates/wechat-footer.html`

## 🗺️ Roadmap

- [x] v0.1 - MVP：4 个核心 tool + 公众号草稿箱 API
- [ ] 自定义排版主题
- [ ] 封面图片 AI 推荐
- [ ] 掘金同步发布（v2）
- [ ] 发布后数据反馈
- [ ] 多标题 A/B 建议

## 🤝 贡献

欢迎提 Issue 和 PR。

```bash
git clone https://github.com/datoushiwo/wechat-writer-mcp.git
cd wechat-writer-mcp
npm install
npm run dev  # 开发模式
```

## 📄 License

MIT

---

**让 AI 帮你搞定公众号排版，你只管写内容。** ✍️