# 博客园 MCP 服务

[![MCP Server](https://img.shields.io/badge/MCP%20Server-博客园-blue.svg)](https://modelcontextprotocol.io)
[![Python](https://img.shields.io/badge/Python-3.10+-green.svg)](https://www.python.org)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

通过 [MCP（Model Context Protocol）](https://modelcontextprotocol.io) 协议，将博客园 Open API 封装为 AI 可调用的工具。让你在 **任何 MCP 客户端**（QwenPaw、Claude Desktop、Cline 等）中直接用自然语言发布博客园文章。

---

## 功能

- ✅ `create_post` — 发布 Markdown 博文到博客园
- ✅ Token 通过 `.env` 管理，不含硬编码
- ✅ 支持任何 MCP 客户端接入

---

## 目录

- [快速开始](#快速开始)
- [获取 Token](#获取-token)
- [客户端接入](#客户端接入)
  - [QwenPaw](#1-qwenpaw)
  - [Claude Desktop](#2-claude-desktop)
  - [Cline / Roo Code](#3-cline--roo-code)
  - [其他 MCP 客户端](#4-其他-mcp-客户端)
- [手动测试](#手动测试)
- [错误处理](#错误处理)
- [API 参考](#api-参考)

---

## 快速开始

### 1. 克隆 / 下载项目

```bash
git clone https://github.com/你的用户名/cnblogs-mcp.git
cd cnblogs-mcp
```

### 2. 创建虚拟环境

```bash
python -m venv .venv
source .venv/bin/activate      # macOS / Linux
# .venv\Scripts\activate       # Windows
```

### 3. 安装依赖

```bash
pip install -r requirements.txt
```

### 4. 配置 Token

```bash
cp .env.example .env
```

编辑 `.env`，填入你的博客园 Personal Access Token：

```
CNBLOGS_TOKEN=your_token_here
```

### 5. 运行测试

```bash
# 验证 MCP 服务能正常启动
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}\n{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}\n' \
  | python cnblogs_mcp.py 2>/dev/null | grep '"name"'
```

正常输出：

```json
{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"create_post",...}]}}
```

---

## 获取 Token

1. 登录 [博客园](https://www.cnblogs.com)
2. 进入 [个人设置 → 安全设置 → Personal Access Token](https://account.cnblogs.com/settings/tokens)
3. 点击「创建 Token」，填写名称和权限（需要「发表随笔」权限）
4. 复制生成的 Token，填入 `.env` 文件

> ⚠️ Token 仅显示一次，请妥善保存。

---

## 客户端接入

### 1. QwenPaw

在 QwenPaw 工作目录下找到 `agent.json`，添加 MCP 客户端：

```json
{
  "mcp": {
    "clients": {
      "cnblogs": {
        "name": "cnblogs",
        "description": "博客园博文发布",
        "enabled": true,
        "transport": "stdio",
        "command": "/absolute/path/to/cnblogs-mcp/.venv/bin/python",
        "args": ["/absolute/path/to/cnblogs-mcp/cnblogs_mcp.py"],
        "env": {
          "DOTENV_PATH": "/absolute/path/to/cnblogs-mcp/.env"
        }
      }
    }
  }
}
```

重启 QwenPaw：

```bash
qwenpaw daemon restart
```

### 2. Claude Desktop

在 `~/Library/Application Support/Claude/claude_desktop_config.json` 中添加：

```json
{
  "mcpServers": {
    "cnblogs": {
      "command": "/absolute/path/to/cnblogs-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/cnblogs-mcp/cnblogs_mcp.py"],
      "env": {
        "DOTENV_PATH": "/absolute/path/to/cnblogs-mcp/.env"
      }
    }
  }
}
```

重启 Claude Desktop。

### 3. Cline / Roo Code

在 VS Code 设置中搜索「MCP」，找到 `MCP Servers`，添加：

```json
{
  "cnblogs": {
    "command": "/absolute/path/to/cnblogs-mcp/.venv/bin/python",
    "args": ["/absolute/path/to/cnblogs-mcp/cnblogs_mcp.py"],
    "env": {
      "DOTENV_PATH": "/absolute/path/to/cnblogs-mcp/.env"
    }
  }
}
```

### 4. 其他 MCP 客户端

通用配置模板：

| 参数 | 值 |
|------|-----|
| `command` | `.venv/bin/python`（项目内虚拟环境的 Python） |
| `args` | `["./cnblogs_mcp.py"]` |
| `env.DOTENV_PATH` | `.env` 文件的绝对路径 |

> 💡 如果 MCP 客户端不支持 `DOTENV_PATH`，也可以直接用 `env.CNBLOGS_TOKEN` 传入 token。

---

## 手动测试

```bash
cd cnblogs-mcp

# 测试 1：初始化 + 工具列表
printf '...' | python cnblogs_mcp.py

# 测试 2：发布一篇博文
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}\n{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"create_post","arguments":{"title":"测试","body":"## 你好\n\n这是一篇测试文章。"}}}\n' | python cnblogs_mcp.py 2>/dev/null
```

正常返回：

```json
{"success": true, "postId": 12345678, "postUrl": "https://www.cnblogs.com/你的博客名/p/12345678"}
```

---

## 错误处理

| 错误信息 | 原因 | 解决方案 |
|---------|------|---------|
| `未配置 CNBLOGS_TOKEN` | `.env` 未配置或路径错误 | 检查 `.env` 文件是否存在且 `DOTENV_PATH` 正确 |
| `API 错误: 401` | Token 无效或已过期 | 重新在博客园创建 Token |
| `API 错误: 403` | Token 权限不足 | 创建 Token 时确保勾选「发表随笔」 |
| `API 错误: 400` | 请求格式有误 | 检查 title 和 body 是否为空 |
| `请求超时` | 网络问题 | 检查网络后重试 |
| MCP 连接后工具列表为空 | `show_banner` 问题 | 确保使用 `mcp.run(show_banner=False)` |

---

## API 参考

### 工具：create_post

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `title` | string | ✅ | 博文标题 |
| `body` | string | ✅ | 博文正文（Markdown 格式） |
| `tags` | array | ❌ | 博文标签（1-5个字符串数组），默认 `["AI随笔"]` |

**返回值：**

```json
{
  "success": true,
  "postId": 19246558,
  "postUrl": "https://www.cnblogs.com/你的博客名/p/19246558"
}
```

或错误时：

```json
{
  "success": false,
  "error": "错误描述"
}
```

---

## 开发

### 项目结构

```
cnblogs-mcp/
├── cnblogs_mcp.py     # MCP 服务主文件
├── requirements.txt   # Python 依赖
├── .env.example       # 环境变量模板（不含真实 Token）
├── .env               # 你的本地配置（已在 .gitignore 中）
├── .gitignore
├── README.md
└── LICENSE
```

### 依赖

```
fastmcp>=3.0.0
python-dotenv>=1.0.0
requests>=2.31.0
```

---

## License

MIT — 欢迎 Star、 Fork 和 PR！