Halo MCP Gateway

一个部署在 Cloudflare Workers 上的 Halo MCP 服务，把 Halo 的 标签、分类、文章整理成严格的 12 个 CRUD 工具，供 ChatGPT 等 MCP 客户端直接调用。

3 类资源 × 4 个动作 = 12 个 MCP Tools

项目通过 Halo Personal Access Token（PAT）调用 Halo API，并使用高强度随机路径密钥保护远程 MCP Endpoint。PAT 和随机密钥都只保存在 Cloudflare Worker Secrets 中。

功能

标签 Tag

Tool	作用
halo_create_tag	创建标签
halo_query_tags	查询单个标签或分页查询标签列表
halo_update_tag	修改标签
halo_delete_tag	删除标签

分类 Category

Tool	作用
halo_create_category	创建分类
halo_query_categories	查询单个分类或分页查询分类列表
halo_update_category	修改分类
halo_delete_category	删除分类

文章 Article

Tool	作用
halo_create_article	创建 Markdown 文章，可直接发布或保存草稿
halo_query_articles	查询单篇文章或分页/关键词查询文章
halo_update_article	修改标题、Markdown、分类、标签、发布状态等
halo_delete_article	默认移入回收站，可显式确认永久删除

所有工具均提供 MCP inputSchema、outputSchema 和 structuredContent。

工作方式

flowchart LR
    A[ChatGPT / MCP Client] -->|/mcp/随机密钥| B[Cloudflare Worker]
    B -->|Bearer HALO_PAT| C[Halo REST API]

安全模型：

• HALO_PAT 不发送给 ChatGPT
• MCP_GATEWAY_KEY 不写入源码或 wrangler.toml
• 错误随机密钥直接返回 404 Not Found
• 文章删除默认进入回收站，降低 AI 误删除风险

资源行为

标签 / 分类默认名称

创建标签或分类时，如果没有手动提供 slug，Worker 会将显示名称转换成无声调小写拼音，并使用 - 分隔。

例如：

人工智能
→ slug: ren-gong-zhi-neng
→ metadata.generateName: ren-gong-zhi-neng-

技术分享
→ slug: ji-shu-fen-xiang
→ metadata.generateName: ji-shu-fen-xiang-

如果显式传入 slug，则优先使用传入值。

查询工具

三个 Query 工具都支持两种模式：

• 传 name：按 Halo metadata.name 查询单个资源
• 不传 name：查询列表

这样无需额外拆分 get/list/search，始终保持 12 个 MCP 工具。

文章创建与更新

文章正文使用 Markdown。创建文章时：

{
  "publish": true
}

表示创建后立即发布；publish=false 则保存为草稿。

文章更新采用部分更新，只修改调用参数中显式提供的字段，可更新：

• 标题
• Markdown 正文
• slug
• 摘要
• 封面
• 标签
• 分类
• 评论开关
• 置顶/优先级
• 可见性
• 发布状态

文章中的标签和分类必须已经存在；建议让 AI 先查询，不存在时再调用对应 Create 工具。

删除安全

标签和分类删除是永久操作。

文章删除默认只进入 Halo 回收站：

{
  "name": "post-xxx"
}

永久删除必须明确传入双重确认：

{
  "name": "post-xxx",
  "permanent": true,
  "confirm_permanent": true
}

前置条件

你需要：

• Halo 2.x 站点
• 一个拥有对应文章/标签/分类权限的 Halo PAT
• Cloudflare 账号
• Node.js 20+
• 支持远程 MCP / Streamable HTTP 的客户端，例如 ChatGPT Developer Mode

操作流程

1. 克隆仓库

git clone https://github.com/wangling-miao/halo-mcp.git
cd halo-mcp

2. 安装依赖

npm install
npm run typecheck

项目使用：

• marked：Markdown → HTML
• pinyin-pro：标签/分类默认拼音 slug

国内 npm 网络不稳定时可以临时切换镜像：

npm config set registry https://registry.npmmirror.com
npm install

3. 配置 Halo 地址

编辑 wrangler.toml：

[vars]
HALO_BASE_URL = "https://your-halo.example.com"
HALO_TIMEOUT_MS = "30000"
MCP_ALLOWED_ORIGINS = "https://chatgpt.com,https://chat.openai.com"

不要把 PAT 写进 wrangler.toml。

4. 创建 Halo PAT

在 Halo 后台创建 Personal Access Token，并确保它拥有文章、分类、标签所需的读写权限。

PAT 只需要放进 Cloudflare Secret。

5. 生成随机 MCP 密钥

python -c "import secrets; print(secrets.token_urlsafe(32))"

6. 配置 Secrets

复制示例文件：

Copy-Item .env.production.example .env.production

编辑：

HALO_PAT=pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
MCP_GATEWAY_KEY=你的高强度随机密钥

也可以逐项写入 Cloudflare：

npx wrangler@latest secret put HALO_PAT
npx wrangler@latest secret put MCP_GATEWAY_KEY

.env.production 不要提交到 Git。

7. 部署到 Cloudflare Workers

npx wrangler@latest login
npx wrangler@latest deploy --secrets-file .env.production

部署后会得到类似：

https://halo-mcp-gateway.<account>.workers.dev

真正的 MCP Endpoint 是：

https://halo-mcp-gateway.<account>.workers.dev/mcp/<MCP_GATEWAY_KEY>

8. 接入 ChatGPT

在 ChatGPT 中：

1. 打开 Developer Mode / 自定义 MCP
2. 添加远程 MCP
3. Transport 选择 Streamable HTTP / Streaming HTTP
4. Authentication 选择 No Authentication
5. Endpoint 填写 /mcp/<MCP_GATEWAY_KEY> 完整地址
6. Scan / Refresh Tools

No Authentication 不代表接口公开：随机路径本身就是网关认证密钥，Halo PAT 仍由 Worker 私下保存和注入。

9. 测试

.\scripts\test.ps1 `
  -BaseUrl "https://halo-mcp-gateway.<account>.workers.dev" `
  -GatewayKey "你的MCP_GATEWAY_KEY"

脚本会检查：

• /health
• MCP initialize
• notifications/initialized
• tools/list
• 工具数量是否严格为 12

要实际调用 Halo 只读 API：

.\scripts\test.ps1 `
  -BaseUrl "https://halo-mcp-gateway.<account>.workers.dev" `
  -GatewayKey "你的MCP_GATEWAY_KEY" `
  -CallHaloRead

Halo API 路径

标签与分类使用 Halo Extension API：

GET/POST       /apis/content.halo.run/v1alpha1/tags
GET/PUT/DELETE /apis/content.halo.run/v1alpha1/tags/{name}

GET/POST       /apis/content.halo.run/v1alpha1/categories
GET/PUT/DELETE /apis/content.halo.run/v1alpha1/categories/{name}

文章主要使用 User Center API，以保留 Halo 的草稿、发布和回收站流程：

POST /apis/uc.api.content.halo.run/v1alpha1/posts
GET  /apis/uc.api.content.halo.run/v1alpha1/posts
GET  /apis/uc.api.content.halo.run/v1alpha1/posts/{name}
PUT  /apis/uc.api.content.halo.run/v1alpha1/posts/{name}
GET  /apis/uc.api.content.halo.run/v1alpha1/posts/{name}/draft?patched=true
PUT  /apis/uc.api.content.halo.run/v1alpha1/posts/{name}/draft
PUT  /apis/uc.api.content.halo.run/v1alpha1/posts/{name}/publish
PUT  /apis/uc.api.content.halo.run/v1alpha1/posts/{name}/unpublish
DELETE /apis/uc.api.content.halo.run/v1alpha1/posts/{name}/recycle

只有显式永久删除时才直接删除底层 Post。

常见问题

Wrangler 报 Could not resolve "marked"

说明依赖尚未安装。执行：

npm install
npm ls marked

再部署即可，不需要设置 Wrangler alias。

ChatGPT 仍显示旧工具

修改工具定义或重新部署后，在 ChatGPT 中重新执行 Scan / Refresh Tools。

PAT 返回 401 / 403

检查：

• PAT 是否仍有效
• PAT 用户是否具有文章、分类、标签读写权限
• HALO_BASE_URL 是否指向正确站点

创建文章时找不到分类或标签

先调用：

halo_query_categories
halo_query_tags

不存在则调用对应 Create 工具创建，再创建/更新文章。

安全建议

• 使用至少 32 字节随机 MCP_GATEWAY_KEY
• PAT 遵循最小权限原则
• 不要提交 .env.production
• 泄露 MCP URL 后应立即更换随机密钥
• 生产环境建议保留文章默认“回收站删除”策略

项目结构

.
├── src/
│   └── index.ts             # MCP Server 与 Halo API 实现
├── scripts/
│   └── test.ps1             # 部署后测试
├── wrangler.toml            # Cloudflare Worker 配置
├── .env.production.example  # Secret 示例
├── package.json
└── tsconfig.json

License

当前仓库未附加开源许可证；如需二次分发，请先确认授权方式。