文颜 (Wenyan) MCP Server 技术文档

欢迎使用文颜 MCP Server。本中心提供了从零开始安装、配置、开发及进阶使用的完整指南。

安装与快速开始

npm install -g @wenyan-md/mcp

Claude Desktop 配置 (claude_desktop_config.json)：：

{
  "mcpServers": {
    "wenyan-mcp": {
      "command": "wenyan-mcp",
      "env": {
        "WECHAT_APP_ID": "your_app_id",
        "WECHAT_APP_SECRET": "your_app_secret"
      }
    }
  }
}

工具参考 (Tools)

文颜 MCP 提供了以下核心工具供 AI 调用：

`publish_article`

将 Markdown 内容发布至微信公众号草稿箱。

参数:
- content: (string) Markdown 文本内容。
- content_url: (string) 可选，远程 Markdown 文件的 URL。
- file: (string) 可选，本地 Markdown 文件的绝对路径。
- theme_id: (string) 渲染所使用的主题名称。
- app_id: (string) 可选，指定发布的目标公众号 AppId（仅 Server 模式有效）。

`list_themes`

获取当前已安装的所有排版主题列表（包括内置和自定义）。

`register_theme`

注册一个新的自定义 CSS 主题。

参数:
- name: (string) 主题的唯一标识符。
- path: (string) CSS 文件的路径或 URL。

`remove_theme`

从系统中删除一个已注册的自定义主题。

参数:
- name: (string) 要删除的主题标识符。

运行模式详解

1. 本地模式 (Stdio Mode)

特点: 最简单，直接连接。
依赖: 宿主机需配置 WECHAT_APP_ID 和 WECHAT_APP_SECRET。
网络: 宿主机 IP 必须在微信公众号后台的 IP 白名单中。

2. 远程客户端模式 (Client-Server Mode)

特点: MCP 仅作为转发层，实际发布由远程 Server 完成。
优势:
- 完美解决 IP 白名单频繁变动的问题。
- 支持连接多个公众号。
配置: 启动时使用 --server <url> --api-key <key>。

内容格式指南

为了确保发布成功，建议 Markdown 文件遵循以下标准：

Frontmatter 示例

---
title: "你的文章标题"
author: "作者名"
cover: "https://example.com/cover.jpg" # 也可以是本地路径
source_url: "https://yoursite.com"
---

图片支持

文颜会自动检测正文中的 ![]() 语法，并尝试上传图片：

网络图片: 自动下载并上传。
本地图片: 请确保路径正确（Docker 模式下需注意挂载路径）。

最佳实践

提示词优化: 可以在 Claude 的指令中加入：“在发布前，请列出所有可用主题供我选择。”
预览建议: 文颜目前直接存入草稿箱，建议在微信公众号后台进行最后的预览确认。
安全性: 请勿在公开场合泄露你的 WECHAT_APP_SECRET。

常见问题 (FAQ)

Q: 为什么提示 IP 不在白名单？
A: 请检查运行 wenyan-mcp 的机器公网 IP，并将其添加到微信公众号后台（开发 -> 基本配置 -> IP 白名单）。

Q: Docker 模式下找不到图片文件？
A: 确保在 docker run 时正确使用了 -v 挂载，并且 HOST_FILE_PATH 环境变量指向了宿主机的正确目录。

💡 提示： 本文档随项目持续更新。如遇问题，请查阅 GitHub Issues。