Hexo Blog Rag MCP

🚀 hexo-blog-rag-mcp

日本語 | 英語

ベクトル検索に基づくHexoブログのRAG（検索強化生成）MCPサーバーです。

💡 すぐに体験する：David's ブログ のMCPを追加したい場合は、https://luoluoqinghuan.cn/mcp から追加できます。

🚀 クイックスタート

Dockerによる迅速なデプロイ

公式イメージを使用して、1クリックで起動します。

docker run -d \
  -p 3000:3000 \
  -e HEXO_SOURCE_DIR=/data/blog \
  -e EMBEDDING_TYPE=simple \
  -v /path/to/your/hexo/blog/source/_posts:/data/blog \
  ghcr.io/richdavidmu/hexo-blog-rag-mcp:latest

イメージのアドレス：ghcr.io/richdavidmu/hexo-blog-rag-mcp:latest

/path/to/your/hexo/blog/source/_posts をあなたのHexoブログの source/_posts ディレクトリの実際のパスに置き換えてください。

あなたのHexoブログをLLMの専用の知識ベースに変換します。

このプロジェクトはMCP（Model Context Protocol）プロトコルを通じて、大規模言語モデルがあなたのHexoブログの内容に直接アクセスし、検索できるようにします。ClaudeやChatGPTなどのAIアシスタントと対話する際に、これらのアシスタントはあなたのブログ内の技術記事、学習ノート、経験談などの内容をリアルタイムに検索し、個人の知識ベースに基づいた正確な回答を提供します。

🎯 核心価値

• 📚 知識の再利用：長年にわたって蓄積されたブログ記事が眠ることなく、AIアシスタントの知識源となります。
• 🎓 個別化された回答：AIがあなたの技術スタックと経験に基づいてカスタマイズされた提案を提供します。
• ⚡ 即時検索：古い記事を手動で探す必要がなく、AIが自動的に関連する内容を見つけます。
• 🔒 プライバシーのコントロール：データはローカルに保存され、あなたが完全に知識ベースをコントロールできます。

💡 使用シーン

• 技術的な質問：AIにあなたのブログのテーマに関する質問をし、あなたの記事に基づいた回答を得ます。
• 知識の復習：過去に書いた技術的な解決策や方法をすばやく見つけます。
• 学習アシスタント：AIがあなたの学習ノートを組み合わせて個別化された学習提案を提供します。
• コンテンツ作成：既存の記事内容に基づいて、新しいブログ記事の作成を支援します。

🔗 動作原理

graph LR
    A[あなたのHexoブログ] --> B[RAG MCPサーバー]
    B --> C[ベクトルデータベース]
    D[Claude/ChatGPT] <--> B
    D --> E[ブログ内容に基づく回答]

1. インデックス作成フェーズ：あなたのHexoブログをスキャンし、記事内容をベクトルに変換して保存します。
2. 対話フェーズ：AIに質問すると、サーバーが関連する記事の断片を検索します。
3. 回答の強化：AIは検索された内容に基づき、コンテキストを考慮して正確な回答を提供します。

✨ 主な機能

• 🔍 ベクトルに基づくHexoブログの意味検索
• 🤖 複数のEmbeddingモデルのサポート（Simple、OpenAI、Qwen）
• 📊 ファイルハッシュに基づく増分インデックス
• 👀 リアルタイムのファイル監視と自動インデックス更新
• 📝 JSON形式の構造化ログ
• 🎯 検索類似度の閾値フィルタリング
• 🔧 カスタマイズ可能なツール説明によるAI呼び出しシーンの精密制御

環境変数の設定

必須設定

Embeddingモデルの設定

以下の3つのEmbedding方法から1つを選択してください。

1. Simple Embedding（デフォルト）

追加の設定は必要ありません。ハッシュに基づく簡単なベクトル化方法を使用します。

EMBEDDING_TYPE=simple

2. OpenAI Embedding

EMBEDDING_TYPE=openai
OPENAI_API_KEY=sk-xxxxxxxxxxxxx
OPENAI_EMBEDDING_MODEL=text-embedding-3-small  # オプション、デフォルト: text-embedding-3-small
OPENAI_BASE_URL=https://api.openai.com/v1      # オプション、カスタムエンドポイント用

サポートされるモデル：

• text-embedding-3-small (1536次元)
• text-embedding-3-large (3072次元)
• text-embedding-ada-002 (1536次元)

3. Qwen Embedding

EMBEDDING_TYPE=qwen
QWEN_API_KEY=sk-xxxxxxxxxxxxx
QWEN_EMBEDDING_MODEL=text-embedding-v3         # オプション、デフォルト: text-embedding-v3
QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1  # オプション

サポートされるモデル：

• text-embedding-v3 (1024次元)
• text-embedding-v2 (1536次元)

ツール説明の設定

AIアシスタントが特定のシーンでツールを呼び出すように、ツール説明をカスタマイズします。

使用シーンの例：

あなたのブログが特定の分野（フロントエンド、AI、ブロックチェーンなど）に特化している場合、カスタマイズされたツール説明を使用して、AIアシスタントが関連するテーマでのみ検索ツールを呼び出すように制限できます。これにより、関係のない質問での呼び出しを避けることができます。

# 例：フロントエンド技術ブログに限定
TOOL_SEARCH_BLOG_DESCRIPTION="フロントエンド技術ブログ内で内容を検索します。このブログはReact、Vue、TypeScript、フロントエンドエンジニアリングなどのテーマをカバーしています。ユーザーがフロントエンド関連の技術質問をする場合のみ使用してください。"

# 例：AI/MLブログに限定
TOOL_SEARCH_BLOG_DESCRIPTION="AIと機械学習ブログ内で検索します。ディープラーニング、LLM、プロンプトエンジニアリング、モデル微調整などの内容をカバーしています。AI/ML関連の質問の場合のみ呼び出してください。"

# 例：汎用ブログ（制限なし）
TOOL_SEARCH_BLOG_DESCRIPTION="ブログ内で関連する内容を検索します。"

オプション設定

📦 インストール

# 依存関係のインストール
pnpm install

# プロジェクトのビルド
pnpm run build

💻 使用例

開発環境

# .envファイルの作成
cp .env.example .env

# .envを編集して環境変数を設定する
# その後、サーバーを起動する
pnpm run dev

本番環境

# プロジェクトのビルド
pnpm run build

# サーバーの起動
pnpm run start

Dockerによるデプロイ

# イメージのビルド
docker build -t hexo-blog-rag-mcp .

# コンテナの実行
docker run -d \
  -p 3000:3000 \
  -e HEXO_SOURCE_DIR=/data/blog \
  -e EMBEDDING_TYPE=openai \
  -e OPENAI_API_KEY=sk-xxxxx \
  -v /path/to/hexo/blog:/data/blog \
  hexo-blog-rag-mcp

MCPツール

search_blog

Hexoブログ内で関連する内容を検索します。

パラメータ：

• query (文字列, 必須): 検索クエリ
• topK (数値, オプション): 返される結果の数（デフォルト: 5）
• threshold (数値, オプション): 類似度の閾値（デフォルト: 1.0）

例：

{
  "query": "Hexoをどのようにデプロイするか",
  "topK": 3,
  "threshold": 0.8
}

get_blog_context

質問に答えるためのブログ内容を取得します。

パラメータ：

• question (文字列, 必須): ユーザーの質問
• threshold (数値, オプション): 類似度の閾値（デフォルト: 1.0）

例：

{
  "question": "Hexoブログのパフォーマンスを最適化する最良の方法は何ですか？",
  "threshold": 0.7
}

MCPリソース

blog://all-posts

すべてのブログ記事のリストを取得します。

返される形式：JSON形式で、記事の総数と記事のタイトルのリストが含まれます。

blog://posts/{title}

指定された記事の完全な内容を取得します。

パラメータ：

• title: 記事のタイトル（Markdownファイル名、.md拡張子を除く）

返される形式：記事の完全なMarkdown内容。

ログ

ログは logs/ ディレクトリに保存されます。

• app-YYYY-MM-DD.log - アプリケーションログ
• error-YYYY-MM-DD.log - エラーログ

ログは日単位でローテーションされ、14日間保存されます。

動作原理

増分インデックス

システムはMD5ハッシュ値を使用してドキュメントの変更を追跡します。

1. 起動時に各Markdownファイルのハッシュ値を計算します。
2. データベースに保存されているハッシュ値と比較します。
3. 変更されたファイルのみを再度インデックス化します。
4. 削除されたファイルは自動的にインデックスから削除されます。

ファイル監視

ブログディレクトリの変更をリアルタイムで監視します。

• ファイルの追加：新しい記事を自動的にインデックス化します。
• ファイルの変更：古いチャンクを削除し、再度インデックス化します。
• ファイルの削除：ベクトルデータベースから削除します。

スマートツールの呼び出し

カスタマイズされたツール説明を使用して、以下のことが可能です。

1. スマート判断 - AIは質問に答える前に、ブログを検索する必要があるかどうかを判断します。
2. 無効な呼び出しの削減 - ブログのテーマと関係のない質問（天気、ニュースなど）には、検索ツールを呼び出しません。
3. 効率の向上 - 関連するテーマでのみブログ内容を検索し、API呼び出しと応答時間を節約します。

例：

• ❌ "今日の天気はどうですか？" - AIはブログ検索を呼び出しません。
• ❌ "詩を書いてください" - AIはブログ検索を呼び出しません。
• ✅ "babelを学ぶ" - AIはブログ検索を呼び出します。

プロジェクトのアーキテクチャ

hexo-blog-rag-mcp/
├── packages/rag-mcp-server/
│   ├── src/
│   │   ├── services/
│   │   │   └── embedding.ts       # Embeddingサービス (Simple/OpenAI/Qwen)
│   │   ├── storage/
│   │   │   └── vector-store.ts    # ベクトルデータベース操作
│   │   ├── loaders/
│   │   │   └── hexo-loader.ts     # Hexo Markdownファイルローダー
│   │   ├── utils/
│   │   │   ├── logger.ts          # Winstonログ
│   │   │   ├── splitter.ts        # テキスト分割
│   │   │   └── env.ts             # 環境変数
│   │   ├── mcp-server.ts          # MCPサーバーの核心
│   │   └── index.ts               # アプリケーションのエントリーポイント
│   └── logs/                      # ログファイル
└── .env                           # 設定ファイル

📄 ライセンス

Apache-2.0

貢献

貢献を歓迎します！いつでもPull Requestを提出してください。

サポート

問題が発生した場合や質問がある場合は、issueを提出 してください。