Halo MCP Server

面向 Halo 2.x 的文档发布、检索与生命周期管理 MCP Server。它通过 Model Context Protocol（MCP）向 Codex 等客户端提供 24 个工具，并附带可全局安装的 halo-docs Skill。

主要能力

• 文章与页面：创建、读取、更新、发布、定时发布、下线、回收与恢复

• 内容安全：默认 PRIVATE、乐观并发控制、写后回读和快照验证

• 分类与标签：读取分类/标签，按需创建缺失项

• Markdown：带 front matter 的导入与导出，支持冲突策略

• 附件：上传后验证 Halo 返回的永久链接

• 全文检索：SQLite FTS 本地索引，支持增量同步和全量重建

• 两种传输：stdio（推荐用于 Codex）和 Streamable HTTP

• 跨平台安装：Windows、macOS、Linux；安装后新会话和任意工程均可使用

完整工具清单见 docs/tools.md。

Related MCP server: gramax-docportal-mcp

环境要求

• Halo 2.x（当前依赖 Halo API Client 2.20.21）

• Node.js 22 或更高版本

• npm

• Python 3.9 或更高版本（运行安装器）

• Codex CLI（使用一键全局安装时需要）

• 一个可访问目标 Halo 的个人访问令牌（PAT）

五分钟安装（推荐）

install_codex.py 会执行测试和构建，把独立 Server 安装到 ~/.codex/servers/halo-mcp-server，把 Skill 安装到 ~/.agents/skills/halo-docs，并注册用户级 Codex MCP。安装完成后，仓库可以移动或删除，不影响新会话使用。

git clone https://github.com/jaxhu1108/halo-mcp.git
cd halo-mcp
python scripts/install_codex.py

首次安装且默认环境文件不存在时，安装器会交互询问：

1. Halo 直连地址

2. Halo 公网地址（可选）

3. Halo PAT（隐藏输入，不会回显）

4. 默认内容所有者（可选）

5. 默认可见性（默认 PRIVATE）

安装完成后关闭并重新打开 Codex 会话，然后验证：

codex mcp get halo-docs

升级已有安装：

git pull
python scripts/install_codex.py --replace

更多参数：

python scripts/install_codex.py --help

详细步骤、手动配置、升级与卸载见 docs/installation.md。

环境文件

默认用户级环境文件：

• Windows：%USERPROFILE%\.config\halo-mcp\halo.env

• macOS/Linux：~/.config/halo-mcp/halo.env

也可通过 HALO_ENV_FILE 指向其他绝对路径。发现顺序为：

1. 进程环境变量

2. HALO_ENV_FILE

3. 当前目录 .env

4. ~/.config/halo-mcp/halo.env

示例：

HALO_BASE_URL=http://127.0.0.1:8090
HALO_PUBLIC_URL=https://halo.example.com
HALO_PAT=pat_xxx
HALO_DEFAULT_OWNER=admin
HALO_DEFAULT_VISIBILITY=PRIVATE
HALO_DB_PATH=./data/halo-search.sqlite
HALO_HTTP_HOST=127.0.0.1
HALO_HTTP_PORT=3210

请勿提交真实 .env、halo.env、PAT 或 SQLite 数据库。安全建议见 docs/security.md。

本地开发与验证

npm ci
npm run verify

检查 Halo 连接（不会输出 PAT）：

# PowerShell
$env:HALO_ENV_FILE="$HOME\.config\halo-mcp\halo.env"
npm run health

# macOS/Linux
HALO_ENV_FILE="$HOME/.config/halo-mcp/halo.env" npm run health

启动 stdio：

npm start

启动 HTTP：

npm run start:http
# MCP: http://127.0.0.1:3210/mcp
# 健康检查: http://127.0.0.1:3210/health

Docker

Docker 默认读取仓库根目录的 .env。先复制示例并填写真实配置：

cp .env.example .env
docker compose up -d --build

Windows PowerShell：

Copy-Item .env.example .env
docker compose up -d --build

如环境文件位于其他位置：

HALO_ENV_FILE=/absolute/path/to/halo.env docker compose up -d --build

Docker 模式提供 HTTP MCP：http://127.0.0.1:3210/mcp。不要把端口直接暴露到不可信网络。

安全默认值

• 新内容默认可见性为 PRIVATE

• 新文章和页面默认保持草稿，除非显式要求发布

• 更新支持 expectedVersion / expectedHeadSnapshot

• 所有写操作执行回读与 UTF-8、状态、版本和快照验证

• 仅提供可恢复的回收操作，不提供永久删除工具

• 配置输出对 PAT 脱敏

• Git 与 Docker 上下文均排除本地凭据和运行数据

项目结构

src/                    TypeScript Server 源码
tests/                  Vitest 测试
scripts/install_codex.py 跨平台 Codex 全局安装器
scripts/health-check.mjs Halo 鉴权健康检查
skills/halo-docs/       可安装 Skill
docs/                   中文安装、工具与安全文档
.github/workflows/       持续集成

参与贡献

请阅读 CONTRIBUTING.md。安全问题请按 SECURITY.md 私下报告，不要在公开 Issue 中提交凭据。

许可证

本项目使用 MIT License。