使用说明

MCP RAG服务器

MCP RAG Server单击功能区上Model Context Protocol (MCP)遵守RAG（Retrieval-Augmented Generation）具有功能Python服务器。下标、文本、力量点、PDF选项卡页面上创建或编辑条目multilingual-e5-large它提供了使用模型进行索引并通过矢量搜索获取相关信息的功能。

概要

此项目包括：MCP除了服务器的基本实现之外RAG提供功能。可以对多种格式的文档进行索引，并根据自然语言查询搜索相关信息。

机能

MCP基本服务器实施
- JSON-RPC over stdio基本动作
- 工具注册和运行机制
- 错误处理和记录
RAG机能
- 多格式文档（下标、文本、PPT、PDF）导入和分析
- 支持具有分层结构的源目录
- markitdown使用库的PPTPDF从标记转换
- 使用可选的嵌入式模型（multilingual-e5-large、ruri等）生成嵌入式
- PostgreSQL的，之pgvector使用向量数据库
- 通过矢量检索获取相关信息
- 前后信息块检索功能（确保上下文连续性）
- 文档全文检索功能（提供完整的上下文）
- 差分索引功能（仅处理新变更文件）
工具
- 矢量检索工具（MCP）
- 文档检索工具（MCP）
- 索引管理工具（CLI）

前提条件

Python 3.10以上
PostgreSQL 14以上（带pgvector扩展）

安装

安装相关性

# uvがインストールされていない場合は先にインストール
# pip install uv

# 依存関係のインストール
uv sync

PostgreSQL打开pgvector设置

Docker中所述修改相应参数的值

# pgvectorを含むPostgreSQLコンテナを起動
docker run --name postgres-pgvector -e POSTGRES_PASSWORD=password -p 5432:5432 -d pgvector/pgvector:pg17

创建数据库

PostgreSQL启动容器后，使用以下命令创建数据库：

# ragdbデータベースの作成
docker exec -it postgres-pgvector psql -U postgres -c "CREATE DATABASE ragdb;"

现有PostgreSQL在…之上pgvector安装时

-- pgvectorエクステンションをインストール
CREATE EXTENSION vector;

设置环境变量

.env创建文件并设置以下环境变量：

# PostgreSQL接続情報
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=password
POSTGRES_DB=ragdb

# ドキュメントディレクトリ
SOURCE_DIR=./data/source
PROCESSED_DIR=./data/processed

# エンベディングモデル設定
EMBEDDING_MODEL=intfloat/multilingual-e5-large
EMBEDDING_DIM=1024
EMBEDDING_PREFIX_QUERY="query: "
EMBEDDING_PREFIX_EMBEDDING="passage: "

设置嵌入式模型

使用此服务器，可以在环境变量中选择嵌入式模型。

支持的模型

multilingual-e5-large（默认值）

EMBEDDING_MODEL=intfloat/multilingual-e5-large
EMBEDDING_DIM=1024
EMBEDDING_PREFIX_QUERY="query: "
EMBEDDING_PREFIX_EMBEDDING="passage: "

Cl nagoya/ruriov 3-30米

EMBEDDING_MODEL=cl-nagoya/ruri-v3-30m
EMBEDDING_DIM=256
EMBEDDING_PREFIX_QUERY="検索クエリ: "
EMBEDDING_PREFIX_EMBEDDING="検索文書: "

关于前缀

许多嵌入式模型（特别是E5系统）可根据文本类型添加前缀以提高性能：

用于搜索查询: EMBEDDING_PREFIX_QUERY -自动添加到用户搜索查询
文书用: EMBEDDING_PREFIX_EMBEDDING -自动添加到索引文档

因为前缀是自动处理的MCP客户端不需要意识到。

更改模型时的注意事项

如果更改了嵌入式模型，则请清除现有索引并重新创建，因为矢量维可能会改变：

python -m src.cli clear
python -m src.cli index

使用方法

MCP启动服务器

uv（建议）

uv run python -m src.main

选项：

uv run python -m src.main --name "my-rag-server" --version "1.0.0" --description "My RAG Server"

正常Python中所述修改相应参数的值

python -m src.main

使用命令行工具（CLI）

提供了用于清除和索引索引的命令行工具。

显示帮助

python -m src.cli --help

清除索引

python -m src.cli clear

文档索引

# デフォルト設定でインデックス化（./data/source ディレクトリ）
python -m src.cli index

# 特定のディレクトリをインデックス化
python -m src.cli index --directory ./path/to/documents

# チャンクサイズとオーバーラップを指定してインデックス化
python -m src.cli index --directory ./data/source --chunk-size 300 --chunk-overlap 50
# または短い形式で
python -m src.cli index -d ./data/source -s 300 -o 50

# 差分インデックス化（新規・変更ファイルのみを処理）
python -m src.cli index --incremental
# または短い形式で
python -m src.cli index -i

检索索引中的文档数

python -m src.cli count

MCP在主机上设置

MCP要在主机（Claude Desktop、Cline、Cursor等）上使用此服务器，请执行以下设置：。设定json对于文件，请参见MCP请参阅主机文档。

设定例

{
  "mcpServers": {
    "mcp-rag-server": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/mcp-rag-server",
        "python",
        "-m",
        "src.main"
      ]
    }
  }
}

设置要点

command: uv（推荐）或python
args：执行参数数组
/path/to/mcp-rag-server：替换为此存储库的实际路径

uv不使用

uv在未安装的环境中Python可用：

{
  "command": "python",
  "args": [
    "-m",
    "src.main"
  ],
  "cwd": "/path/to/mcp-rag-server"
}

RAG使用工具

搜索

进行矢量检索。

{
  "jsonrpc": "2.0",
  "method": "search",
  "params": {
    "query": "Pythonのジェネレータとは何ですか？",
    "limit": 5,
    "with_context": true,
    "context_size": 1,
    "full_document": false
  },
  "id": 1
}

参数说明

query：搜索查询（必需）
limit：返回的结果数（默认值：5）
with_context：是否也检索前后信息块（默认值：true）
context_size：前后获取的信息块数（默认值：1）
full_document：是否检索整个文档（默认值：false）

改进搜索结果

该工具通过以下功能提供更好的搜索结果：

前后信息块获取功能：
- 检索在搜索中命中的信息块之前和之后的信息块，并将其包含在结果中
- with_context启用/禁用参数
- context_size可通过参数调整前后取得信息块数
文档全文检索功能：
- 检索在搜索中命中的文档的全文并将其包含在结果中
- full_document启用/禁用参数
- 特别是在短文档或整个上下文处理重要文档时很有用
结果整形改善：
- 按文件分组搜索结果
- 在视觉上区分“查找成功”、“前后上下文”和“文档全文”
- 按区块索引排序以保持文档流

get_document_count

获取索引中的文档数。

{
  "jsonrpc": "2.0",
  "method": "get_document_count",
  "params": {},
  "id": 2
}

使用例

打开文档文件 data/source 放置在目录中。支持的文件格式如下：
- 标记下降（.md，.markdown）
- 文本（.txt）
- 功率点（.ppt，.pptx）
- Word（.doc、.docx）
- PDF（.PDF）

CLI使用命令索引文档：

# 初回は全件インデックス化
python -m src.cli index

# 以降は差分インデックス化で効率的に更新
python -m src.cli index -i

MCP启动服务器：
```
uv run python -m src.main
```
search使用工具进行搜索。

备份和恢复

索引数据库PC中所述修改相应参数的值。

最小备份（仅限PostgreSQL数据库）

简单地说PC单击功能区上RAG如果你只是想使用搜索功能PostgreSQL数据库备份就足够了。因为所有矢量化的数据都保存在数据库中。

PostgreSQL备份数据库

PostgreSQL单击功能区上的Docker在容器中pg_dump使用命令：

# Dockerコンテナ内でデータベースをバックアップ
docker exec -it postgres-pgvector pg_dump -U postgres -d ragdb -F c -f /tmp/ragdb_backup.dump

# バックアップファイルをコンテナからホストにコピー
docker cp postgres-pgvector:/tmp/ragdb_backup.dump ./ragdb_backup.dump

因此PostgreSQL数据库备份文件（例如239MB）将在当前目录中创建。

最小还原过程

新建PC单击功能区上PostgreSQL打开pgvector设置：

# Dockerを使用する場合
docker run --name postgres-pgvector -e POSTGRES_PASSWORD=password -p 5432:5432 -d pgvector/pgvector:pg17

# データベースを作成
docker exec -it postgres-pgvector psql -U postgres -c "CREATE DATABASE ragdb;"

从备份中恢复数据库：

# バックアップファイルをコンテナにコピー
docker cp ./ragdb_backup.dump postgres-pgvector:/tmp/ragdb_backup.dump

# コンテナ内でデータベースを復元
docker exec -it postgres-pgvector pg_restore -U postgres -d ragdb -c /tmp/ragdb_backup.dump

检查首选项：

新建PC那么.env在动态输入提示中单击PostgreSQL请确保已正确设置连接信息。

动作确认：

python -m src.cli count

这将显示索引中的文档数。原始PC查看项目中可用的所有族。

完全备份（可选）

如果您将来计划添加新文档，或者希望使用差分索引功能，则可以执行以下附加备份：

备份已处理的文档

备份已处理的文档目录：

# 処理済みドキュメントディレクトリをZIPファイルにバックアップ
zip -r processed_data_backup.zip data/processed/

备份配置文件

.env备份文件：

# .envファイルをコピー
cp .env env_backup.txt

完全复元手顺

前提条件

新建PC必须安装以下软件：

Python 3.10以上
PostgreSQL 14以上（带pgvector扩展）
mcp-rag-server代码库

PostgreSQL按照上面的“最低还原步骤”还原数据库。
恢复已处理的文档：

# ZIPファイルを展開
unzip processed_data_backup.zip -d /path/to/mcp-rag-server/

恢复配置文件：

# .envファイルを復元
cp env_backup.txt /path/to/mcp-rag-server/.env

如果需要，请选择新的PC适应环境.env文件设置（特别是PostgreSQL连接信息）。

动作确认：

python -m src.cli count

注意点

PostgreSQL的版本和pgvector的版本是PC新的PC对较大场景进行渲染期间已观察到该故障。
如果有大量数据，备份和恢复可能需要很长时间。
新建PC那么，必要的Python软件包（sentence-transformers、psycopg2-binary等已弃用的函数的缺少的支持。

目录结构

mcp-rag-server/
├── data/
│   ├── source/        # 原稿ファイル（階層構造対応）
│   │   ├── markdown/  # マークダウンファイル
│   │   ├── docs/      # ドキュメントファイル
│   │   └── slides/    # プレゼンテーションファイル
│   └── processed/     # 処理済みファイル（テキスト抽出済み）
│       └── file_registry.json  # 処理済みファイルの情報（差分インデックス用）
├── docs/
│   └── design.md      # 設計書
├── logs/              # ログファイル
├── src/
│   ├── __init__.py
│   ├── document_processor.py  # ドキュメント処理モジュール
│   ├── embedding_generator.py # エンベディング生成モジュール
│   ├── example_tool.py        # サンプルツールモジュール
│   ├── main.py                # メインエントリーポイント
│   ├── mcp_server.py          # MCPサーバーモジュール
│   ├── rag_service.py         # RAGサービスモジュール
│   ├── rag_tools.py           # RAGツールモジュール
│   └── vector_database.py     # ベクトルデータベースモジュール
├── tests/
│   ├── __init__.py
│   ├── conftest.py
│   ├── test_document_processor.py
│   ├── test_embedding_generator.py
│   ├── test_example_tool.py
│   ├── test_mcp_server.py
│   ├── test_rag_service.py
│   ├── test_rag_tools.py
│   └── test_vector_database.py
├── .env           # 環境変数設定ファイル
├── .gitignore
├── LICENSE
├── pyproject.toml
└── README.md

许可证

这个项目MIT在许可证下公开。了解更多信息许可证请参见文件。