Halo MCP Server

🚀 Halo MCP Server

Halo MCP Server 是一個基於 Python 的 MCP 服務器，通過 MCP 將 Halo 博客系統與 AI 助手（如 Claude、Cursor、Qoder、Trae等）無縫集成，為 AI 助手提供完整的 Halo 博客管理能力。你可以通過自然語言對話，輕鬆完成文章創建、編輯、發佈等所有博客管理操作，並利用 AI 的強大能力進行智能寫作、內容優化和 SEO 提升。

🚀 快速開始

📋 前置要求

1. Python 3.10 或更高版本

python --version  # 確認版本 >= 3.10

2. 運行中的 Halo 博客系統
   • Halo 2.21 或更高版本
   • 記錄服務器地址（如 http://localhost:8091 或 https://yourdomain.com）
3. Claude Desktop 或其他 MCP 兼容客戶端
   • 下載地址：Claude Desktop

📦 安裝

方式一：從源碼安裝（開發）

# 1. 克隆或下載項目
git clone https://github.com/Huangwh826/halo-mcp-server.git
cd halo-mcp-server

# 2. 創建虛擬環境（推薦）
python -m venv venv

# 3. 激活虛擬環境
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# 4. 安裝項目（可編輯模式）
pip install -e .

方式二：使用 pip 安裝（推薦）

pip install halo-mcp-server

🔧 配置

步驟 1: 獲取 Halo 訪問令牌

1. 登錄 Halo 後臺管理系統
2. 進入 個人中心 → 個人令牌
3. 點擊 生成新令牌
4. 設置令牌名稱（如 "MCP Server"）
5. 選擇權限（建議勾選所有內容管理權限）
6. 保存並複製生成的令牌（僅顯示一次）

步驟 2: 配置 Claude Desktop

找到並編輯 Claude Desktop 配置文件： 文件位置：

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

配置內容：

{
  "mcpServers": {
    "halo-mcp-server": {
      "command": "python",
      "args": [
        "-m",
        "halo_mcp_server"
      ],
      "env": {
        "HALO_BASE_URL": "your_halo_base_url_here",
        "HALO_TOKEN": "your_halo_token_here"
      }
    }
  }
}

📝 配置說明：

配置項	說明	示例
command	Python 解釋器路徑	python 或 C:\\Python310\\python.exe
HALO_BASE_URL	Halo 服務器地址	http://localhost:8091 或 https://blog.example.com
HALO_TOKEN	API 訪問令牌	從 Halo 後臺獲取的令牌

💡 提示：

1. 使用虛擬環境時，將 command 指向虛擬環境的 Python：

"command": "D:\\Project\\halo-mcp\\venv\\Scripts\\python.exe"

2. 查找 Python 路徑：

# Windows
where python

# macOS/Linux
which python

3. 遠程 Halo 服務，確保使用完整 URL（包含 http:// 或 https://）

步驟 3: 重啟 Claude Desktop

完全關閉並重新啟動 Claude Desktop 以加載新配置。

✅ 驗證安裝

在 Claude Desktop 中輸入以下測試命令：

請列出我的所有博客文章

預期結果：

• Claude 會調用 Halo MCP Server
• 返回你的文章列表
• 如果沒有文章，會提示"暫無文章"

成功標誌：

• ✅ 沒有報錯
• ✅ 返回了文章列表或提示信息
• ✅ Claude 理解了"列出文章"的指令

✨ 主要特性

📝 文章管理（9個工具）

操作類型	具體操作
基礎操作	- ✅ 創建文章（支持 Markdown） - ✅ 編輯文章（標題、內容、設置） - ✅ 發佈/取消發佈文章 - ✅ 刪除文章（回收站） - ✅ 列出我的文章（分頁、篩選）
高級功能	- ✅ 草稿管理（查看、編輯草稿） - ✅ 分類和標籤管理 - ✅ 文章置頂/取消置頂 - ✅ 設置封面圖片 - ✅ 自定義 URL 別名

🏷️ 分類標籤（13個工具）

管理類型	具體操作
分類管理（6個）	- ✅ 列出所有分類 - ✅ 創建分類（支持層級結構） - ✅ 更新分類（名稱、描述、封面） - ✅ 刪除分類 - ✅ 獲取分類詳情 - ✅ 查看分類下的文章
標籤管理（7個）	- ✅ 列出所有標籤 - ✅ 創建標籤（支持顏色） - ✅ 更新標籤（名稱、顏色） - ✅ 刪除標籤 - ✅ 獲取標籤詳情 - ✅ 查看標籤下的文章 - ✅ 控制檯標籤列表

📎 附件管理（8個工具）

• ✅ 列出附件（支持篩選）
• ✅ 上傳本地文件
• ✅ 從 URL 上傳
• ✅ 刪除附件
• ✅ 附件分組管理
• ✅ 查看附件詳情
• ✅ 創建附件分組
• ✅ 查看存儲策略

🤖 AI 寫作助手（10個 Prompts）

功能類型	具體功能
內容創作	- 🎨 博客寫作助手 - 生成高質量文章 - ✨ 內容優化器 - 提升可讀性和結構 - 🎯 SEO 優化器 - 提高搜索排名 - 📰 標題生成器 - 創作吸引人的標題 - 📋 摘要生成器 - 自動生成文章摘要
輔助功能	- 🏷️ 標籤建議器 - 智能推薦標籤 - 📂 分類建議器 - 推薦合適分類 - 🌐 內容翻譯器 - 多語言翻譯 - ✏️ 內容校對器 - 語法和拼寫檢查 - 📚 系列規劃器 - 規劃系列文章

💻 使用示例

🌟 自然語言交互（推薦）

Halo MCP Server 的最大優勢是支持自然語言對話，無需記憶複雜命令：

📝 文章創作

👤 用戶：幫我寫一篇關於 Python 異步編程的技術文章併發布

🤖 Claude：
好的！我來幫你創作這篇文章。

[自動觸發 halo_blog_writing_assistant Prompt]
→ 生成 2000 字專業文章
→ 推薦標籤：Python、異步編程、asyncio
→ 推薦分類：技術教程
→ 調用 create_post 創建文章
→ 調用 publish_post 發佈

✓ 文章《Python異步編程完全指南》已成功創建併發布！

🔍 文章管理

# 查看文章
請顯示我最近發佈的5篇文章

# 搜索文章
搜索標題包含"Python"的文章

# 編輯文章
把"Python教程"這篇文章的標題改為"Python入門指南"

# 刪除文章
刪除名為"test-post"的文章

✨ 內容優化

# 優化文章
請優化"Python教程"這篇文章，讓它更通俗易懂

# 生成標題
為這篇文章生成5個吸引人的標題

# SEO優化
幫這篇文章做SEO優化，關鍵詞是：Python、教程、入門

🏷️ 分類標籤

# 創建分類
創建一個名為"技術教程"的分類，描述是"各類技術教程文章"

# 創建標籤
創建標籤：Python、JavaScript、TypeScript，顏色設置為藍色

# 批量操作
為"Python教程"文章添加標籤：Python、編程、教程

📎 附件管理

# 上傳圖片
上傳這張圖片作為文章封面：https://example.com/image.jpg

# 查看附件
列出所有圖片附件

# 創建分組
創建一個名為"文章配圖"的附件分組

📚 完整工作流示例

場景：從零開始發佈一篇技術博客

👤 用戶：我想寫一篇關於 Docker 容器化的技術文章

🤖 Claude：
好的！我來幫你完成整個創作和發佈流程。

步驟1: 內容創作
[觸發 halo_blog_writing_assistant]
→ 生成完整文章（包含簡介、核心概念、實踐示例、總結）

步驟2: 標題優化
[觸發 halo_title_generator]
→ 提供5個標題選項供選擇

步驟3: SEO優化
[觸發 halo_seo_optimizer]
→ 優化關鍵詞佈局
→ 生成Meta描述

步驟4: 分類標籤
[觸發 halo_tag_suggester]
→ 推薦標籤：Docker、容器化、DevOps、雲原生
[觸發 halo_category_suggester]
→ 推薦分類：雲原生技術

步驟5: 創建併發布
[調用 create_post]
→ 創建文章
[調用 publish_post]
→ 發佈文章

✓ 完成！文章《Docker容器化實踐指南》已成功發佈
  - 字數：2000字
  - 標籤：Docker、容器化、DevOps、雲原生
  - 分類：雲原生技術
  - 文章鏈接：https://yourblog.com/posts/docker-guide

📚 詳細文檔

核心文檔

文檔	描述
快速開始	5分鐘快速上手指南
設計文檔	系統架構和設計理念
MCP Prompts 指南	10個寫作助手詳細說明
Prompts vs Tools	兩者區別和使用方法
使用示例	完整的使用示例集

API 文檔

文檔	描述
API 整理	Halo API 整理
Console API	Halo 控制檯 API
Public API	Halo 公開 API
UC API	Halo 用戶內容 API
Extension API	Halo 擴展 API

📖 示例代碼

💡 完整示例指南：查看 examples/README.md 獲取詳細的示例文檔和使用說明

📁 示例目錄結構

examples/
├── README.md                           # 📘 示例總覽和詳細指南
├── quick_start_example.md              # ⚡ 快速開始（必讀）
├── usage_examples.md                   # 📚 使用示例合集
├── category_management_examples.py     # 🏷️ 分類管理完整示例
├── tag_management_examples.py          # 🔖 標籤管理完整示例
├── attachment_management_examples.py   # 📎 附件管理完整示例
└── mcp_prompts_examples.py             # 🤖 AI寫作助手示例

🚀 快速開始

新手推薦路徑：

1. 📖 快速開始示例 - 5分鐘瞭解基本用法
2. 📚 使用示例合集 - 常見場景和最佳實踐
3. 📘 完整示例指南 - 所有示例的詳細文檔

按功能學習：

示例文件	功能	難度	說明
quick_start_example.md	快速入門	⭐	實際調用示例，展示基本用法
usage_examples.md	綜合示例	⭐⭐	涵蓋所有工具的使用場景
category_management_examples.py	分類管理	⭐⭐	279行完整代碼示例
tag_management_examples.py	標籤管理	⭐⭐	375行完整代碼示例
attachment_management_examples.py	附件管理	⭐⭐⭐	477行完整代碼示例
mcp_prompts_examples.py	AI寫作助手	⭐⭐⭐	341行Prompts使用示例

💡 使用提示

• Markdown 示例 (.md) - 適合閱讀和理解，包含詳細說明
• Python 示例 (.py) - 可直接運行的完整代碼，包含註釋
• 從簡到難 - 建議按上表順序學習，逐步掌握所有功能

運行 Python 示例：

# 1. 確保已配置環境變量
export HALO_BASE_URL="your_url"
export HALO_TOKEN="your_token"

# 2. 運行示例（以分類管理為例）
cd examples
python category_management_examples.py

🔧 技術細節

MCP Tools vs Prompts

Halo MCP Server 提供兩種不同的能力：

類型	Tools（工具）	Prompts（提示助手）	對比
數量	30 個	10 個	互補配合
用途	執行具體操作（CRUD）	生成內容指導	工具執行 提示生成
顯示	✅ 在工具列表中可見	❌ 後臺自動觸發	顯式 vs 隱式
調用	Claude 主動調用 API	根據意圖自動匹配	API vs 智能
示例	• create_post - 創建文章 • list_categories - 列出分類 • upload_attachment - 上傳附件	• 博客寫作助手 - 生成文章 • SEO優化器 - 優化內容 • 標籤建議器 - 推薦標籤	操作 vs 創作
觸發方式	明確的操作指令： "創建文章" "上傳圖片"	描述性需求： "寫一篇文章" "優化內容"	命令 vs 對話

💡 實際工作流：

用戶: "幫我寫一篇Python教程併發布"
     ↓
Prompts: halo_blog_writing_assistant → 生成文章內容
     ↓
Tools: create_post → 創建文章到 Halo
     ↓
Tools: publish_post → 發佈文章
     ↓
結果: ✓ 文章創建併發布成功

為什麼看不到 Prompts？

這是 MCP 的優秀設計：

• ✅ 用戶友好 - 無需記憶 Prompt 名稱
• ✅ 智能匹配 - AI 自動理解意圖並選擇合適的 Prompt
• ✅ 無感知 - 後臺自動工作，用戶只需描述需求
• ✅ 靈活性 - 可以用各種方式表達同一個需求

對比傳統方式：

# ❌ 傳統 CLI 方式
$ halo-cli create-post \
  --title "Python教程" \
  --content-file article.md \
  --tags "Python,教程" \
  --category "編程" \
  --publish

# ✅ MCP 方式（自然語言）
幫我寫一篇Python教程併發布

配置說明

環境變量

創建 .env 文件或在 Claude Desktop 配置中設置：

# ========== 必需配置 ==========
HALO_BASE_URL=http://localhost:8091    # Halo 服務器地址
HALO_TOKEN=your_token_here              # API 訪問令牌

# ========== 可選配置 ==========
MCP_LOG_LEVEL=INFO                      # 日誌級別: DEBUG, INFO, WARNING, ERROR
MCP_TIMEOUT=30                          # HTTP 請求超時（秒）

# ========== 功能開關 ==========
ENABLE_IMAGE_COMPRESSION=true           # 啟用圖片壓縮
IMAGE_MAX_WIDTH=1920                    # 壓縮後最大寬度（像素）
IMAGE_QUALITY=85                        # 圖片質量 (1-100)
MAX_UPLOAD_SIZE_MB=10                   # 最大上傳大小（MB）

# ========== 高級配置 ==========
HTTP_POOL_SIZE=10                       # HTTP 連接池大小
MAX_RETRIES=3                           # 請求重試次數
ENABLE_CACHE=true                       # 啟用緩存
CACHE_TTL=300                           # 緩存過期時間（秒）

完整配置說明請參考 .env.example

故障排除

常見問題

1. Claude 無法識別 Halo 工具

症狀： Claude 不響應博客管理命令 解決方案：

# 檢查配置文件
# Windows: %APPDATA%\Claude\claude_desktop_config.json
# macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

# 驗證配置格式（JSON必須正確）
# 確認 Python 路徑正確
# 重啟 Claude Desktop

2. 認證失敗

症狀： 報錯"Authentication failed"或"Invalid token" 解決方案：

1. 檢查 HALO_TOKEN 是否正確（無多餘空格）
2. 確認 Token 未過期
3. 驗證 HALO_BASE_URL 是否可訪問
4. 測試網絡連接：

curl http://localhost:8091/apis/api.console.halo.run/v1alpha1/posts

3. 模塊導入錯誤

症狀： "No module named 'halo-mcp-server'" 解決方案：

# 重新安裝
pip install -e .

# 驗證安裝
pip show halo-mcp-server

# 檢查 Python 路徑
python -c "import halo-mcp-server; print(halo_mcp_server.__version__)"

4. Prompts 不生效

症狀： AI 不能自動生成文章內容 說明： Prompts 是隱藏的，通過自然語言觸發 測試方法：

# ✅ 正確方式（會觸發寫作 Prompt）
幫我寫一篇關於Python的文章

# ❌ 錯誤理解（不需要這樣）
使用 halo_blog_writing_assistant 寫文章

調試方法

查看日誌

設置調試級別：

{
  "mcpServers": {
    "halo": {
      "env": {
        "MCP_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

日誌位置：

• Claude Desktop 日誌：幫助 → 開發者工具 → Console
• MCP 服務日誌：查看標準輸出

手動測試

測試認證：

# 使用 curl 測試
curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:8091/apis/uc.api.content.halo.run/v1alpha1/posts

測試 Python 模塊：

# 進入 Python 環境
python

# 導入並測試
>>> from halo_mcp_server.client import HaloClient
>>> import asyncio
>>> client = HaloClient()
>>> asyncio.run(client.authenticate())
>>> print("✓ 認證成功")

開發

開發環境設置

# 1. 克隆項目
git clone https://github.com/Huangwh826/halo_mcp_server.git
cd halo-mcp-server

# 2. 創建虛擬環境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 3. 安裝開發依賴
pip install -e ".[dev]"

# 4. 安裝 pre-commit hooks
pre-commit install

項目結構

halo-mcp-server/
├── src/halo-mcp-server/           # 源代碼
│   ├── __init__.py
│   ├── __main__.py         # 入口文件
│   ├── config.py           # 配置管理
│   ├── server.py           # MCP 服務器
│   ├── exceptions.py       # 異常定義
│   ├── client/             # Halo API 客戶端
│   │   ├── base.py
│   │   └── halo_client.py
│   ├── tools/              # MCP Tools
│   │   ├── post_tools.py
│   │   ├── category_tools.py
│   │   ├── tag_tools.py
│   │   └── attachment_tools.py
│   ├── prompts/            # MCP Prompts
│   │   └── blog_prompts.py
│   └── utils/              # 工具函數
│       └── logger.py
├── tests/                  # 單元測試
├── examples/               # 使用示例
├── halo_apis_docs/         # API 文檔
├── debug_tests/            # 調試腳本
├── pyproject.toml          # 項目配置
└── README.md               # 本文件

代碼規範

# 格式化代碼
black src/ tests/
isort src/ tests/

# 類型檢查
mypy src/

# 代碼檢查
ruff check src/ tests/

# 運行測試
pytest tests/ -v --cov=halo-mcp-server

添加新功能

1. 添加新 Tool：

# src/halo-mcp-server/tools/custom_tools.py
from mcp.types import Tool

async def my_custom_tool(client, arguments):
    """實現你的工具邏輯"""
    pass

MY_TOOLS = [
    Tool(
        name="my_tool",
        description="工具描述",
        inputSchema={...}
    )
]

2. 添加新 Prompt：

# src/halo-mcp-server/prompts/custom_prompts.py
from mcp.types import Prompt, PromptArgument

CUSTOM_PROMPTS = [
    Prompt(
        name="my_prompt",
        description="Prompt 描述",
        arguments=[...]
    )
]

3. 註冊到 Server：

# src/halo-mcp-server/server.py
from halo_mcp_server.tools.custom_tools import MY_TOOLS
from halo_mcp_server.prompts.custom_prompts import CUSTOM_PROMPTS

# 添加到對應列表
all_tools += MY_TOOLS
all_prompts += CUSTOM_PROMPTS

貢獻指南

歡迎貢獻！請查看 DEVELOPMENT.md 瞭解詳細信息。

測試

快速測試

項目提供了全面的測試套件，覆蓋所有 30 個 MCP 工具：

# 進入測試目錄
cd tests

# 運行綜合測試
python run_comprehensive_test.py

測試覆蓋

✅ 分類管理 (6個工具): create_category, list_categories, get_category, update_category, get_category_posts, delete_category ✅ 標籤管理 (7個工具): create_tag, list_tags, get_tag, update_tag, list_console_tags, get_tag_posts, delete_tag ✅ 附件管理 (8個工具): 上傳、列表、刪除、分組等 ✅ 文章管理 (9個工具): 創建、編輯、發佈、草稿等

測試詳情

查看 tests/README.md 瞭解：

• 📝 詳細的測試指南
• 🔧 環境配置說明
• 🐛 故障排除方法
• 📊 測試報告生成

功能對照表

完整工具列表（30個）

📝 文章管理工具（9個）

| 工具名稱 | 功能說明 | 調用示例 | | ---- | ---- | ---- | | `list_my_posts` | 列出我的文章 | "列出我的所有文章" | | `get_post` | 獲取文章詳情 | "顯示post-xxx的詳情" | | `create_post` | 創建文章 | "創建一篇文章" | | `update_post` | 更新文章 | "更新文章標題" | | `publish_post` | 發佈文章 | "發佈這篇文章" | | `unpublish_post` | 取消發佈 | "下線這篇文章" | | `delete_post` | 刪除文章 | "刪除這篇文章" | | `get_post_draft` | 獲取草稿 | "查看草稿內容" | | `update_post_draft` | 更新草稿 | "修改草稿" |

🏷️ 分類管理工具（6個）

| 工具名稱 | 功能說明 | 調用示例 | | ---- | ---- | ---- | | `list_categories` | 列出分類 | "列出所有分類" | | `get_category` | 獲取分類詳情 | "查看分類詳情" | | `create_category` | 創建分類 | "創建技術分類" | | `update_category` | 更新分類 | "修改分類名稱" | | `delete_category` | 刪除分類 | "刪除這個分類" | | `get_category_posts` | 獲取分類下文章 | "查看分類下的文章" |

🔖 標籤管理工具（7個）

| 工具名稱 | 功能說明 | 調用示例 | | ---- | ---- | ---- | | `list_tags` | 列出標籤 | "列出所有標籤" | | `get_tag` | 獲取標籤詳情 | "查看標籤詳情" | | `create_tag` | 創建標籤 | "創建Python標籤" | | `update_tag` | 更新標籤 | "修改標籤顏色" | | `delete_tag` | 刪除標籤 | "刪除這個標籤" | | `get_tag_posts` | 獲取標籤下文章 | "查看標籤下的文章" | | `list_console_tags` | 控制檯標籤列表 | "查看控制檯標籤" |

📎 附件管理工具（8個）

| 工具名稱 | 功能說明 | 調用示例 | | ---- | ---- | ---- | | `list_attachments` | 列出附件 | "列出所有附件" | | `get_attachment` | 獲取附件詳情 | "查看附件詳情" | | `upload_attachment` | 上傳文件 | "上傳這個文件" | | `upload_attachment_from_url` | 從URL上傳 | "從URL上傳圖片" | | `delete_attachment` | 刪除附件 | "刪除這個附件" | | `list_attachment_groups` | 列出附件分組 | "列出附件分組" | | `create_attachment_group` | 創建分組 | "創建圖片分組" | | `get_attachment_policies` | 獲取存儲策略 | "查看存儲策略" |

完整 Prompts 列表（10個）

🤖 AI 寫作助手詳細說明

| Prompt 名稱 | 功能說明 | 觸發示例 | 主要參數 | | ---- | ---- | ---- | ---- | | `halo_blog_writing_assistant` | 博客寫作助手 | "寫一篇Python文章" | topic, audience, type, word_count | | `halo_content_optimizer` | 內容優化器 | "優化這篇文章" | content, focus, length | | `halo_seo_optimizer` | SEO優化器 | "SEO優化" | title, content, keywords | | `halo_title_generator` | 標題生成器 | "生成5個標題" | content_summary, style, count | | `halo_excerpt_generator` | 摘要生成器 | "生成摘要" | content, length, style | | `halo_tag_suggester` | 標籤建議器 | "推薦標籤" | title, content, existing_tags | | `halo_category_suggester` | 分類建議器 | "推薦分類" | title, content, existing_categories | | `halo_content_translator` | 內容翻譯器 | "翻譯成英文" | content, target_language | | `halo_content_proofreader` | 內容校對器 | "校對文章" | content, language, focus | | `halo_series_planner` | 系列規劃器 | "規劃系列文章" | series_topic, audience, count |

🤝 貢獻

歡迎貢獻代碼、報告問題或提出建議！

貢獻方式

1. Fork 項目
2. 創建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 開啟 Pull Request

貢獻者

感謝所有為項目做出貢獻的開發者！

📄 許可證

本項目採用 MIT 許可證 - 詳見 LICENSE 文件

🙏 致謝

• Halo - 優秀的開源博客系統
• Model Context Protocol - 強大的 AI 集成協議
• Claude - 智能的 AI 助手
• 所有貢獻者和用戶

📞 聯繫我們

• 項目主頁: GitHub
• 問題反饋: Issues
• 文檔: Documentation

🎁 支持項目

如果這個項目對你有幫助，歡迎通過以下方式支持：

• ⭐ 給項目點個 Star
• 🐛 提交 Issue 或 PR
• 💬 分享給更多人
• ☕ 讚賞作者

⭐ 如果這個項目對你有幫助，請給它一個 Star！