MCP RAG Server

Un servidor Python que proporciona funcionalidad de Generación Aumentada por Recuperación (RAG). Indexa varios formatos de documentos y requiere una base de datos PostgreSQL con pgvector.

GitHub
71
Prueba este MCPPatrocinado

Documentación

MCP RAG Server

MCP RAG Server es un servidor Python con funcionalidad RAG (Retrieval-Augmented Generation) compatible con el Model Context Protocol (MCP). Proporciona la capacidad de indexar documentos en múltiples formatos como Markdown, texto, PowerPoint y PDF como fuentes de datos, utilizando el modelo multilingual-e5-large para la indexación y recuperando información relevante mediante búsqueda vectorial.

Resumen

Este proyecto proporciona funcionalidad RAG además de una implementación básica de servidor MCP. Puede indexar documentos en múltiples formatos y buscar información relevante basada en consultas en lenguaje natural.

Características

  • Implementación básica del servidor MCP

    • Funciona sobre JSON-RPC over stdio
    • Mecanismo para registro y ejecución de herramientas
    • Manejo de errores y registro de eventos

  • Funcionalidad RAG

    • Carga y análisis de documentos en múltiples formatos (Markdown, texto, PowerPoint, PDF)
    • Soporte para directorios fuente con estructura jerárquica
    • Conversión a Markdown desde PowerPoint y PDF usando la biblioteca markitdown
    • Generación de embeddings con modelos seleccionables (multilingual-e5-large, ruri, etc.)
    • Base de datos vectorial usando pgvector de PostgreSQL
    • Recuperación de información relevante mediante búsqueda vectorial
    • Función de obtención de fragmentos anteriores y posteriores (asegura continuidad del contexto)
    • Función de recuperación de documentos completos (proporciona contexto completo)
    • Función de indexación diferencial (procesa solo archivos nuevos o modificados)

  • Herramientas

    • Herramienta de búsqueda vectorial (MCP)
    • Herramienta de obtención de número de documentos (MCP)
    • Herramienta de gestión de índices (CLI)

Requisitos previos

  • Python 3.10 o superior
  • PostgreSQL 14 o superior (con extensión pgvector)

Instalación

Instalación de dependencias

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

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

Configuración de PostgreSQL y pgvector

Usando Docker

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

Creación de la base de datos

Después de iniciar el contenedor de PostgreSQL, cree la base de datos con el siguiente comando:

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

Instalación de pgvector en PostgreSQL existente

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

Configuración de variables de entorno

Cree el archivo .env y configure las siguientes variables de entorno:

# 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: "

Configuración del modelo de embeddings

Este servidor permite seleccionar el modelo de embeddings mediante variables de entorno.

Modelos compatibles

multilingual-e5-large (predeterminado)

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

cl-nagoya/ruri-v3-30m

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

Acerca de los prefijos

En muchos modelos de embeddings (especialmente la serie E5), el rendimiento mejora añadiendo prefijos según el tipo de texto:

  • Para consultas de búsqueda: EMBEDDING_PREFIX_QUERY - se añade automáticamente a las consultas de búsqueda del usuario
  • Para documentos: EMBEDDING_PREFIX_EMBEDDING - se añade automáticamente a los documentos que se indexan

Los prefijos se procesan automáticamente, por lo que el cliente MCP no necesita preocuparse por ellos.

Nota al cambiar el modelo

Si cambia el modelo de embeddings, las dimensiones del vector pueden cambiar, por lo que debe borrar y recrear el índice existente:

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

Uso

Inicio del servidor MCP

Usando uv (recomendado)

uv run python -m src.main

Para especificar opciones:

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

Usando Python normal

python -m src.main

Uso de la herramienta de línea de comandos (CLI)

Se proporciona una herramienta de línea de comandos para borrar el índice y realizar la indexación.

Mostrar ayuda

python -m src.cli --help

Borrar el índice

python -m src.cli clear

Indexar documentos

# デフォルト設定でインデックス化（./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

Obtener el número de documentos en el índice

python -m src.cli count

Configuración en el host MCP

Para usar este servidor en un host MCP (Claude Desktop, Cline, Cursor, etc.), realice la siguiente configuración. Consulte la documentación de cada host MCP para el archivo json a configurar.

Ejemplo de configuración

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

Puntos clave de configuración

  • command: uv (recomendado) o python
  • args: matriz de argumentos de ejecución
  • /path/to/mcp-rag-server: reemplace con la ruta real de este repositorio

Sin usar uv

En entornos donde uv no está instalado, puede usar Python normal:

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

Uso de las herramientas RAG

search

Realiza una búsqueda vectorial.

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

Descripción de parámetros

  • query: consulta de búsqueda (obligatorio)
  • limit: número de resultados a devolver (predeterminado: 5)
  • with_context: si se obtienen también los fragmentos anteriores y posteriores (predeterminado: true)
  • context_size: número de fragmentos a obtener antes y después (predeterminado: 1)
  • full_document: si se obtiene el documento completo (predeterminado: false)

Mejora de los resultados de búsqueda

Esta herramienta proporciona mejores resultados de búsqueda mediante las siguientes funciones:

  1. Función de obtención de fragmentos anteriores y posteriores:

    • También obtiene e incluye en los resultados los fragmentos anteriores y posteriores al fragmento encontrado en la búsqueda
    • Se puede activar/desactivar con el parámetro with_context
    • El número de fragmentos a obtener antes y después se puede ajustar con el parámetro context_size

  2. Función de recuperación de documentos completos:

    • Obtiene e incluye en los resultados el texto completo del documento encontrado en la búsqueda
    • Se puede activar/desactivar con el parámetro full_document
    • Es especialmente útil para documentos cortos o cuando el contexto general es importante

  3. Mejora del formato de resultados:

    • Agrupa los resultados de búsqueda por archivo
    • Distingue visualmente entre "coincidencias de búsqueda", "contexto anterior y posterior" y "texto completo del documento"
    • Ordena por índice de fragmento para mantener el flujo del documento

get_document_count

Obtiene el número de documentos en el índice.

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

Ejemplos de uso

  1. Coloque los archivos de documentos en el directorio data/source. Los formatos de archivo compatibles son los siguientes:

    • Markdown (.md, .markdown)
    • Texto (.txt)
    • PowerPoint (.ppt, .pptx)
    • Word (.doc, .docx)
    • PDF (.pdf)

  2. Indexe los documentos usando el comando CLI:

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

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

  3. Inicie el servidor MCP:

    uv run python -m src.main

  4. Realice búsquedas usando la herramienta search.

Copia de seguridad y restauración

Para usar la base de datos indexada en otro PC, realice la copia de seguridad y restauración con los siguientes pasos.

Copia de seguridad mínima (solo base de datos PostgreSQL)

Si solo desea usar la función de búsqueda RAG en otro PC, la copia de seguridad de la base de datos PostgreSQL es suficiente, ya que todos los datos vectorizados se almacenan en la base de datos.

Copia de seguridad de la base de datos PostgreSQL

Para hacer una copia de seguridad de la base de datos PostgreSQL, use el comando pg_dump dentro del contenedor Docker:

# 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

Esto creará un archivo de copia de seguridad de la base de datos PostgreSQL (por ejemplo, 239 MB) en el directorio actual.

Procedimiento de restauración mínima

  1. Configure PostgreSQL y pgvector en el nuevo PC:
# 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;"
  1. Restaure la base de datos desde la copia de seguridad:
# バックアップファイルをコンテナにコピー
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
  1. Verifique la configuración del entorno:

En el nuevo PC, asegúrese de que la información de conexión a PostgreSQL en el archivo .env esté configurada correctamente.

  1. Verificación de funcionamiento:
python -m src.cli count

Esto mostrará el número de documentos en el índice. Si se muestra el mismo número que en el PC original, la restauración se ha realizado correctamente.

Copia de seguridad completa (opcional)

Si planea añadir nuevos documentos en el futuro o desea usar la función de indexación diferencial, también es recomendable realizar las siguientes copias de seguridad adicionales:

Copia de seguridad de documentos procesados

Haga una copia de seguridad del directorio de documentos procesados:

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

Copia de seguridad del archivo de configuración del entorno

Haga una copia de seguridad del archivo .env:

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

Procedimiento de restauración completa

  1. Requisitos previos

El nuevo PC debe tener instalado el siguiente software:

  • Python 3.10 o superior
  • PostgreSQL 14 o superior (con extensión pgvector)
  • El código base de mcp-rag-server

  1. Restaure la base de datos PostgreSQL con el "procedimiento de restauración mínima" anterior.

  2. Restaure los documentos procesados:

# ZIPファイルを展開
unzip processed_data_backup.zip -d /path/to/mcp-rag-server/
  1. Restaure el archivo de configuración del entorno:
# .envファイルを復元
cp env_backup.txt /path/to/mcp-rag-server/.env

Si es necesario, edite la configuración del archivo .env (especialmente la información de conexión a PostgreSQL) según el entorno del nuevo PC.

  1. Verificación de funcionamiento:
python -m src.cli count

Notas

  • Las versiones de PostgreSQL y pgvector deben ser compatibles entre el PC original y el nuevo PC.
  • Si hay una gran cantidad de datos, la copia de seguridad y la restauración pueden tardar.
  • En el nuevo PC, debe instalar los paquetes de Python necesarios (sentence-transformers, psycopg2-binary, etc.).

Estructura de directorios

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

Licencia

Este proyecto se publica bajo la licencia MIT. Consulte el archivo LICENSE para más detalles.