flowchart TD
    A[Markdown 文本/本地文件] --> B[wechat-md-mcp 核心服务]
    B --> C[doocs/md 语法与版式解析]
    C --> D[Juice 样式深度内联]
    D --> E{使用场景}
    
    E -->|可视化编辑| F[Web 可视化编辑器<br/>390px 手机实时预览]
    F -->|格式调优| G[保存为默认配置<br/>.editor-state.json]
    G -.->|全局复用| B
    
    E -->|MCP Agent 模式| H[Agent 调用 open_editor<br/>弹出/嵌入侧栏供用户微调]
    H -->|用户确认后| I[copy_to_clipboard<br/>macOS 系统剪贴板]
    
    E -->|HTTP API 模式| J[POST /render 或 /load<br/>返回内联 HTML 或编辑器 URL]
    
    I --> K[微信公众号后台<br/>Cmd + V 完美粘贴]
    J --> K

# 1. 克隆本仓库（仓库自包含内核，无需额外安装 doocs/md）
git clone https://github.com/rookit-ljt/wechat-md-mcp.git
cd wechat-md-mcp

# 2. 安装依赖
npm install

# 3. 运行冒烟测试确认环境
npm test

# 4. 根据需要启动服务
npm start            # 启动 HTTP 服务与可视化编辑器，默认监听 http://127.0.0.1:8788
npm run mcp          # 以 stdio 模式运行 MCP 服务

npm start                      # 启动服务并在浏览器访问 http://127.0.0.1:8788/
# 也可以通过固定脚本一键启动并直接打开指定文章：
npm run editor -- /path/to/article.md
# 或直接运行：./scripts/open-sidebar.sh /path/to/article.md

{
  "mcpServers": {
    "wechat-md-mcp": {
      "command": "/path/to/wechat-md-mcp/bin/md-mcp",
      "args": []
    }
  }
}

claude mcp add wechat-md-mcp -- /path/to/wechat-md-mcp/bin/md-mcp

{
  "mcpServers": {
    "wechat-md-mcp": {
      "command": "/path/to/wechat-md-mcp/bin/md-mcp",
      "args": []
    }
  }
}

{
  "mcpServers": {
    "wechat-md-mcp": {
      "command": "/path/to/wechat-md-mcp/bin/md-mcp",
      "args": []
    }
  }
}

[mcp_servers.wechat-md-mcp]
command = "/path/to/wechat-md-mcp/bin/md-mcp"
args = []

{
  "mcpServers": {
    "wechat-md-mcp": {
      "command": "/path/to/wechat-md-mcp/bin/md-mcp",
      "args": []
    }
  }
}

npm run install:skill        # 自动软链到 Claude / Codex / Cursor / WorkBuddy 的 skills 目录
npm run uninstall:skill      # 卸载移除软链

npm start                      # 默认监听 127.0.0.1:8788（端口被占时自动顺延）
MD_SERVICE_PORT=9000 npm start # 自定义端口

curl -X POST http://127.0.0.1:8788/render \
  -H 'Content-Type: application/json' \
  -d '{
    "markdown": "# 标题\n\n正文内容，支持**加粗**与[超链接](https://example.com)。",
    "theme": "grace",
    "primaryColor": "#07C160"
  }'

curl -X POST http://127.0.0.1:8788/load \
  -H 'Content-Type: application/json' \
  -d '{"path":"/abs/path/to/article.md"}'

{
  "path": "/abs/path/to/article.md",
  "url": "http://127.0.0.1:8788/?path=%2Fabs%2Fpath%2Fto%2Farticle.md&from=agent",
  "port": 8788
}

wechat-md-mcp/
├── assets/
│   └── demo.gif          # 项目实操演示动图
├── bin/
│   └── md-mcp            # MCP 专用 Shell 启动器（自动探测环境与清理脏变量）
├── web/                  # 可视化编辑器（原生 HTML/CSS/JS，无需编译构建）
│   ├── index.html        # 三栏编辑界面骨架
│   ├── app.js            # 实时渲染、防抖、文件读写与状态管理
│   └── style.css         # 响应式布局样式（支持侧边栏窄屏适配）
├── docs/                 # 客户端接入指南、选型记录与设计文档
├── run-mcp.mjs           # MCP 服务入口
├── run-server.mjs        # HTTP 服务入口
├── polyfill.mjs          # Node.js 环境下模拟浏览器 DOM 的必要 Polyfill
├── src/
│   ├── clipboard.ts      # macOS 系统富文本剪贴板注入实现
│   ├── cssNormalize.ts   # 微信专用 CSS 归一化与变量预处理
│   ├── images.ts         # 本地图片相对路径扫描与预览转码
│   ├── mcp.ts            # MCP Server 与 6 大工具注册声明
│   ├── render.ts         # doocs/md 核心渲染管道与 Juice 内联调度
│   ├── server.ts         # HTTP 路由、静态文件托管与智能端口探测
│   └── state.ts          # .editor-state.json 格式配置状态持久化
├── skills/
│   └── wechat-md/        # 通用 Agent Skill（定义排版操作 SOP 与规则）
├── scripts/
│   ├── install-skill.sh  # Skill 多客户端一键软链/卸载脚本
│   └── open-sidebar.sh   # 一键自启服务并在侧边栏/浏览器打开文章的固定脚本
├── test/                 # 冒烟测试、代码块测试与排版预览构建脚本
└── vendor/
    └── doocs-md/         # 本地裁剪版 doocs/md 官方渲染引擎

npm test                                          # 运行冒烟与代码块渲染测试
npx tsx test/clipboard.ts                         # 测试剪贴板富文本写入（注意：会覆盖当前剪贴板）
npx tsx test/build-preview.ts input.md out.html grace # 生成手机宽度(375px)本地预览 HTML