MCP MongoDB Server

MCP MongoDB 服务

一个高性能的 模型上下文协议（MCP） 服务，为大语言模型（LLM）与 MongoDB 之间提供高效的知识接口。该服务针对较小的上下文窗口（3k tokens）进行了优化，使大语言模型能够检索并与存储在 MongoDB 集合中的领域专属知识进行交互。

🚀 功能

• 双服务架构：

  • 基于 SSE 的 MCP 服务，实现高效的大语言模型通信
  • 用于数据库管理的 RESTful CRUD API

• Token 效率：响应经过格式化，可在较小的上下文窗口中承载尽可能多的信息

• MongoDB 集成：可使用现有 MongoDB 集合，并采用经过优化的查询机制

• 数据模型，适用于多种领域专属实体：

  • 小说
  • 章节
  • 角色
  • 问答知识库

• Python 爬虫集成：作为子模块包含在项目中，可从各种来源填充数据库

🔧 架构

                    ┌───────────────────┐
                    │                   │
                    │     Language      │
                    │      Models       │
                    │                   │
                    └─────────┬─────────┘
                              │
                              │ MCP (JSON-RPC 2.0)
                              ▼
┌─────────────────────────────────────────────────────┐
│                                                     │
│  ┌─────────────────┐           ┌─────────────────┐  │
│  │                 │           │                 │  │
│  │   SSE Server    │◄────────►│   MCP Handler   │  │
│  │  (Port 3000)    │           │                 │  │
│  └─────────────────┘           └────────┬────────┘  │
│                                         │           │
│                                         ▼           │
│                                ┌────────────────┐   │
│  ┌─────────────────┐           │                │   │
│  │                 │           │  DB Services   │   │
│  │   CRUD API      │◄────────►│                │   │
│  │  (Port 3001)    │           └────────────────┘   │
│  └─────────────────┘                   │           │
│                                         │           │
└─────────────────────────────────────────┼───────────┘
                                          │
                                          ▼
                                 ┌─────────────────┐
                                 │                 │
                                 │    MongoDB      │
                                 │                 │
                                 └─────────────────┘

🏁 开始使用

前置条件

• Rust（最新稳定工具链）
• MongoDB 实例
• Python 3.7+（用于数据爬虫）

安装

1. 克隆仓库及其子模块：

   git clone --recursive https://github.com/SFBB/mcp-mongodb-novel-server.git
   cd mcp-mongodb-novel-server
   

2. 配置环境： 在项目根目录中创建一个 .env 文件：

   MONGODB_URI=mongodb://localhost:27017
   DATABASE_NAME=your_database
   PORT=3000  # Base port (MCP SSE server)
               # CRUD API will use PORT+1 (3001)
   

3. 构建并运行：

   cargo build --release
   cargo run --release
   

成功启动后，你会看到：

• MCP SSE 端点位于 http://127.0.0.1:3000/sse
• MCP POST 端点位于 http://127.0.0.1:3000/message
• CRUD API 端点位于 http://127.0.0.1:3001/api/...

使用方法

你需要先运行此服务，然后根据 JSON-RPC 或 SSE 配置客户端。

以下是 VS Code copilot 客户端的示例配置。

"mcp-mongodb-novel-server": {
    "type": "sse",
    "url": "http://localhost:3000/sse"
}  

🔌 服务端点

1. MCP 服务（SSE 协议）

MCP 服务提供两个端点：

• SSE 端点：http://localhost:3000/sse
  • 用于建立 SSE 连接以接收事件
• POST 端点：http://localhost:3000/message
  • 用于发送 JSON-RPC 2.0 格式的命令

MCP 请求示例（使用 POST 请求 /message）：

{
  "jsonrpc": "2.0",
  "id": "request-1",
  "method": "query_character",
  "params": {
    "character_id": "5f8e4c3b2a1d"
  }
}

2. CRUD API（REST）

CRUD API 提供用于管理数据库内容的 RESTful 端点：

• 小说：/api/novels
• 章节：/api/chapters
• 角色：/api/characters
• 问答：/api/qa

支持标准 REST 操作（GET、POST、PATCH、DELETE）。

📊 数据模型

小说

{
  "_id": "ObjectId",
  "title": "String",
  "author": "String",
  "summary": "String",
  "year": "Number",
  "tags": ["String"]
}

章节

{
  "_id": "ObjectId",
  "novel_id": "ObjectId",
  "title": "String",
  "chapter_number": "Number",
  "summary": "String",
  "content": "String",
  "word_count": "Number"
}

角色

{
  "_id": "ObjectId",
  "novel_id": "ObjectId",
  "name": "String",
  "description": "String",
  "traits": ["String"],
  "relationships": [
    {
      "character_id": "ObjectId",
      "type": "String"
    }
  ]
}

问答

{
  "_id": "ObjectId",
  "question": "String",
  "answer": "String",
  "tags": ["String"],
  "novel_id": "ObjectId"
}

🤖 MCP 方法

该服务支持以下用于与大语言模型交互的 MCP 方法：

查询方法

方法	描述	参数
query_character	获取角色详情	{"character_id": "string"}
query_novel	获取小说元数据	{"novel_id": "string"}
query_chapter	获取章节信息	{"chapter_id": "string"} 或 {"chapter_number": number} 或 {"chapter_title": "string"}
query_qa_regex	根据正则表达式查找问答条目	{"regex_pattern": "string"}
query_chapter_regex	根据正则表达式查找章节	{"regex_pattern": "string"}
query_character_regex	根据正则表达式查找角色	{"regex_pattern": "string"}

更新方法

方法	描述	参数
update_chapter_summary	更新章节摘要	{"auth_token": "string", "chapter_id": "string", "summary": "string"}

📥 数据填充

此项目包含 Python 爬虫子模块，可帮助你填充 MongoDB：

角色爬虫

cd character-scraper
pip install -r requirements.txt
python src/scraper.py --config config/settings.json

小说爬虫库

cd scraper_library
pip install -r requirements.txt
python -m src.scrapers.scrape_syosetu --url <novel_url>

可用的爬虫包括：

• scrape_syosetu.py（Syosetu 小说）
• scrape_69shu.py（69Shu 小说）
• scrape_ximalaya.py（喜马拉雅有声书）
• scrape_qa.py（问答内容）
• scrape_x_timeline.py（Twitter/X 时间线）
• 以及更多……

🛠️ 开发

更新子模块

# Update all submodules to their latest version
git submodule update --remote --merge

# Navigate to a specific submodule and pull changes
cd scraper_library
git pull origin main
cd ..
git add scraper_library
git commit -m "Update scraper_library"

运行测试

cargo test

代码风格

此项目遵循 Rust 标准代码风格指南：

# Check code formatting
cargo fmt -- --check

# Run linting
cargo clippy

性能调优

对于高流量部署，请考虑：

1. 为文本搜索和关联创建 MongoDB 索引
2. 增加 Tokio 工作线程以处理 CPU 密集型操作
3. 配置 MongoDB 连接池

📄 许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。