# 🚀 Hexo Blog MCP Server

一个基于 [Model Context Protocol](https://modelcontextprotocol.io) 的 Hexo 博客管理服务器，让 AI 客户端（Claude Desktop、Cursor 等）能够直接管理你的 Hexo 博客。

## ✨ 功能特性

- 📝 **文章管理** — 列出、搜索、读取、创建、编辑、删除博客文章
- 👀 **本地预览** — 一键启动/停止 Hexo 本地预览服务器
- 🌐 **一键发布** — 构建并部署到 GitHub Pages
- 💾 **源码备份** — 自动 Git 提交并推送到 `hexo-source` 分支
- 🔒 **安全防护** — 路径沙盒、分支锁定、命令超时保护

## 📦 安装

```bash
# 克隆或进入项目目录
cd /Users/lizexi/Documents/AI/aiMcp/hexo-mcp-server

# 安装依赖
npm install

# 构建
npm run build
```

## ⚙️ MCP 客户端配置

在你的 AI 客户端中添加以下 MCP 配置：

### Claude Desktop

编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "hexo-blog": {
      "command": "node",
      "args": ["/Users/lizexi/Documents/AI/aiMcp/hexo-mcp-server/dist/index.js"],
      "env": {
        "BLOG_ROOT": "/Users/lizexi/Documents/code/leejersey.github.io"
      }
    }
  }
}
```

### Cursor

在 Cursor Settings → MCP 中添加相同配置。

## 🛠️ 可用的 Tools

### 文章管理

| 工具 | 参数 | 功能 |
|------|------|------|
| `list_posts` | `keyword?` | 列出所有文章，支持按关键词过滤标题和标签 |
| `search_posts` | `query` | 按关键词全文搜索文章（标题+正文） |
| `read_post` | `filename` | 读取指定文章的完整内容（含 Front-matter） |
| `create_post` | `title`, `content?`, `tags?` | 创建新文章并自动生成 Front-matter |
| `update_post` | `filename`, `content`, `title?`, `tags?` | 修改文章内容或元数据 |
| `delete_post` | `filename` | 删除指定文章 |

### 博客操作

| 工具 | 功能 |
|------|------|
| `preview_blog` | 执行 `hexo clean && hexo g && hexo s`，启动本地预览（localhost:4000） |
| `stop_preview` | 停止正在运行的预览服务器 |
| `deploy_blog` | 执行 `hexo clean && hexo g && hexo d`，发布到 GitHub Pages |

### Git 操作

| 工具 | 参数 | 功能 |
|------|------|------|
| `backup_source` | `message?` | Git add → commit → push 到 `hexo-source` 分支 |
| `quick_publish` | `message?` | 一键完成 deploy + backup 组合操作 |
| `git_status` | — | 查看当前工作区的 Git 状态 |

## 📚 可用的 Resources

| URI | 描述 |
|-----|------|
| `blog://config/site` | 站点配置 `_config.yml` 的内容 |
| `blog://config/theme` | Apollo 主题配置 `_config.apollo.yml` 的内容 |
| `blog://posts/summary` | 所有文章的元数据汇总（标题、日期、标签、字数） |

## 🏗️ 项目结构

```
src/
├── index.ts              # MCP 服务器入口
├── config.ts             # 路径与常量配置
├── tools/
│   ├── post-tools.ts     # 文章管理工具（6个）
│   ├── hexo-tools.ts     # 构建/预览/部署工具（3个）
│   └── git-tools.ts      # Git 操作工具（3个）
├── resources/
│   └── blog-resources.ts # 博客数据资源（3个）
└── utils/
    ├── post-manager.ts   # 文章文件操作核心逻辑
    ├── hexo-runner.ts    # shell/hexo 命令封装
    └── git-runner.ts     # git 命令封装
```

## 🔧 技术栈

- **TypeScript** + Node.js 18+
- **@modelcontextprotocol/sdk** — MCP 官方 SDK（stdio 传输）
- **zod** — 工具参数验证
- **gray-matter** — Hexo 文章 Front-matter 解析

## 📄 License

MIT