Halo MCP Server

🚀 Halo MCP Server

MCPを介して、HaloブログシステムとClaude、Cursor、Qoder、TraeなどのAIアシスタントをシームレスに統合し、AIをブログ管理のアシスタントにしましょう。

🚀 クイックスタート

📋 前提条件

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：ソースコードからインストール（開発用）

# 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 .

方法2：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個のプロンプト）

機能種別	詳細
コンテンツ作成	- 🎨 ブログ執筆アシスタント - 高品質な記事を生成する - ✨ コンテンツ最適化ツール - 読みやすさと構造を向上させる - 🎯 SEO最適化ツール - 検索ランキングを向上させる - 📰 タイトル生成ツール - 魅力的なタイトルを作成する - 📋 要約生成ツール - 記事の要約を自動生成する
補助機能	- 🏷️ タグ推薦ツール - タグを自動推薦する - 📂 カテゴリ推薦ツール - 適切なカテゴリを推薦する - 🌐 コンテンツ翻訳ツール - 多言語翻訳を行う - ✏️ コンテンツ校正ツール - 文法とスペルチェックを行う - 📚 シリーズ計画ツール - シリーズ記事を計画する

💻 使用例

🌟 自然言語による対話（推奨）

Halo MCP Serverの最大の利点は、自然言語による対話をサポートしており、複雑なコマンドを覚える必要がないことです。

📝 記事作成

👤 ユーザー：帮我写一篇关于 Python 异步编程的技术文章并发布

🤖 Claude：
了解しました！この記事を作成します。

[自動的に halo_blog_writing_assistant プロンプトをトリガー]
→ 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行のプロンプト使用例

💡 使用ヒント

• 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

🔧 技術詳細

環境変数

.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. トークンが期限切れでないことを確認する
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は隠されており、自然言語でトリガーされます。

テスト方法：

# ✅ 正しい方法（執筆プロンプトをトリガーする）
帮我写一篇关于Python的文章

# ❌ 誤った理解（このような方法は必要ない）
使用 halo_blog_writing_assistant 写文章

デバッグ方法

ログを確認する

デバッグレベルを設定する：

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

ログの場所：

• Claude Desktopのログ：ヘルプ → 開発者ツール → コンソール
• 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. サーバーに登録する：

   # 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

🎁 プロジェクトをサポートする

このプロジェクトが役に立った場合、以下の方法でサポートすることができます。

• ⭐ プロジェクトにスターを付ける
• 🐛 IssueまたはPRを提出する
• 💬 他の人に共有する
• ☕ 作者に寄付する

---