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"
      }
    }
  }
}

📝 配置說明：

💡 提示：

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個工具）

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

📎 附件管理（8個工具）

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

🤖 AI 寫作助手（10個 Prompts）

💻 使用示例

🌟 自然語言交互（推薦）

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

📚 詳細文檔

核心文檔

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. 📘 完整示例指南 - 所有示例的詳細文檔

按功能學習：

💡 使用提示

• 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 提供兩種不同的能力：

💡 實際工作流：

用戶: "幫我寫一篇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個）

完整 Prompts 列表（10個）

🤝 貢獻

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

貢獻方式

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！