# 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](docs/tools.md)。

## 环境要求

- 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。安装完成后，仓库可以移动或删除，不影响新会话使用。

```bash
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 会话，然后验证：

```bash
codex mcp get halo-docs
```

升级已有安装：

```bash
git pull
python scripts/install_codex.py --replace
```

更多参数：

```bash
python scripts/install_codex.py --help
```

详细步骤、手动配置、升级与卸载见 [docs/installation.md](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`

示例：

```dotenv
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](docs/security.md)。

## 本地开发与验证

```bash
npm ci
npm run verify
```

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

```bash
# 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：

```bash
npm start
```

启动 HTTP：

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

## Docker

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

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

Windows PowerShell：

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

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

```bash
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 上下文均排除本地凭据和运行数据

## 项目结构

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

## 参与贡献

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

## 许可证

本项目使用 [MIT License](LICENSE)。