夏颜 MCP Server

「夏颜」是一款基于Python的Markdown排版美化工具，让你将Markdown一键发布至微信公众号草稿箱，并使用优雅的主题系统进行排版。本项目基于MCP（Model Context Protocol）协议，可与支持MCP的AI助手无缝集成。

功能特性

• 🔧 Python实现 - 使用纯Python编写，易于扩展和定制
• 🎨 多主题支持 - 内置8种精美主题，适配不同内容风格
• 📝 Markdown渲染 - 完整支持Markdown语法，包括代码高亮、表格、TOC等
• 🖼️ 图片自动上传 - 支持本地和网络图片自动上传
• 📱 微信公众号集成 - 直接发布到公众号草稿箱
• 🔌 MCP协议 - 基于模型上下文协议，可与AI助手无缝集成
• 📁 多媒体管理 - 支持临时/永久素材上传、管理和删除
• 🛠️ 丰富工具集 - 提供7个专业MCP工具，覆盖发布、管理全流程

主题预览

内置主题包括：

• 默认主题 - 简洁大方的默认样式
• Orange Heart - 温暖橙心主题
• Rainbow - 彩虹渐变主题
• Lapis - 青金石主题
• Pie - 优雅派主题
• Maize - 玉米黄主题
• Purple - 紫色主题
• 物理猫薄荷 - 清新自然主题

安装使用

环境要求

• Python 3.9+
• 微信公众号开发者权限
• MCP客户端（如Codebuddy、Claude Desktop等）

快速开始

# 克隆仓库
git clone https://github.com/herofox/xiayan-mcp.git
cd xiayan-mcp

# 安装依赖
pip install -r requirements.txt

# 配置环境变量
cp .env.example .env
# 编辑.env文件，填入微信公众号API凭证

# 启动服务
python run.py

开发环境设置

MCP配置

在你的MCP客户端配置文件中添加：

{
  "mcpServers": {
    "xiayan-mcp": {
      "name": "夏颜公众号助手",
      "command": "python",
      "args": ["path/to/xiayan-mcp/run.py"],
      "env": {
        "WECHAT_APP_ID": "your_wechat_app_id",
        "WECHAT_APP_SECRET": "your_wechat_app_secret"
      }
    }
  }
}

Codebuddy快速配置

如果你使用Codebuddy，可以直接使用以下配置：

{
  "mcpServers": {
    "xiayan-mcp": {
      "name": "夏颜公众号助手",
      "command": "python",
      "args": ["e:\\资料\\文颜公众号MCP\\xiayan-mcp\\run.py"],
      "env": {
        "WECHAT_APP_ID": "your_wechat_app_id",
        "WECHAT_APP_SECRET": "your_wechat_app_secret"
      }
    }
  }
}

环境变量

需要在环境中设置微信公众号的API凭证：

• WECHAT_APP_ID - 微信公众号App ID
• WECHAT_APP_SECRET - 微信公众号App Secret

文章格式

在Markdown文章开头添加frontmatter：

---
title: 你的文章标题
cover: /path/to/cover/image.jpg
---

# 正文内容

这里是你的文章正文内容...

MCP工具接口

xiayan-mcp 提供以下7个专业工具：

1. publish_article - 发布文章

将Markdown文章发布到微信公众号草稿箱，支持主题选择和高级选项。

参数：

• content（必需）：Markdown内容，支持frontmatter
• theme_id（可选）：主题ID，默认为default
• permanent_cover（可选）：封面是否使用永久素材，默认false
• author（可选）：作者名，默认为"Xiayan MCP"
• need_open_comment（可选）：是否开启评论，默认0
• only_fans_can_comment（可选）：是否仅粉丝可评论，默认0

2. list_themes - 列出主题

获取所有可用的主题信息。

3. upload_temp_media - 上传临时素材

上传临时媒体文件，有效期3天。

参数：

• media_path（必需）：媒体文件路径
• media_type（可选）：类型（image/voice/video/thumb），默认image

4. upload_permanent_material - 上传永久素材

上传永久素材到微信服务器。

参数：

• media_path（必需）：媒体文件路径
• media_type（可选）：类型（image/voice/video/thumb），默认image
• description（可选）：视频描述（视频素材必需）

5. upload_image_for_news - 上传图文图片

专门用于图文消息的图片上传，返回可用URL。

参数：

• image_path（必需）：图片文件路径

6. get_media_list - 获取素材列表

获取微信服务器上的媒体素材列表。

参数：

• media_type（可选）：媒体类型，默认image
• permanent（可选）：是否永久素材，默认true
• offset（可选）：分页起始位置，默认0
• count（可选）：获取数量（1-20），默认20

7. delete_permanent_material - 删除永久素材

删除指定的永久素材。

参数：

• media_id（必需）：要删除的素材media_id

使用示例

基础文章发布

请使用xiayan-mcp帮我发布一篇文章到微信公众号草稿箱：

---
title: 测试文章
cover: https://example.com/cover.jpg
---

# 这是测试文章

这是一篇使用xiayan-mcp发布的测试文章，使用了default主题。

## 功能介绍

- Markdown排版
- 多主题支持
- 自动图片上传
- 微信公众号发布

主题ID请使用：default

多媒体操作

请帮我：
1. 上传一张临时图片：/path/to/image.jpg
2. 获取图片素材列表
3. 使用orangeheart主题发布一篇文章

高级发布选项

发布文章到微信公众号，要求：
- 使用purple主题
- 封面图片作为永久素材
- 开启评论功能
- 作者名为"我的名字"

内容：
---
title: 高级测试文章
cover: /path/to/cover.jpg
---

# 高级测试文章

这是测试高级功能的文章...

项目结构

xiayan-mcp/
├── src/                          # 源代码目录
│   └── xiayan_mcp/               # Python包
│       ├── __init__.py           # 包初始化
│       ├── server.py             # MCP服务器主入口
│       ├── core/                 # 核心功能模块
│       │   ├── __init__.py
│       │   ├── formatter.py      # Markdown格式化器
│       │   └── publisher.py      # 微信公众号发布器
│       └── themes/               # 主题系统
│           ├── __init__.py
│           └── theme_manager.py  # 主题管理器
├── tests/                        # 测试文件目录
├── data/                         # 数据目录
├── .env.example                  # 环境变量模板
├── .env                          # 实际环境变量配置
├── pyproject.toml               # Python项目配置
├── requirements.txt             # 依赖包列表
├── run.py                       # 主启动脚本
├── mcp_server.py                # MCP服务器脚本
├── fixed_run.py                 # 修复版启动脚本
└── README.md                    # 项目说明文档

开发

# 克隆仓库
git clone https://github.com/herofox2024/xiayan-mcp.git
cd xiayan-mcp

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest

# 代码格式化
black src/
ruff check src/

添加新主题

1. 在themes/theme_manager.py中添加新主题
2. 定义对应的CSS样式
3. 更新主题列表

# 示例：添加新主题
"my_theme": Theme(
    id="my_theme",
    name="我的主题",
    description="自定义主题描述",
    template=self._get_default_template(),
    css_styles=self._get_my_theme_css()
)

微信公众号配置

1. 登录微信公众平台
2. 获取App ID和App Secret
3. 配置服务器IP白名单
4. 设置开发者权限

详细配置参考：微信公众平台开发文档

故障排除

常见问题

1. Access Token获取失败

   • 检查App ID和App Secret是否正确
   • 确认服务器IP在白名单中
   • 验证.env文件配置

2. 图片上传失败

   • 检查图片路径是否正确
   • 确认图片格式支持（jpg、png等）
   • 检查图片大小限制（微信API限制）

3. 主题不生效

   • 检查theme_id是否正确
   • 确认CSS语法无误
   • 验证主题文件是否存在

4. MCP连接失败

   • 检查Python路径和命令参数
   • 确认环境变量设置正确
   • 验证MCP客户端配置
   • 检查端口占用情况

5. 导入模块错误

   • 设置PYTHONPATH：export PYTHONPATH=$PYTHONPATH:./src
   • 或使用启动脚本：python run.py
   • 检查虚拟环境是否正确激活

6. 编码问题

   • 使用修复版本：python fixed_run.py
   • 运行诊断脚本：python diagnose.py

调试模式

启用详细日志：

# 设置调试模式
export DEBUG=True

# 启动服务
python run.py

# 或使用更详细的日志
python -c "import logging; logging.basicConfig(level=logging.DEBUG)" run.py

测试工具

项目提供多个诊断脚本：

• diagnose.py - 全面诊断工具
• simple_diagnose.py - 简化诊断
• analyze_encoding.py - 编码分析
• debug_conversion.py - 调试转换

贡献

欢迎提交Issue和Pull Request！

开发流程

1. Fork 项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

代码规范

# 安装开发依赖
pip install -e ".[dev]"

# 代码格式化
black src/

# 代码检查
ruff check src/

# 类型检查
mypy src/

# 运行测试
pytest tests/

启动方式

xiayan-mcp支持多种启动方式：

1. 基础启动：python run.py
2. 包管理启动：xiayan-mcp（需先安装 pip install -e .）
3. 模块启动：python -m xiayan_mcp.server
4. 修复启动：python fixed_run.py（解决编码问题）
5. MCP服务器启动：python mcp_server.py

测试文件

所有测试文件已整理到 tests/ 目录中，包含：

• Python测试脚本（test_*.py）
• Markdown测试文档（test_*.md）
• 测试数据文件

许可证

本项目采用 Apache License 2.0 许可证。详情请见 LICENSE 文件。

更新日志

v0.1.0

• ✨ 新增完整的微信公众号多媒体上传功能
• 🎨 支持8种精美主题（default, orangeheart, rainbow, lapis, pie, maize, purple, phycat）
• 🔧 提供7个专业MCP工具
• 📱 完善的文档和示例
• 🛠️ 支持临时/永久素材管理
• 🔍 提供多种诊断和调试工具
• 🧪 完整的测试套件（tests/目录）

致谢

感谢以下开源项目的启发和支持：

• 文颜 wenyan-mcp - 原始TypeScript实现
• MCP SDK - 模型上下文协议
• Python-Markdown - Markdown解析库

联系方式

• 项目主页: https://github.com/herofox2024/xiayan-mcp
• 问题反馈: https://github.com/herofox2024/xiayan-mcp/issues
• 邮箱: 42845734@qq.com

---

⭐ 如果这个项目对你有帮助，请给我们一个Star！