使用说明

项目简介

本项目 'MCP MongoDB 小说服务器' 是一个基于 Model Context Protocol (MCP) 构建的后端服务，旨在帮助大型语言模型 (LLM) 更好地理解和利用存储在 MongoDB 数据库中的小说领域知识。它优化了数据结构和响应格式，以适应 LLM 有限的上下文窗口（例如 3k tokens）。

主要功能点

MCP 协议实现: 完全遵循 Model Context Protocol 规范，确保与 MCP 客户端的兼容性。
自然语言查询解析: 能够将自然语言查询转换为结构化的数据库操作，简化 LLM 的数据访问。
MongoDB 集成: 无缝连接 MongoDB 数据库，并优化查询以提升性能。
上下文优化响应: 服务器返回的响应经过精心设计，格式紧凑，特别适合 LLM 的小上下文窗口。
领域特定格式: 针对小说、章节、人物、问答等不同实体类型，采用定制化的格式，提高信息利用率。
Python 爬虫集成: 内置 Python 爬虫工具，方便从多个来源抓取数据并填充数据库。

安装步骤

环境准备:
- 确保已安装 Rust 最新稳定版 (https://www.rust-lang.org/)。
- 确保已安装 MongoDB 数据库服务，并已准备好包含小说数据的数据库实例。
- 确保已安装 Python 3.7+ (用于运行爬虫工具)。
- 确保已安装 Git (https://git-scm.com/)。

克隆仓库: 打开终端，执行以下命令克隆仓库（推荐使用包含子模块的方式）：

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

或者先正常克隆，再初始化子模块：

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

配置环境变量: 在项目根目录下创建 '.env' 文件，并根据您的 MongoDB 数据库配置和端口需求填写以下内容：

MONGODB_URI=mongodb://localhost:27017  # 您的 MongoDB 连接 URI
DATABASE_NAME=your_database_name      # 您的数据库名称
PORT=3000                             # 服务器监听端口，默认为 3000

请将 'MONGODB_URI' 和 'DATABASE_NAME' 替换为您的实际配置。

编译和运行服务器: 在终端中，进入项目根目录，执行以下命令编译并运行 MCP 服务器：
```
cargo build --release
cargo run --release
```
服务器成功启动后，默认监听 'http://localhost:3000'，MCP 端点为 '/mcp'。

服务器配置

MCP 服务器是为 MCP 客户端设计的后端服务。为了让 MCP 客户端能够连接到此服务器，您需要在客户端中进行如下配置。以下是一个 JSON 格式的配置示例，通常在 MCP 客户端的设置中进行配置：

{
  "serverName": "mcp-mongodb-novel-server",  // MCP 服务器的名称，您可以自定义
  "command": "mcp-mongodb-novel-server",    // 启动 MCP 服务器的命令，这里假设 'mcp-mongodb-novel-server' 可执行文件在您的 PATH 环境变量中，或者您可以使用绝对路径，例如 "/path/to/mcp-mongodb-novel-server/target/release/mcp-mongodb-novel-server"
  "args": [],                               // 启动命令的参数，本项目默认不需要额外的启动参数
  "transport": "stdio",                       // 使用 stdio 作为传输协议
  "protocol": "json-rpc",                     // 使用 JSON-RPC 协议进行通信
  "description": "MCP MongoDB Novel Server", // 服务器的描述信息，方便您在客户端中识别
  "capabilities": [                           // 服务器声明的功能，客户端可以据此了解服务器能力
    "query",
    "get_chapter_content",
    "get_character_details",
    "query_qa_regex",
    "query_chapter_regex",
    "query_character_regex",
    "update_chapter_summary",
    "mcp.capabilities",
    "mcp.prompts",
    "initialize",
    "notifications/initialized"
  ],
  "baseUrl": "http://localhost:3000/mcp"    // 如果您选择使用 HTTP 传输协议，则需要配置服务器的根 URL 和 MCP 端点，对于 stdio 传输，此项配置通常不生效
}

配置说明:

'serverName': 为您的 MCP 服务器指定一个易于识别的名称。
'command': 重要: 这是启动 MCP 服务器可执行文件的命令。请确保 'mcp-mongodb-novel-server' 命令在您的系统 'PATH' 环境变量中可用。如果不可用，您需要提供 'mcp-mongodb-novel-server' 可执行文件的绝对路径。该可执行文件在编译成功后位于 'mcp-mongodb-novel-server/target/release/mcp-mongodb-novel-server'。
'args': 本项目服务器默认不需要命令行参数，因此 'args' 数组为空。如有需要，您可以在此处添加参数。
'transport': 设置为 'stdio'，表示 MCP 客户端将通过标准输入输出流与服务器通信。
'protocol': 设置为 'json-rpc'，指定通信协议为 JSON-RPC。
'description': 对服务器的简短描述，方便在 MCP 客户端界面中识别和管理多个服务器连接。
'capabilities': 列出了服务器所支持的 MCP 方法，客户端可以根据这些声明来了解服务器的功能。
'baseUrl': 当 'transport' 设置为 'stdio' 时，此配置通常不生效。如果客户端支持 HTTP 传输，并且您希望通过 HTTP 与服务器通信，则需要配置此项，并确保服务器以 HTTP 模式运行（本项目默认配置为 HTTP 模式，可以通过修改 'src/main.rs' 中的 'stdio_mode' 变量切换）。

基本使用方法

启动服务器: 按照上述安装步骤运行 MCP 服务器。
配置 MCP 客户端: 在您的 MCP 客户端中，根据上述 “服务器配置” 示例，添加或配置连接到 'MCP MongoDB 小说服务器' 的设置。请特别注意 'command' 字段的配置，确保 MCP 客户端能够正确启动服务器进程。

发送 MCP 请求: 使用 MCP 客户端，您可以向服务器发送符合 MCP 协议的 JSON-RPC 请求，例如查询小说信息、章节内容、人物详情或问答数据。

示例 JSON-RPC 请求 (查询人物信息):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "query_character",
  "params": {
    "character_id": "12345"  // 替换为实际的人物 ID
  }
}

通过 HTTP 发送请求: 您也可以使用 HTTP 客户端（如 'curl' 或 Postman）直接向服务器的 '/mcp' 端点发送 POST 请求，请求体为符合 MCP 协议的 JSON 数据。

curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "id": 1, "method": "query_character", "params": {"character_id": "12345"}}' http://localhost:3000/mcp

使用 CRUD API (可选): 除了 MCP 协议，服务器还提供了 RESTful API 用于直接管理数据库内容 (小说、章节、人物、问答)。您可以参考 'README.md' 中 "CRUD API" 部分的说明，使用 HTTP 客户端或编程方式调用这些 API 进行数据管理。

爬虫工具使用

本项目集成了 Python 爬虫工具，用于从网络小说站点抓取数据并填充 MongoDB 数据库。请参考 'README.md' 中 "Python Scrapers" 部分的说明，配置和运行爬虫脚本。

关键词