Hexo Blog Rag MCP

🚀 hexo-blog-rag-mcp

基於向量搜索的 Hexo 博客 RAG (檢索增強生成) MCP 服務器，能讓大語言模型直接訪問和搜索 Hexo 博客內容，為用戶提供基於個人知識庫的精準回答。

中文 | English

💡 快速體驗： 如果你想添加 David's 博客 的 MCP，可通過 https://luoluoqinghuan.cn/mcp 添加。

🚀 快速開始

Docker 快速部署

使用官方鏡像，一鍵啟動：

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 調用場景。

📦 安裝指南

# 安裝依賴
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 (string, 必需): 搜索查詢。
• topK (number, 可選): 返回結果數量（默認: 5）。
• threshold (number, 可選): 相似度閾值（默認: 1.0）。

示例：

{
  "query": "如何部署 Hexo",
  "topK": 3,
  "threshold": 0.8
}

get_blog_context

獲取博客內容用於回答問題。 參數：

• question (string, 必需): 用戶問題。
• threshold (number, 可選): 相似度閾值（默認: 1.0）。

示例：

{
  "question": "優化 Hexo 博客性能的最佳方法是什麼？",
  "threshold": 0.7
}

MCP Resources

blog://all-posts

獲取所有博客文章列表。 返回格式： JSON，包含文章總數和文章標題列表。

blog://posts/{title}

獲取指定文章的完整內容。 參數：

• title: 文章標題（Markdown 文件名，不含 .md 擴展名）。 返回格式： 文章的完整 Markdown 內容。

日誌

日誌存儲在 logs/ 目錄中：

• app-YYYY-MM-DD.log - 應用日誌。
• error-YYYY-MM-DD.log - 錯誤日誌。

日誌按天輪轉，保留 14 天。

環境變量配置

必需配置

Embedding 模型配置

選擇以下三種 Embedding 方法之一：

1. Simple Embedding（默認）

無需額外配置，使用基於哈希的簡單向量化方法。

EMBEDDING_TYPE=simple

2. OpenAI Embedding

EMBEDDING_TYPE=openai
OPENAI_API_KEY=sk-xxxxxxxxxxxxx
OPENAI_EMBEDDING_MODEL=text-embedding-3-small  # Optional, default: text-embedding-3-small
OPENAI_BASE_URL=https://api.openai.com/v1      # Optional, for custom endpoints

支持的模型：

• 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         # Optional, default: text-embedding-v3
QWEN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1  # Optional

支持的模型：

• text-embedding-v3 (1024 維)
• text-embedding-v2 (1536 維)

Tool Description Configuration

自定義工具描述，引導 AI 助手在特定場景下調用工具：

使用場景示例： 如果你的博客專注於特定領域（如前端、AI、區塊鏈等），可以通過自定義工具描述來限制 AI 助手只在相關主題下調用搜索工具，避免在無關問題上浪費調用：

# 示例：限定為前端技術博客
TOOL_SEARCH_BLOG_DESCRIPTION="在前端技術博客中搜索內容。該博客涵蓋 React、Vue、TypeScript、前端工程化等主題。僅在用戶詢問前端相關技術問題時使用。"

# 示例：限定為 AI/ML 博客
TOOL_SEARCH_BLOG_DESCRIPTION="在 AI 和機器學習博客中搜索。涵蓋深度學習、LLM、提示工程、模型微調等內容。僅在 AI/ML 相關問題時調用。"

# 示例：通用博客（不限制）
TOOL_SEARCH_BLOG_DESCRIPTION="在博客中搜索相關內容。"

可選配置

🔧 技術細節

增量索引

系統使用 MD5 哈希值追蹤文檔變化：

1. 啟動時計算每個 Markdown 文件的哈希值。
2. 與數據庫中存儲的哈希值比較。
3. 僅重新索引發生變化的文件。
4. 自動從索引中刪除已刪除的文件。

文件監聽

即時監控博客目錄的變化：

• 文件新增：自動索引新文章。
• 文件修改：刪除舊的 chunks 並重新索引。
• 文件刪除：從向量數據庫中移除。

智能工具調用

通過自定義工具描述，實現：

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。