@wenyan-md/mcp 1.0.7 → 1.0.9

package/README.md

@@ -1,4 +1,6 @@
-![logo](data/wenyan-mcp.png)
+<div align="center">
+    <img alt = "logo" src="https://media.githubusercontent.com/media/caol64/wenyan-mcp/main/data/wenyan-mcp.png" />
+</div>
 
 # 文颜 MCP Server
 
@@ -8,94 +10,70 @@
 [![Docker Pulls](https://img.shields.io/docker/pulls/caol64/wenyan-mcp)](https://hub.docker.com/r/caol64/wenyan-mcp)
 [![Stars](https://img.shields.io/github/stars/caol64/wenyan-mcp?style=social)](https://github.com/caol64/wenyan-mcp)
 
-「文颜」是一款多平台排版美化工具，让你将 Markdown 一键发布至微信公众号、知乎、今日头条等主流写作平台。
+## 简介
 
-**文颜**现已推出多个版本：
+**文颜（Wenyan）** 是一款多平台 Markdown 排版与发布工具，支持将 Markdown 一键转换并发布至：
 
-* [macOS App Store 版](https://github.com/caol64/wenyan) - MAC 桌面应用
-* [跨平台版本](https://github.com/caol64/wenyan-pc) - Windows/Linux 跨平台桌面应用
-* [CLI 版本](https://github.com/caol64/wenyan-cli) - CI/CD 或脚本自动化发布公众号文章
-* [MCP 版本](https://github.com/caol64/wenyan-mcp) - 让 AI 自动发布公众号文章
-* [嵌入版本](https://github.com/caol64/wenyan-core) - 将文颜的核心功能嵌入 Node 或者 Web 项目
+-   微信公众号
+-   知乎
+-   今日头条
+-   以及其它内容平台（持续扩展中）
 
-文颜 MCP Server 是一个基于模型上下文协议（Model Context Protocol, MCP）的服务器组件，支持将 Markdown 格式的文章发布至微信公众号草稿箱，并使用与 [文颜](https://yuzhi.tech/wenyan) 相同的主题系统进行排版。
+文颜的目标是：**让写作者专注内容，而不是排版和平台适配**。
 
-https://github.com/user-attachments/assets/2c355f76-f313-48a7-9c31-f0f69e5ec207
+本仓库是 **文颜的 MCP Server 版本**，基于模型上下文协议（Model Context Protocol），旨在让 AI 助手（如 Claude Desktop）具备自动排版和发布公众号文章的能力。
 
-使用场景：
+## 文颜的不同版本
 
-- [让AI帮你管理公众号的排版和发布](https://babyno.top/posts/2025/06/let-ai-help-you-manage-your-gzh-layout-and-publishing/)
+文颜目前提供多种形态，覆盖不同使用场景：
 
-## 功能
+-   [macOS App Store 版](https://github.com/caol64/wenyan) - MAC 桌面应用
+-   [跨平台桌面版](https://github.com/caol64/wenyan-pc) - Windows/Linux
+-   [CLI 版本](https://github.com/caol64/wenyan-cli) - 命令行 / CI 自动化发布
+-   👉 [MCP 版本](https://github.com/caol64/wenyan-mcp) - 本项目
+-   [核心库](https://github.com/caol64/wenyan-core) - 嵌入 Node / Web 项目
 
-- 列出并选择支持的文章主题
-- 使用内置主题对 Markdown 内容排版
-- 发布文章到微信公众号草稿箱
-- 自动上传本地或网络图片
+## 功能特性
 
-## 主题效果
+-   列出并选择支持的文章主题
+-   使用内置主题对 Markdown 内容排版
+-   自动处理并上传图片（本地 / 网络）
+-   一键发布文章到微信公众号草稿箱
+-   **与 AI 深度集成**：[让 AI 帮你管理公众号的排版和发布](https://babyno.top/posts/2025/06/let-ai-help-you-manage-your-gzh-layout-and-publishing/)
 
-👉 [内置主题预览](https://yuzhi.tech/docs/wenyan/theme)
-
-文颜采用了多个开源的 Typora 主题，在此向各位作者表示感谢：
+<video src="https://github.com/user-attachments/assets/2c355f76-f313-48a7-9c31-f0f69e5ec207"></video>
 
-- [Orange Heart](https://github.com/evgo2017/typora-theme-orange-heart)
-- [Rainbow](https://github.com/thezbm/typora-theme-rainbow)
-- [Lapis](https://github.com/YiNNx/typora-theme-lapis)
-- [Pie](https://github.com/kevinzhao2233/typora-theme-pie)
-- [Maize](https://github.com/BEATREE/typora-maize-theme)
-- [Purple](https://github.com/hliu202/typora-purple-theme)
-- [物理猫-薄荷](https://github.com/sumruler/typora-theme-phycat)
-
-## 使用方式
+> [!TIP]
+>
+> 如果与 AI 集成遇到问题，可以参考 [test/list.js](./test/list.js) 和 [test/publish.js](./test/publish.js) 中的完整调用示例。
 
-### 方式一：本地安装（推荐）
+## 主题效果预览
 
-```
-npm install -g @wenyan-md/mcp
-```
+👉 [内置主题预览](https://yuzhi.tech/docs/wenyan/theme)
 
-#### 与 MCP Client 集成
+文颜内置并适配了多个优秀的 Typora 主题，在此感谢原作者：
 
-在你的 MCP 配置文件中加入以下内容：
+-   [Orange Heart](https://github.com/evgo2017/typora-theme-orange-heart)
+-   [Rainbow](https://github.com/thezbm/typora-theme-rainbow)
+-   [Lapis](https://github.com/YiNNx/typora-theme-lapis)
+-   [Pie](https://github.com/kevinzhao2233/typora-theme-pie)
+-   [Maize](https://github.com/BEATREE/typora-maize-theme)
+-   [Purple](https://github.com/hliu202/typora-purple-theme)
+-   [物理猫-薄荷](https://github.com/sumruler/typora-theme-phycat)
 
-```json
-{
-  "mcpServers": {
-    "wenyan-mcp": {
-      "name": "公众号助手",
-      "command": "wenyan-mcp",
-      "env": {
-        "WECHAT_APP_ID": "your_app_id",
-        "WECHAT_APP_SECRET": "your_app_secret"
-      }
-    }
-  }
-}
-```
-
-> 说明：
->
-> * `WECHAT_APP_ID` 微信公众号平台的 App ID
-> * `WECHAT_APP_SECRET` 微信平台的 App Secret
-
----
+## 安装与集成
 
-### 方式二：编译运行
+文颜 MCP Server 支持多种运行方式，请根据你的环境选择。
 
-#### 编译
+### 方式一：npm 安装（推荐）
 
-确保已安装 [Node.js](https://nodejs.org/) 环境：
+直接安装到本地：
 
 ```bash
-git clone https://github.com/caol64/wenyan-mcp.git
-cd wenyan-mcp
-
-npm install
-npx tsc -b
+npm install -g @wenyan-md/mcp
 ```
 
-#### 与 MCP Client 集成
+**配置 MCP Client（如 Claude Desktop）：**
 
 在你的 MCP 配置文件中加入以下内容：
 
@@ -104,10 +82,7 @@ npx tsc -b
   "mcpServers": {
     "wenyan-mcp": {
       "name": "公众号助手",
-      "command": "node",
-      "args": [
-        "Your/path/to/wenyan-mcp/dist/index.js"
-      ],
+      "command": "wenyan-mcp",
       "env": {
         "WECHAT_APP_ID": "your_app_id",
         "WECHAT_APP_SECRET": "your_app_secret"
@@ -117,34 +92,17 @@ npx tsc -b
 }
 ```
 
-> 说明：
->
-> * `WECHAT_APP_ID` 微信公众号平台的 App ID
-> * `WECHAT_APP_SECRET` 微信平台的 App Secret
-
----
-
-### 方式三：使用 Docker 运行（推荐）
+### 方式二：Docker 运行（推荐）
 
-适合部署到服务器环境，或与本地 AI 工具链集成。
+适合部署到服务器环境，或希望环境隔离的用户。
 
-#### 你可以直接下载编译好的docker镜像
+**拉取镜像：**
 
 ```bash
 docker pull caol64/wenyan-mcp
 ```
 
-#### 或者自己构建镜像
-
-```bash
-docker build -t wenyan-mcp .
-# 国内用户可以指定`npm`镜像源。
-docker build --build-arg NPM_REGISTRY=https://mirrors.cloud.tencent.com/npm/ -t wenyan-mcp .
-```
-
-#### 与 MCP Client 集成
-
-在你的 MCP 配置文件中加入以下内容：
+**配置 MCP Client：**
 
 ```json
 {
@@ -156,53 +114,63 @@ docker build --build-arg NPM_REGISTRY=https://mirrors.cloud.tencent.com/npm/ -t
         "run",
         "--rm",
         "-i",
-        "-v", "/your/host/image/path:/mnt/host-downloads",
+        "-v", "/your/host/file/path:/mnt/host-downloads",
         "-e", "WECHAT_APP_ID=your_app_id",
         "-e", "WECHAT_APP_SECRET=your_app_secret",
-        "-e", "HOST_IMAGE_PATH=/your/host/image/path",
-        "wenyan-mcp"
+        "-e", "HOST_FILE_PATH=/your/host/file/path",
+        "caol64/wenyan-mcp"
       ]
     }
   }
 }
 ```
 
-> 说明：
+> **Docker 配置特别说明：**
 >
-> * `-v` 挂载宿主机目录，使容器内部可以访问本地图片。与环境变量`HOST_IMAGE_PATH`保持一致。你的 `Markdown` 文章内的本地图片应该都放置在该目录中，docker会自动将它们映射到容器内。容器无法读取在该目录以外的图片。
-> * `-e` 注入docker容器的环境变量：
-> * `WECHAT_APP_ID` 微信公众号平台的 App ID
-> * `WECHAT_APP_SECRET` 微信平台的 App Secret
-> * `HOST_IMAGE_PATH` 宿主机图片目录
+> *   **挂载目录 (`-v`)**：必须将宿主机的文件/图片目录挂载到容器内的 `/mnt/host-downloads`。
+> *   **环境变量 (`HOST_FILE_PATH`)**：必须与宿主机挂载的文件/图片目录路径保持一致。
+> *   **原理**：你的 Markdown 文件/文章内所引用的本地图片应放置在该目录中，Docker 会自动将其映射，使容器能够读取并上传。
 
-## 微信公众号 IP 白名单
+## 环境变量说明
+
+无论使用哪种方式，都需要配置以下环境变量以连接微信公众号平台：
 
-请务必将服务器 IP 加入公众号平台的 IP 白名单，以确保上传接口调用成功。
-详细配置说明请参考：[https://yuzhi.tech/docs/wenyan/upload](https://yuzhi.tech/docs/wenyan/upload)
+-   `WECHAT_APP_ID`：微信公众号平台的 App ID
+-   `WECHAT_APP_SECRET`：微信公众号平台的 App Secret
 
-## 配置说明（Frontmatter）
+## Markdown Frontmatter 说明（必读）
 
-为了可以正确上传文章，需要在每一篇 Markdown 文章的开头添加一段`frontmatter`，提供`title`、`cover`两个字段：
+为了正确上传文章，每篇 Markdown 顶部需要包含 frontmatter：
 
 ```md
 ---
 title: 在本地跑一个大语言模型(2) - 给模型提供外部知识库
-cover: /Users/lei/Downloads/result_image.jpg
+cover: /Users/xxx/image.jpg
 ---
 ```
 
-* `title` 是文章标题，必填。
-* `cover` 是文章封面，支持本地路径和网络图片：
+字段说明：
 
-  * 如果正文有至少一张图片，可省略，此时将使用其中一张作为封面；
-  * 如果正文无图片，则必须提供 cover。
+-   `title` 文章标题（必填）
+-   `cover` 文章封面
+    -   本地路径或网络图片
+    -   如果正文有至少一张图片，可省略，此时将使用其中一张作为封面
+    -   如果正文无图片，则必须提供 cover
 
 ## 关于图片自动上传
 
-* 支持图片路径：
+支持以下图片来源：
+
+-   本地路径（如：`/Users/lei/Downloads/result_image.jpg`）
+-   网络路径（如：`https://example.com/image.jpg`）
 
-  * 本地路径（如：`/Users/lei/Downloads/result_image.jpg`）
-  * 网络路径（如：`https://example.com/image.jpg`）
+## 微信公众号 IP 白名单
+
+> [!IMPORTANT]
+>
+> 请确保运行文颜 MCP Server 的机器 IP 已加入微信公众号后台的 IP 白名单，否则上传接口将调用失败。
+
+配置说明文档：[https://yuzhi.tech/docs/wenyan/upload](https://yuzhi.tech/docs/wenyan/upload)
 
 ## 示例文章格式
 
@@ -223,15 +191,15 @@ cover: /Users/lei/Downloads/result_image.jpg
 
 ## 如何调试
 
-使用 Inspector 进行简单调试：
+推荐使用官方 Inspector 进行调试：
 
-```
-npx @modelcontextprotocol/inspector
+```bash
+npx @modelcontextprotocol/inspector <command>
 ```
 
 启动成功出现类似提示：
 
-```
+```bash
 🔗 Open inspector with token pre-filled:
    http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=761c05058aa4f84ad02280e62d7a7e52ec0430d00c4c7a61492cca59f9eac299
    (Auto-open is disabled when authentication is enabled)
@@ -251,7 +219,9 @@ npx @modelcontextprotocol/inspector
 
 ## 赞助
 
-如果您觉得这个项目不错，可以给我家猫咪买点罐头吃。[喂猫❤️](https://yuzhi.tech/sponsor)
+如果你觉得文颜对你有帮助，可以给我家猫咪买点罐头 ❤️
+
+[https://yuzhi.tech/sponsor](https://yuzhi.tech/sponsor)
 
 ## License
 

package/dist/index.js

@@ -9,10 +9,13 @@
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { getGzhContent } from "@wenyan-md/core/wrapper";
 import { publishToDraft } from "@wenyan-md/core/publish";
 import { themes } from "@wenyan-md/core/theme";
+import { getNormalizeFilePath } from "./utils.js";
+import fs from "node:fs/promises";
+import path from "node:path";
 /**
  * Create an MCP server with capabilities for resources (to list/read notes),
  * tools (to create new notes), and prompts (to summarize notes).
@@ -43,14 +46,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     properties: {
                         content: {
                             type: "string",
-                            description: "The original Markdown content to publish, preserving its frontmatter (if present).",
+                            description: "The Markdown text to publish. REQUIRED if 'file' is not provided. Preserves frontmatter if present.",
+                        },
+                        file: {
+                            type: "string",
+                            description: "The path to the Markdown file (absolute or relative). REQUIRED if 'content' is not provided.",
                         },
                         theme_id: {
                             type: "string",
                             description: "ID of the theme to use (e.g., default, orangeheart, rainbow, lapis, pie, maize, purple, phycat).",
                         },
                     },
-                    required: ["content"],
+                    anyOf: [{ required: ["content"] }, { required: ["file"] }],
                 },
             },
             {
@@ -58,7 +65,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 description: "List the themes compatible with the 'publish_article' tool to publish an article to '微信公众号'.",
                 inputSchema: {
                     type: "object",
-                    properties: {}
+                    properties: {},
                 },
             },
         ],
@@ -74,12 +81,28 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         //     level: "debug",
         //     data: JSON.stringify(request.params.arguments),
         // });
-        const content = String(request.params.arguments?.content || "");
+        let content = String(request.params.arguments?.content || "");
+        const file = String(request.params.arguments?.file || "");
         const themeId = String(request.params.arguments?.theme_id || "");
+        let absoluteDirPath = undefined;
+        if (!content && file) {
+            const normalizePath = getNormalizeFilePath(file);
+            content = await fs.readFile(normalizePath, "utf-8");
+            absoluteDirPath = path.dirname(normalizePath);
+        }
+        if (!content) {
+            throw new Error("Missing content to publish");
+        }
         const gzhContent = await getGzhContent(content, themeId, "solarized-light", true, true);
-        const title = gzhContent.title ?? "this is title";
-        const cover = gzhContent.cover ?? "";
-        const response = await publishToDraft(title, gzhContent.content, cover);
+        if (!gzhContent.title) {
+            throw new Error("未能找到文章标题");
+        }
+        if (!gzhContent.cover) {
+            throw new Error("未能找到文章封面");
+        }
+        const response = await publishToDraft(gzhContent.title, gzhContent.content, gzhContent.cover, {
+            relativePath: absoluteDirPath,
+        });
         return {
             content: [
                 {
@@ -95,7 +118,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             text: JSON.stringify({
                 id: theme.id,
                 name: theme.name,
-                description: theme.description
+                description: theme.description,
             }),
         }));
         return {

package/dist/types/utils.d.ts

@@ -0,0 +1 @@
+export declare function getNormalizeFilePath(inputPath: string): string;

package/dist/utils.js

@@ -0,0 +1,27 @@
+import path from "node:path";
+/**
+ * 路径标准化工具函数
+ * 将 Windows 的反斜杠 \ 转换为正斜杠 /，并去除末尾斜杠
+ * 目的：在 Linux 容器内也能正确处理 Windows 路径字符串
+ */
+function normalizePath(p) {
+    return p.replace(/\\/g, "/").replace(/\/+$/, "");
+}
+export function getNormalizeFilePath(inputPath) {
+    const isContainer = !!process.env.CONTAINERIZED;
+    if (isContainer) {
+        const hostFilePath = normalizePath(process.env.HOST_FILE_PATH || "");
+        const containerFilePath = normalizePath(process.env.CONTAINER_FILE_PATH || "/mnt/host-downloads");
+        let relativePart = normalizePath(inputPath);
+        if (relativePart.startsWith(hostFilePath)) {
+            relativePart = relativePart.slice(hostFilePath.length);
+        }
+        if (!relativePart.startsWith("/")) {
+            relativePart = "/" + relativePart;
+        }
+        return containerFilePath + relativePart;
+    }
+    else {
+        return path.resolve(inputPath);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wenyan-md/mcp",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "MCP server for Wenyan, a Markdown formatting tool that allows AI assistants to apply elegant built-in themes and publish articles directly to 微信公众号.",
   "author": "Lei <caol64@gmail.com> (https://github.com/caol64)",
   "license": "Apache-2.0",
@@ -31,18 +31,19 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "0.6.0",
-    "@wenyan-md/core": "^1.0.14"
+    "@wenyan-md/core": "^1.0.17"
   },
   "devDependencies": {
-    "@types/node": "^20.11.24",
-    "typescript": "^5.3.3",
-    "vitest": "^3.2.3"
+    "@types/node": "^24.3.0",
+    "dotenv-cli": "^10.0.0",
+    "openai": "^6.16.0",
+    "typescript": "^5.9.2"
   },
   "scripts": {
     "build": "tsc",
-    "watch": "tsc --watch",
-    "inspector": "pnpm build && node ./run-inspector.js",
-    "test": "pnpx vitest run",
+    "inspector": "pnpm build && dotenv -e .env.test -- node ./run-inspector.js",
+    "test:list": "pnpm build && dotenv -e .env.test -- node ./test/list.js",
+    "test:publish": "pnpm build && dotenv -e .env.test -- node ./test/publish.js",
     "upgrade:core": "pnpm update @wenyan-md/core"
   }
 }