MCP-RAG

✨100% escrito por IA

Servicio RAG orientado a clientes de IA, centrado actualmente en servicios HTTP FastAPI y puntos finales MCP HTTP transmitibles (Streamable).

El código proporciona actualmente una capa de backend unificada:

• Servicio HTTP FastAPI

• MCP HTTP transmitible

• Tiempo de ejecución compartido, actualización en caliente de configuración, autenticación, limitación de tasa, cuotas, observabilidad

• Recuperación y gestión de documentos basada en un registro de bases de conocimiento

Capacidades actuales

• Importación de documentos: admite la adición directa de texto, así como la carga de txt, md, pdf, docx

• Recuperación: fusión de búsqueda vectorial + búsqueda por palabras clave

• Preguntas y respuestas: /search, /chat, MCP rag_ask

• Bases de conocimiento múltiples: admite bases de conocimiento únicas y recuperación/diálogo agregado de bases de conocimiento múltiples mediante kb_ids

• Ámbito de la base de conocimiento: public y agent_private

• Contexto de inquilino: base_collection + user_id + agent_id

• Gobernanza en tiempo de ejecución: clave API, limitación de tasa de memoria, cuotas de carga/indexación, caché de recuperación a nivel de solicitud

• Gobernanza de proveedores: presupuesto de proveedor, disyuntor, fallback

• Observabilidad: /health, /ready, /metrics

• Frontend: panel de gestión de página única integrado /app

Arquitectura

Enlace principal:

HTTP / MCP
  -> app_factory.py
  -> http_server.py / mcp_server.py
  -> context.py
  -> service_facade.py
  -> services/
       - runtime.py
       - indexing_service.py
       - retrieval_service.py
       - chat_service.py
  -> knowledge_bases.py
  -> core/indexing/
  -> retrieval/

Archivos clave:

• src/mcp_rag/cli.py: Punto de entrada CLI, proporciona serve e init

• src/mcp_rag/main.py: Punto de entrada de inicio del servicio HTTP

• src/mcp_rag/http_server.py: API HTTP, entrada SPA, montaje de MCP HTTP transmitible

• src/mcp_rag/mcp_server.py: Definición de herramientas MCP y rag_ask

• src/mcp_rag/app_factory.py: Ensamblaje unificado del contexto de la aplicación, tiempo de ejecución, guardrails

• src/mcp_rag/knowledge_bases.py: Registro de bases de conocimiento y resolución de bases de conocimiento predeterminadas

• src/mcp_rag/config.py: Modelo de configuración, persistencia JSON/SQLite, actualización en caliente

Requisitos del entorno

• Python >= 3.13

• uv

Instalación

Instalar CLI:

uv tool install mcp-rag

Ejecutar directamente después de la instalación:

mcp-rag serve

Desarrollar en el repositorio:

uv sync

Si se requiere embedding local:

uv sync --extra local-embeddings

Notas sobre los límites:

• Los usuarios que instalan con uv tool install mcp-rag no necesitan Node.js ni pnpm

• pnpm solo se utiliza para mantener la construcción del frontend, no es una dependencia de tiempo de ejecución del servicio

Inicio e inicialización

Iniciar servicio:

uv run mcp-rag serve

Inicializar directorio de datos:

uv run mcp-rag init --data-dir ./data

El puerto predeterminado es 8060, el servicio escucha por defecto en 0.0.0.0:8060.

Entradas comunes:

• Panel de gestión: http://127.0.0.1:8060/app

• Documentación de API: http://127.0.0.1:8060/docs

• Punto final MCP: http://127.0.0.1:8060/mcp

Entradas compatibles:

• / redirigirá a /app

• /doc redirigirá a /docs

• /documents-page redirigirá a /app/documents

• /config-page redirigirá a /app/config

Comportamiento en el primer inicio:

• Si ./data/config.json no existe, se utilizarán los valores predeterminados al leer la configuración

• Al iniciar el servicio se llamará a ensure_config_file(), escribiendo la configuración predeterminada en el disco

• ./data/chroma y los archivos SQLite relacionados en el directorio de datos se crearán según sea necesario

Frontend y recursos estáticos

El paquete de publicación incluirá src/mcp_rag/static/ en el wheel / sdist.

Esto significa:

• Los usuarios que instalen uv tool install mcp-rag pueden acceder directamente a /app

• No es necesario construir el frontend por separado, ni se requiere Node.js

• Los mantenedores del frontend deben generar los recursos estáticos más recientes antes de la publicación

El código fuente del frontend está en frontend/, la salida de construcción va a src/mcp_rag/static/app.

Flujo típico:

cd frontend
pnpm install
pnpm build

Modelo de base de conocimiento

El proyecto actual ya no depende solo de collection para organizar los datos, sino principalmente de un registro de bases de conocimiento.

Características de la base de conocimiento:

• Registro persistente en el archivo SQLite apuntado por knowledge_base_db_path

• Por defecto, se asegura la existencia de una base de conocimiento pública

• Al pasar user_id + agent_id, se asegura la existencia de la base de conocimiento agent_private predeterminada correspondiente

• Tras crear una nueva base de conocimiento, se asignará un nombre de colección interno estable, por ejemplo kb_<id>

La capa de interfaz aún conserva el parámetro collection debido a la necesidad de compatibilidad con métodos de llamada antiguos. El comportamiento actual es:

• Se puede pasar explícitamente kb_id

• También se puede seguir pasando la collection antigua

• El servicio resolverá la solicitud a la base de conocimiento específica y al nombre de colección real

Interfaz HTTP

Interfaces del sistema:

• GET /health

• GET /ready

• GET /metrics

Interfaces de configuración:

• GET /config

• POST /config

• POST /config/bulk

• POST /config/reset

• POST /config/reload

Interfaces de proveedor:

• GET /providers/{provider}/models

Interfaces de base de conocimiento:

• GET /collections

• GET /knowledge-bases

• POST /knowledge-bases

Interfaces de documentos:

• POST /add-document

• POST /upload-files

• GET /list-documents

• DELETE /delete-document

• GET /list-files

• DELETE /delete-file

Recuperación y preguntas y respuestas:

• GET /search

• POST /chat

Interfaces de depuración MCP:

• GET /debug/mcp/tools

• POST /debug/mcp/call

Algunos puntos a aclarar:

• /search y /chat admiten kb_id

• /search y /chat también admiten kb_ids para la agregación de múltiples bases de conocimiento

• /upload-files utiliza multipart/form-data

• /delete-document y /delete-file pasan los parámetros de eliminación a través del cuerpo de la solicitud

Si se han habilitado políticas de seguridad, la clave API se puede pasar de las siguientes maneras:

• Cabecera HTTP: x-api-key

• Cabecera: Authorization: Bearer <token>

• Parámetro de consulta, cuerpo JSON o api_key en el formulario

MCP

La forma principal actual es MCP HTTP transmitible:

{
  "mcpServers": {
    "rag": {
      "url": "http://127.0.0.1:8060/mcp"
    }
  }
}

Herramientas MCP implementadas:

• rag_ask

Parámetros principales de rag_ask:

• query

• mode: raw o summary

• collection

• kb_id

• scope

• limit

• threshold

• tenant

• user_id / agent_id

• _user_id / _agent_id

• api_key

• request_id

• trace_id

Ejemplo:

{
  "name": "rag_ask",
  "arguments": {
    "query": "FastAPI 是什么",
    "kb_id": 1,
    "mode": "summary",
    "limit": 5
  }
}

Configuración

Archivo de configuración predeterminado:

./data/config.json

Base de datos de conocimiento predeterminada:

./data/knowledge_bases.sqlite3

La configuración actual tiene un cambio importante:

• La configuración de ejecución normal se guarda en config.json

• La configuración relacionada con el proveedor se persistirá en SQLite, en lugar de seguir escribiéndose completamente en config.json

Es decir, estos campos se guardarán en service_provider_settings dentro de SQLite:

• embedding_provider

• embedding_fallback_provider

• provider_configs

• llm_provider

• llm_fallback_provider

• llm_model

• llm_base_url

• llm_api_key

El resto de la configuración se sigue guardando en config.json, por ejemplo:

{
  "http_port": 8060,
  "chroma_persist_directory": "./data/chroma",
  "knowledge_base_db_path": "./data/knowledge_bases.sqlite3",
  "enable_llm_summary": false,
  "security": {
    "enabled": false,
    "allow_anonymous": true,
    "api_keys": [],
    "tenant_api_keys": {}
  },
  "rate_limit": {
    "requests_per_window": 120,
    "window_seconds": 60,
    "burst": 30
  },
  "quotas": {
    "max_upload_files": 20,
    "max_upload_bytes": 52428800,
    "max_upload_file_bytes": 10485760,
    "max_index_documents": 500,
    "max_index_chunks": 2000,
    "max_index_chars": 500000
  },
  "cache": {
    "enabled": false,
    "max_entries": 256,
    "ttl_seconds": 300
  },
  "provider_budget": {
    "enabled": true
  }
}

Capacidades relacionadas con el proveedor integradas actualmente:

• El valor predeterminado del proveedor de embedding es zhipu

• El valor predeterminado del proveedor LLM es doubao

• La configuración del proveedor integrado incluye doubao, zhipu, aliyun

• qwen / dashscope se normalizarán a aliyun

• /providers/{provider}/models admite la obtención de listas de modelos desde servicios de modelos compatibles con OpenAI

• El embedding local admite m3e-small y e5-small

• LLM admite adicionalmente ollama

Actualización en caliente y refresco en tiempo de ejecución

Comportamiento de actualización en caliente:

• Tras modificar mediante /config, /config/bulk, /config/reset, /config/reload, el tiempo de ejecución se actualizará inmediatamente

• Al entrar una solicitud, se detectará si la configuración del disco ha cambiado mediante reload_if_changed()

• Después de cambiar la configuración del proveedor o de recuperación, se reconstruirán las dependencias de tiempo de ejecución relacionadas y se limpiará la caché de recuperación

Readiness y métricas

• /health devuelve un resumen de salud, instantánea de tiempo de ejecución y config_revision

• /ready devuelve 503 si el bootstrap no se ha completado o si las dependencias críticas no están listas

• /metrics devuelve métricas de observación agregadas por operación / proveedor

La instantánea de readiness actual incluirá:

• document_processor

• embedding_model

• vector_store

• hybrid_service

• llm_model

• retrieval_cache

• provider_budget

Pruebas

Ejecutar pruebas completas:

uv run python -m unittest discover -s tests

Comprobación de compilación:

uv run python -m compileall src

Cobertura de pruebas actual:

• Valores predeterminados de configuración, recarga de disco y migración de configuración de proveedor

• Comportamiento de la capa HTTP y la capa MCP

• Resolución de contexto de solicitud / inquilino

• Caché de recuperación a nivel de solicitud

• Presupuesto de proveedor / fallback

• Readiness / health / metrics

• Metadatos de empaquetado y recursos estáticos

Licencia

MIT