Hexo Blog Rag MCP

🚀 hexo-blog-rag-mcp

Chinese | English

A Retrieval Augmented Generation (RAG) MCP server for Hexo blogs based on vector search.

💡 Quick Experience: If you want to add the MCP of David's Blog, you can do so via https://luoluoqinghuan.cn/mcp.

🚀 Quick Start

Quick Deployment with Docker

Use the official image to start with one click:

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

Image Address: ghcr.io/richdavidmu/hexo-blog-rag-mcp:latest

Just replace /path/to/your/hexo/blog/source/_posts with the actual path of the source/_posts directory of your Hexo blog.

Transform your Hexo blog into a dedicated knowledge base for LLMs.

This project enables large language models to directly access and search the content of your Hexo blog through the MCP (Model Context Protocol). When you have a conversation with AI assistants like Claude or ChatGPT, they can retrieve technical articles, study notes, experience summaries, and other content from your blog in real-time, providing you with accurate answers based on your personal knowledge base.

🎯 Core Values

• 📚 Knowledge Reuse: Years of accumulated blog articles are no longer dormant and become the knowledge source for AI assistants.
• 🎓 Personalized Answers: AI provides customized suggestions based on your technical stack and experience.
• ⚡ Instant Retrieval: There's no need to manually browse old articles, as AI automatically finds relevant content.
• 🔒 Privacy Control: Data is stored locally, giving you full control over your knowledge base.

💡 Use Cases

• Technical Q&A: Ask the AI questions about the topics of your blog and get answers based on your articles.
• Knowledge Review: Quickly find previously written technical solutions and methods.
• Learning Assistant: Let the AI provide personalized learning suggestions based on your study notes.
• Content Creation: Assist in creating new blog articles based on existing article content.

🔗 How It Works

graph LR
    A[Your Hexo Blog] --> B[RAG MCP Server]
    B --> C[Vector Database]
    D[Claude/ChatGPT] <--> B
    D --> E[Answers Based on Blog Content]

1. Indexing Phase: Scan your Hexo blog, convert article content into vectors, and store them.
2. Conversation Phase: When you ask the AI a question, the server retrieves relevant article fragments.
3. Enhanced Answers: The AI provides accurate answers based on the retrieved content and context.

✨ Features

• 🔍 Semantic search for Hexo blogs based on vectors.
• 🤖 Support for multiple Embedding models (Simple, OpenAI, Qwen).
• 📊 Incremental indexing based on file hashes.
• 👀 Real-time file monitoring and automatic index updates.
• 📝 Structured logs in JSON format.
• 🎯 Search similarity threshold filtering.
• 🔧 Customizable tool descriptions for precise control of AI invocation scenarios.

Environment Variable Configuration

Required Configuration

Embedding Model Configuration

Choose one of the following three Embedding methods:

1. Simple Embedding (Default)

No additional configuration is required. Use a simple vectorization method based on hashes.

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

Supported models:

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

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

Supported models:

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

Tool Description Configuration

Customize tool descriptions to guide AI assistants to call tools in specific scenarios:

Usage Scenario Examples:

If your blog focuses on specific fields (such as front-end, AI, blockchain, etc.), you can limit the AI assistant to call the search tool only for relevant topics through customized tool descriptions, avoiding unnecessary calls for unrelated questions:

# Example: Limit to a front-end technology blog
TOOL_SEARCH_BLOG_DESCRIPTION="Search for content in the front-end technology blog. This blog covers topics such as React, Vue, TypeScript, and front-end engineering. Use only when the user asks front-end related technical questions."

# Example: Limit to an AI/ML blog
TOOL_SEARCH_BLOG_DESCRIPTION="Search in the AI and machine learning blog. Covers deep learning, LLM, prompt engineering, model fine-tuning, etc. Call only for AI/ML related questions."

# Example: General blog (no limit)
TOOL_SEARCH_BLOG_DESCRIPTION="Search for relevant content in the blog."

Optional Configuration

📦 Installation

# Install dependencies
pnpm install

# Build the project
pnpm run build

💻 Usage Examples

Development Environment

# Create a .env file
cp .env.example .env

# Edit .env to configure your environment variables
# Then start the server
pnpm run dev

Production Environment

# Build the project
pnpm run build

# Start the server
pnpm run start

Docker Deployment

# Build the image
docker build -t hexo-blog-rag-mcp .

# Run the container
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 Tools

search_blog

Search for relevant content in the Hexo blog.

Parameters:

• query (string, required): Search query
• topK (number, optional): Number of results to return (default: 5)
• threshold (number, optional): Similarity threshold (default: 1.0)

Example:

{
  "query": "How to deploy Hexo",
  "topK": 3,
  "threshold": 0.8
}

get_blog_context

Retrieve blog content to answer questions.

Parameters:

• question (string, required): User question
• threshold (number, optional): Similarity threshold (default: 1.0)

Example:

{
  "question": "What is the best way to optimize the performance of a Hexo blog?",
  "threshold": 0.7
}

MCP Resources

blog://all-posts

Get a list of all blog articles.

Return Format: JSON, containing the total number of articles and a list of article titles.

blog://posts/{title}

Get the full content of a specified article.

Parameters:

• title: Article title (Markdown file name without the .md extension)

Return Format: Full Markdown content of the article.

📚 Documentation

Logs are stored in the logs/ directory:

• app-YYYY-MM-DD.log - Application logs
• error-YYYY-MM-DD.log - Error logs

Logs are rotated daily and retained for 14 days.

🔧 Technical Details

Incremental Indexing

The system uses MD5 hashes to track document changes:

1. Calculate the hash value of each Markdown file at startup.
2. Compare it with the hash value stored in the database.
3. Only re-index files that have changed.
4. Automatically delete deleted files from the index.

File Monitoring

Monitor changes in the blog directory in real-time:

• New File: Automatically index new articles.
• File Modification: Delete old chunks and re-index.
• File Deletion: Remove from the vector database.

Intelligent Tool Invocation

Through customized tool descriptions, achieve:

1. Intelligent Judgment - The AI determines whether to search the blog before answering a question.
2. Reduce Invalid Calls - For questions unrelated to the blog topic (such as weather, news, etc.), the search tool will not be called.
3. Improve Efficiency - Search the blog content only for relevant topics, saving API calls and response time.

Examples:

• ❌ "What's the weather like today?" - The AI will not call the blog search.
• ❌ "Write me a poem." - The AI will not call the blog search.
• ✅ "Learn babel" - The AI will call the blog search.

Project Architecture

hexo-blog-rag-mcp/
├── packages/rag-mcp-server/
│   ├── src/
│   │   ├── services/
│   │   │   └── embedding.ts       # Embedding service (Simple/OpenAI/Qwen)
│   │   ├── storage/
│   │   │   └── vector-store.ts    # Vector database operations
│   │   ├── loaders/
│   │   │   └── hexo-loader.ts     # Hexo Markdown file loader
│   │   ├── utils/
│   │   │   ├── logger.ts          # Winston logs
│   │   │   ├── splitter.ts        # Text splitting
│   │   │   └── env.ts             # Environment variables
│   │   ├── mcp-server.ts          # Core of the MCP server
│   │   └── index.ts               # Application entry
│   └── logs/                      # Log files
└── .env                           # Configuration file

📄 License

Apache-2.0

Contribution

Contributions are welcome! Please feel free to submit a Pull Request.

Support

If you encounter any problems or have questions, please submit an issue.