文颜 MCP Server

1<div align="center">
2    <img alt = "logo" src="https://media.githubusercontent.com/media/caol64/wenyan-mcp/main/data/wenyan-mcp.png" />
3</div>
4 
5# 文颜 MCP Server
6 
7[![npm](https://img.shields.io/npm/v/@wenyan-md/mcp)](https://www.npmjs.com/package/@wenyan-md/mcp)
8[![License](https://img.shields.io/github/license/caol64/wenyan-mcp)](LICENSE)
9![NPM Downloads](https://img.shields.io/npm/dm/%40wenyan-md%2Fmcp)
10[![Docker Pulls](https://img.shields.io/docker/pulls/caol64/wenyan-mcp)](https://hub.docker.com/r/caol64/wenyan-mcp)
11[![Stars](https://img.shields.io/github/stars/caol64/wenyan-mcp?style=social)](https://github.com/caol64/wenyan-mcp)
12 
13## 简介
14 
15**文颜（Wenyan）** 是一款多平台 Markdown 排版与发布工具，支持将 Markdown 一键转换并发布至：
16 
17-   微信公众号
18-   知乎
19-   今日头条
20-   以及其它内容平台（持续扩展中）
21 
22文颜的目标是：**让写作者专注内容，而不是排版和平台适配**。
23 
24## 文颜的不同版本
25 
26文颜目前提供多种形态，覆盖不同使用场景：
27 
28-   [macOS App Store 版](https://github.com/caol64/wenyan) - MAC 桌面应用
29-   [跨平台桌面版](https://github.com/caol64/wenyan-pc) - Windows/Linux
30-   [CLI 版本](https://github.com/caol64/wenyan-cli) - 命令行 / CI 自动化发布
31-   👉 [MCP 版本](https://github.com/caol64/wenyan-mcp) - 本项目
32-   [核心库](https://github.com/caol64/wenyan-core) - 嵌入 Node / Web 项目
33 
34本仓库是 **文颜的 MCP Server 版本**，基于模型上下文协议（Model Context Protocol），旨在让 AI 助手（如 Claude Desktop）具备自动排版和发布公众号文章的能力。
35 
36-   **与 AI 深度集成**：[让 AI 帮你管理公众号的排版和发布](https://babyno.top/posts/2025/06/let-ai-help-you-manage-your-gzh-layout-and-publishing/)
37 
38<video src="https://github.com/user-attachments/assets/2c355f76-f313-48a7-9c31-f0f69e5ec207"></video>
39 
40> [!TIP]
41>
42> 如果与 AI 集成遇到问题，可以参考 [test/list.js](./test/list.js) 和 [test/publish.js](./test/publish.js) 中的完整调用示例。
43 
44## v2.0 新特性
45- **支持 SSE 模式**
46- **多租户支持 (Stateless)**：`publish_article` 工具优先使用传入的 `wechat_app_id` 和 `wechat_app_secret` 参数，不再强制依赖服务器环境变量。适合 SaaS 或多用户共享部署。
47- **文件上传接口 (Secure Upload)**：新增 `POST /upload` 接口，支持上传 Markdown 文件并返回临时 `file_id`。
48  - 解决 IP 限制：客户端上传文件 -> 服务器（在白名单 IP）获取内容 -> 发布到微信。
49  - 节省 Token：相比直接传输全文，使用 `file_id` 引用服务器上的临时文件更高效。
50  - 自动清理：上传的文件仅存储 10 分钟（可配置），之后自动销毁。
51- **HTTPS 支持**：支持 `--https` 启动参数，需配合 `SSL_KEY_PATH` 和 `SSL_CERT_PATH` 环境变量使用，保障传输安全。
52- **本地文件限制**：默认**禁用**本地文件访问（`--allow-local-files` 开启），以适应无状态容器化部署的安全需求。
53 
54## 运行和配置
55 
56文颜 MCP Server 支持`stdio`和`sse`两种运行模式。
57 
58### 1. stdio 模式（标准输入输出）
59 
60这是 MCP 的默认运行模式，最适合 **本地客户端**（如 Claude Desktop, VS Code）直接集成。
61 
62* **运行原理**：宿主程序（如 Claude）启动 MCP Server 作为一个子进程，通过标准输入（stdin）发送请求，通过标准输出（stdout）接收响应。
63* **适用场景**：本地 AI 开发环境、个人桌面端配置。
64 
65#### 运行方式1: npm
66 
67```bash
68# 安装 npm 包
69npm install -g @wenyan-md/mcp
70```
71 
72* **配置示例（Claude Desktop）**：
73在 `claude_desktop_config.json` 中配置：
74```json
75{
76  "mcpServers": {
77    "wenyan-mcp": {
78      "name": "公众号助手",
79      "command": "wenyan-mcp",
80      "env": {
81        "WECHAT_APP_ID": "your_app_id",
82        "WECHAT_APP_SECRET": "your_app_secret"
83      }
84    }
85  }
86}
87```
88 
89#### 运行方式2: Docker
90 
91适合部署到服务器环境，或希望环境隔离的用户。
92 
93```bash
94# 拉取镜像
95docker pull caol64/wenyan-mcp
96```
97 
98* **配置示例（Claude Desktop）**：
99 
100```json
101{
102  "mcpServers": {
103    "wenyan-mcp": {
104      "name": "公众号助手",
105      "command": "docker",
106      "args": [
107        "run",
108        "--rm",
109        "-i",
110        "-v", "/your/host/file/path:/mnt/host-downloads",
111        "-e", "WECHAT_APP_ID=your_app_id",
112        "-e", "WECHAT_APP_SECRET=your_app_secret",
113        "-e", "HOST_FILE_PATH=/your/host/file/path",
114        "caol64/wenyan-mcp"
115      ]
116    }
117  }
118}
119```
120 
121> **Docker 配置特别说明：**
122>
123> *   **挂载目录 (`-v`)**：必须将宿主机的文件/图片目录挂载到容器内的 `/mnt/host-downloads`。
124> *   **环境变量 (`HOST_FILE_PATH`)**：必须与宿主机挂载的文件/图片目录路径保持一致。
125> *   **原理**：你的 Markdown 文件/文章内所引用的本地图片应放置在该目录中，Docker 会自动将其映射，使容器能够读取并上传。
126 
127### 2. sse 模式（服务器发送事件）
128 
129SSE 模式基于 HTTP 协议，允许 MCP Server 作为一个**独立的网络服务**运行。
130 
131* **运行原理**：Server 启动一个 HTTP 端口，客户端通过 HTTP POST 发送指令，Server 通过 SSE 长连接实时推送响应数据。
132* **适用场景**：远程服务器部署、多客户端共享 Server、或者宿主环境不支持子进程管理时。
133 
134#### 运行方式1: npm
135 
136```bash
137# 安装 npm 包
138npm install -g @wenyan-md/mcp
139# 启动 HTTP 服务器
140WECHAT_APP_ID=your_app_id WECHAT_APP_SECRET=your_app_secret wenyan-mcp --sse
141```
142 
143* **配置示例（Claude Desktop）**：
144在 `claude_desktop_config.json` 中配置：
145```json
146{
147  "mcpServers": {
148    "wenyan-mcp": {
149      "name": "公众号助手",
150      "baseUrl": "http://localhost:3000/sse"
151    }
152  }
153}
154```
155 
156#### 运行方式2: Docker
157 
158```bash
159# 拉取镜像
160docker pull caol64/wenyan-mcp
161# 启动 HTTP 服务器
162docker run -d \
163  --rm
164  -p 3000:3000 \
165  -e WECHAT_APP_ID=your_app_id \
166  -e WECHAT_APP_SECRET=your_app_secret \
167  -v /your/host/file/path:/mnt/host-downloads \
168  -e HOST_FILE_PATH=/your/host/file/path \
169  --name wenyan-mcp \
170  caol64/wenyan-mcp --sse
171```
172 
173* **配置示例（Claude Desktop）**：
174同`npm`运行时配置。
175 
176#### 运行方式3: Kubernetes
177 
178本项目提供了一份标准的 Kubernetes 部署清单，包含 Deployment 和 Service 配置。
179 
180```bash
181kubectl apply -f k8s/deployment.yaml
182```
183 
184该配置默认开启了 HTTP Stateless 模式，并配置了 Liveness/Readiness 探针以确保服务高可用。
185请根据实际情况修改 `image` 版本或调整资源限制。
186 
187* **配置示例（Claude Desktop）**：
188同`npm`运行时配置。
189 
190#### 高级配置
191 
192HTTP 服务器支持以下环境变量进行高级配置：
193 
194| 环境变量 | 默认值 | 说明 |
195|----------|--------|------|
196| `HTTP_CORS_ORIGIN` | `*` | 允许的 CORS 来源，可设置为具体域名（如 `https://example.com`）以限制跨域访问 |
197| `HTTP_API_KEY` | 无 | 如果设置，所有请求必须携带 `X-API-Key` 头且值与此匹配（健康检查和根端点除外） |
198| `HTTP_LOG_LEVEL` | `info` | 日志级别：`debug`、`info`、`warn`、`error` |
199 
200**带认证的 Docker 运行示例：**
201 
202```bash
203docker run -d \
204  --rm
205  -p 3000:3000 \
206  -e WECHAT_APP_ID=your_app_id \
207  -e WECHAT_APP_SECRET=your_app_secret \
208  -e HTTP_API_KEY=your_secret_api_key \
209  -e HTTP_CORS_ORIGIN=https://yourdomain.com \
210  -v /your/host/file/path:/mnt/host-downloads \
211  -e HOST_FILE_PATH=/your/host/file/path \
212  --name wenyan-mcp \
213  caol64/wenyan-mcp --sse
214```
215 
216**配置带认证的 MCP Client：**
217 
218```json
219{
220  "mcpServers": {
221    "wenyan-mcp-http": {
222      "name": "公众号助手 (HTTP)",
223      "baseUrl": "http://localhost:3000/sse",
224      "headers": {
225        "X-API-Key": "your_secret_api_key"
226      }
227    }
228  }
229}
230```
231 
232## 基本用法
233 
234### 列出主题
235 
236对AI说
237 
238> 目前你可以使用哪些公众号主题？
239 
240AI回复：
241 
242```
243目前我支持的公众号主题包括以下这些，每个主题都有独特的风格和配色，适用于不同的内容调性：
244 
2451. **Default（默认）**  
246   简洁经典的排版，适合长文阅读，通用性强。
247 
2482. **OrangeHeart（橙心）**  
249   暖橙色调，优雅而富有活力，适合情感、生活类内容。
250...
251```
252 
253### 注册主题
254 
255对AI说
256 
257> 帮我把这个css(https://wenyan.yuzhi.tech/manhua.css)注册为一个新的公众号主题，名称为：xiuluochang
258 
259AI回复：
260 
261```
262好的，已成功将 CSS 样式表注册为新的公众号主题，主题名称为：**xiuluochang**。
263 
264您现在可以在公众号后台选择该主题进行应用，样式将按照 `https://wenyan.yuzhi.tech/manhua.css` 的定义进行渲染。
265 
266如有需要进一步自定义或更换主题，随时告诉我！
267```
268 
269### 删除主题
270 
271对AI说
272 
273> 把名为“xiuluochang”的公众号主题删除
274 
275AI回复：
276 
277```
278公众号主题 “xiuluochang” 已成功删除。
279```
280 
281### 发布文章
282 
283对AI说
284 
285> 使用phycat主题将这篇文章发布到微信公众号：`./tests/publish.md`
286 
287AI回复：
288 
289```
290文章已成功发布至微信公众号草稿箱！🎉
291 
292- **主题**：phycat  
293- **媒体ID**：xxx
294 
295您可登录微信公众号后台，在「草稿箱」中查看并编辑文章，确认无误后即可一键发布。如需进一步排版优化、添加封面或设置摘要，我也可以协助您完成！
296 
297是否需要我帮您生成一篇发布文案或封面建议？ 😊
298```
299 
300## 关于图片自动上传
301 
302支持以下图片来源：
303 
304-   本地路径（如：`/Users/lei/Downloads/result_image.jpg`）
305-   网络路径（如：`https://example.com/image.jpg`）
306 
307## 环境变量说明
308 
309无论使用哪种方式，都需要配置以下环境变量以连接微信公众号平台：
310 
311-   `WECHAT_APP_ID`：微信公众号平台的 App ID
312-   `WECHAT_APP_SECRET`：微信公众号平台的 App Secret
313 
314## Markdown Frontmatter 说明（必读）
315 
316为了正确上传文章，每篇 Markdown 顶部需要包含 frontmatter：
317 
318```md
319---
320title: 在本地跑一个大语言模型(2) - 给模型提供外部知识库
321cover: /Users/xxx/image.jpg
322---
323```
324 
325字段说明：
326 
327-   `title` 文章标题（必填）
328-   `cover` 文章封面
329    -   本地路径或网络图片
330    -   如果正文有至少一张图片，可省略，此时将使用其中一张作为封面
331    -   如果正文无图片，则必须提供 cover
332 
333## 微信公众号 IP 白名单
334 
335> [!IMPORTANT]
336>
337> 请确保运行文颜 MCP Server 的机器 IP 已加入微信公众号后台的 IP 白名单，否则上传接口将调用失败。
338 
339配置说明文档：[https://yuzhi.tech/docs/wenyan/upload](https://yuzhi.tech/docs/wenyan/upload)
340 
341## 示例文章格式
342 
343```md
344---
345title: 在本地跑一个大语言模型(2) - 给模型提供外部知识库
346cover: /Users/lei/Downloads/result_image.jpg
347---
348 
349在[上一篇文章](https://babyno.top/posts/2024/02/running-a-large-language-model-locally/)中，我们展示了如何在本地运行大型语言模型。本篇将介绍如何让模型从外部知识库中检索定制数据，提升答题准确率，让它看起来更“智能”。
350 
351## 准备模型
352 
353访问 `Ollama` 的模型页面，搜索 `qwen`，我们使用支持中文语义的“[通义千问](https://ollama.com/library/qwen:7b)”模型进行实验。
354 
355![](https://mmbiz.qpic.cn/mmbiz_jpg/Jsq9IicjScDVUjkPc6O22ZMvmaZUzof5bLDjMyLg2HeAXd0icTvlqtL7oiarSlOicTtiaiacIxpVOV1EeMKl96PhRPPw/640?wx_fmt=jpeg)
356```
357 
358## 如何调试
359 
360推荐使用官方 Inspector 进行调试：
361 
362```bash
363npx @modelcontextprotocol/inspector <command>
364```
365 
366启动成功出现类似提示：
367 
368```bash
369🔗 Open inspector with token pre-filled:
370   http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=761c05058aa4f84ad02280e62d7a7e52ec0430d00c4c7a61492cca59f9eac299
371   (Auto-open is disabled when authentication is enabled)
372```
373 
374访问以上链接即可打开调试页面。
375 
376![debug](data/1.jpg)
377 
3781. 正确填写启动命令
3792. 添加环境变量
3803. 点击 Connect
3814. 选择 Tools -> List Tools
3825. 选择要调试的接口
3836. 填入参数并点击 Run Tool
3847. 查看完整参数
385 
386## 赞助
387 
388如果你觉得文颜对你有帮助，可以给我家猫咪买点罐头 ❤️
389 
390[https://yuzhi.tech/sponsor](https://yuzhi.tech/sponsor)
391 
392## License
393 
394Apache License Version 2.0
395