MCP RAG Server

Um servidor Python que fornece funcionalidade de Geração Aumentada por Recuperação (RAG). Ele indexa vários formatos de documentos e requer um banco de dados PostgreSQL com pgvector.

GitHub
71
Experimente este MCPPatrocinado

Documentação

MCP RAG Server

O MCP RAG Server é um servidor Python com funcionalidade RAG (Retrieval-Augmented Generation) compatível com o Model Context Protocol (MCP). Ele indexa documentos em vários formatos, como Markdown, texto, PowerPoint e PDF, usando o modelo multilingual-e5-large, e fornece funcionalidade de recuperação de informações relevantes por meio de busca vetorial.

Visão geral

Este projeto fornece funcionalidade RAG além da implementação básica de um servidor MCP. Ele pode indexar documentos em vários formatos e pesquisar informações relevantes com base em consultas em linguagem natural.

Funcionalidades

  • Implementação básica do servidor MCP

    • Opera com base em JSON-RPC over stdio
    • Mecanismo para registro e execução de ferramentas
    • Tratamento de erros e registro de logs

  • Funcionalidade RAG

    • Leitura e análise de documentos em vários formatos (Markdown, texto, PowerPoint, PDF)
    • Suporte a diretórios de origem com estrutura hierárquica
    • Conversão para Markdown a partir de PowerPoint e PDF usando a biblioteca markitdown
    • Geração de embeddings usando modelos selecionáveis (multilingual-e5-large, ruri, etc.)
    • Banco de dados vetorial usando pgvector do PostgreSQL
    • Recuperação de informações relevantes por meio de busca vetorial
    • Funcionalidade de recuperação de chunks anteriores e posteriores (garantindo continuidade do contexto)
    • Funcionalidade de recuperação do documento completo (fornecendo contexto completo)
    • Funcionalidade de indexação incremental (processa apenas arquivos novos ou modificados)

  • Ferramentas

    • Ferramenta de busca vetorial (MCP)
    • Ferramenta de contagem de documentos (MCP)
    • Ferramenta de gerenciamento de índice (CLI)

Pré-requisitos

  • Python 3.10 ou superior
  • PostgreSQL 14 ou superior (com extensão pgvector)

Instalação

Instalação das dependências

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

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

Configuração do PostgreSQL e pgvector

Usando Docker

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

Criação do banco de dados

Após iniciar o contêiner PostgreSQL, crie o banco de dados com o seguinte comando:

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

Instalando pgvector em um PostgreSQL existente

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

Configuração das variáveis de ambiente

Crie o arquivo .env e defina as seguintes variáveis de ambiente:

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

Configuração do modelo de embeddings

Neste servidor, você pode selecionar o modelo de embeddings por meio de variáveis de ambiente.

Modelos suportados

multilingual-e5-large (padrão)

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="検索文書: "

Sobre os prefixos

Em muitos modelos de embeddings (especialmente da família E5), o desempenho melhora ao adicionar prefixos de acordo com o tipo de texto:

  • Para consultas de busca: EMBEDDING_PREFIX_QUERY - adicionado automaticamente à consulta de busca do usuário
  • Para documentos: EMBEDDING_PREFIX_EMBEDDING - adicionado automaticamente aos documentos indexados

Os prefixos são processados automaticamente, portanto o cliente MCP não precisa se preocupar com eles.

Observações ao alterar o modelo

Ao alterar o modelo de embeddings, a dimensão vetorial pode mudar, portanto limpe e recrie o índice existente:

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

Uso

Iniciando o servidor MCP

Usando uv (recomendado)

uv run python -m src.main

Ao especificar opções:

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 da ferramenta de linha de comando (CLI)

Está disponível uma ferramenta de linha de comando para limpar o índice e realizar a indexação.

Exibição da ajuda

python -m src.cli --help

Limpeza do índice

python -m src.cli clear

Indexação de 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

Obtenção do número de documentos no índice

python -m src.cli count

Configuração no host MCP

Para usar este servidor em um host MCP (Claude Desktop, Cline, Cursor, etc.), faça a configuração da seguinte forma. Consulte a documentação de cada host MCP para o arquivo json a ser configurado.

Exemplo de configuração

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

Pontos importantes da configuração

  • command: uv (recomendado) ou python
  • args: matriz de argumentos de execução
  • /path/to/mcp-rag-server: substitua pelo caminho real deste repositório

Sem usar uv

Em ambientes sem uv instalado, você pode usar Python normal:

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

Uso das ferramentas RAG

search

Realiza busca vetorial.

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

Descrição dos parâmetros

  • query: consulta de busca (obrigatório)
  • limit: número de resultados a retornar (padrão: 5)
  • with_context: se deve obter também os chunks anteriores e posteriores (padrão: true)
  • context_size: número de chunks a obter antes e depois (padrão: 1)
  • full_document: se deve obter o documento inteiro (padrão: false)

Melhoria dos resultados de busca

Esta ferramenta fornece melhores resultados de busca por meio das seguintes funcionalidades:

  1. Funcionalidade de recuperação de chunks anteriores e posteriores:

    • Também obtém e inclui nos resultados os chunks anteriores e posteriores ao chunk encontrado na busca
    • Pode ser ativada/desativada pelo parâmetro with_context
    • O número de chunks a obter antes e depois pode ser ajustado pelo parâmetro context_size

  2. Funcionalidade de recuperação do documento completo:

    • Obtém e inclui nos resultados o texto completo do documento encontrado na busca
    • Pode ser ativada/desativada pelo parâmetro full_document
    • Particularmente útil ao lidar com documentos curtos ou documentos em que o contexto geral é importante

  3. Melhoria na formatação dos resultados:

    • Agrupa os resultados da busca por arquivo
    • Distingue visualmente "correspondências da busca", "contexto anterior/posterior" e "texto completo do documento"
    • Mantém o fluxo do documento ordenando pelo índice do chunk

get_document_count

Obtém o número de documentos no índice.

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

Exemplos de uso

  1. Coloque os arquivos de documento no diretório data/source. Os formatos de arquivo suportados são:

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

  2. Indexe os documentos usando o comando CLI:

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

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

  3. Inicie o servidor MCP:

    uv run python -m src.main

  4. Realize a busca usando a ferramenta search.

Backup e restauração

Para usar o banco de dados indexado em outro PC, faça backup e restauração seguindo os passos abaixo.

Backup mínimo (somente banco de dados PostgreSQL)

Se você apenas deseja usar a funcionalidade de busca RAG em outro PC, o backup do banco de dados PostgreSQL é suficiente, pois todos os dados vetorizados estão armazenados no banco de dados.

Backup do banco de dados PostgreSQL

Para fazer backup do banco de dados PostgreSQL, use o comando pg_dump dentro do contêiner 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

Isso criará um arquivo de backup do banco de dados PostgreSQL (exemplo: 239MB) no diretório atual.

Procedimento mínimo de restauração

  1. Configure o PostgreSQL e o pgvector no novo 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 o banco de dados a partir do backup:
# バックアップファイルをコンテナにコピー
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 a configuração do ambiente:

No novo PC, verifique se as informações de conexão do PostgreSQL no arquivo .env estão configuradas corretamente.

  1. Verificação de funcionamento:
python -m src.cli count

Isso exibirá o número de documentos no índice. Se o mesmo número do PC original for exibido, a restauração foi concluída com sucesso.

Backup completo (opcional)

Se você planeja adicionar novos documentos no futuro ou deseja usar a funcionalidade de indexação incremental, também é recomendável fazer os seguintes backups adicionais:

Backup dos documentos processados

Faça backup do diretório de documentos processados:

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

Backup do arquivo de configuração do ambiente

Faça backup do arquivo .env:

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

Procedimento completo de restauração

  1. Pré-requisitos

O novo PC deve ter o seguinte software instalado:

  • Python 3.10 ou superior
  • PostgreSQL 14 ou superior (com extensão pgvector)
  • O código base do mcp-rag-server

  1. Restaure o banco de dados PostgreSQL usando o "procedimento mínimo de restauração" acima.

  2. Restaure os documentos processados:

# ZIPファイルを展開
unzip processed_data_backup.zip -d /path/to/mcp-rag-server/
  1. Restaure o arquivo de configuração do ambiente:
# .envファイルを復元
cp env_backup.txt /path/to/mcp-rag-server/.env

Se necessário, edite as configurações do arquivo .env (especialmente as informações de conexão do PostgreSQL) de acordo com o ambiente do novo PC.

  1. Verificação de funcionamento:
python -m src.cli count

Observações

  • As versões do PostgreSQL e do pgvector devem ser compatíveis entre o PC original e o novo PC.
  • Se houver muitos dados, o backup e a restauração podem levar tempo.
  • No novo PC, é necessário instalar os pacotes Python necessários (sentence-transformers, psycopg2-binary, etc.).

Estrutura de diretórios

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

Licença

Este projeto é publicado sob a licença MIT. Consulte o arquivo LICENSE para obter detalhes.