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

📝 設定の説明：

💡 ヒント：

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個のプロンプト）

💻 使用例

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

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

📚 ドキュメント

核心ドキュメント

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

🔧 技術詳細

環境変数

.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個）

完全な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

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

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

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