Asistente de Conocimiento MCP

Un servidor de Model Context Protocol (MCP) de solo lectura que permite a un cliente de IA buscar en una base de conocimiento y recuperar documentos fuente completos. El proyecto comienza con un pequeño prototipo local y luego aplica el mismo contrato de herramientas a la recuperación semántica desde un almacén de vectores de OpenAI.

Qué demuestra esto

• Diseño de herramientas MCP con responsabilidades reducidas de search y fetch

• Entradas y salidas estructuradas mediante FastMCP y Pydantic

• Recuperación semántica sobre documentos subidos a un almacén de vectores de OpenAI

• Deduplicación a nivel de documento cuando la búsqueda vectorial devuelve varios fragmentos coincidentes

• Transportes MCP HTTP transmisible y stdio

• Uso integral de herramientas a través de la API de Respuestas de OpenAI y un túnel MCP seguro

• Configuración mediante variables de entorno, sin credenciales en el código fuente

• Pruebas unitarias y a nivel de protocolo que no realizan llamadas de pago a la API

Related MCP server: File AI

Arquitectura

OpenAI Responses API
        |
        | MCP tool calls through an outbound secure tunnel
        v
Local FastMCP server (Streamable HTTP)
        |
        | vector-store search and file retrieval
        v
OpenAI vector store -> uploaded documents

El repositorio también incluye una ruta de aprendizaje totalmente local:

Local demo client -> FastMCP server (stdio) -> data/documents.json

Ambos servidores exponen el mismo contrato público de herramientas:

Mantener la detección separada de la recuperación evita enviar documentos completos antes de que sean necesarios y proporciona al modelo identificadores de documento estables para usar en llamadas posteriores.

Estructura del proyecto

.
├── data/documents.json                   # Sample local knowledge base
├── sample_data/cats.pdf                  # Public-domain vector-store sample
├── src/mcp_knowledge_assistant/
│   ├── knowledge_base.py                 # Local keyword retrieval
│   ├── models.py                         # Shared response schemas
│   ├── server.py                         # Local stdio MCP server
│   └── vector_store_server.py            # OpenAI vector-store MCP server
├── tests/                                # Offline unit and MCP tests
├── demo_client.py                        # Local stdio demonstration
├── vector_store_demo_client.py           # Direct HTTP MCP demonstration
└── api_client.py                         # Responses API + secure tunnel demonstration

Requisitos

• Python 3.11 o superior

• Un proyecto de API de OpenAI con facturación habilitada para la ruta del almacén de vectores

• El PDF de muestra incluido, o su propio documento, subido a un almacén de vectores de OpenAI

• El cliente de túnel de OpenAI solo para la demostración del túnel seguro

El servidor JSON local y el conjunto completo de pruebas no requieren clave de API.

Atribución del documento de muestra

La demostración del almacén de vectores utiliza Cats: Their Points and Characteristics de W. Gordon Stables, eBook #43429 del Proyecto Gutenberg. El PDF de muestra está alojado por OpenAI y se produjo a partir de la edición del Proyecto Gutenberg. Consulte el PDF para conocer la licencia del Proyecto Gutenberg y los términos de reutilización aplicables.

Configuración

Clone el repositorio, cree un entorno virtual e instale el proyecto:

python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

Para los ejemplos respaldados por OpenAI, copie la plantilla de entorno:

cp .env.example .env.local

Luego agregue sus propios valores a .env.local:

OPENAI_API_KEY=your_project_api_key
VECTOR_STORE_ID=vs_your_vector_store_id

.env.local, la configuración de PyCharm, los entornos virtuales y los perfiles de túnel locales están excluidos de Git.

1. Ejecutar el prototipo local

El primer servidor usa stdio, por lo que el cliente MCP lo inicia como un proceso hijo y se comunica a través de la entrada y salida estándar:

python demo_client.py

La demostración detecta ambas herramientas, busca en la base de conocimiento JSON de muestra y recupera el documento seleccionado.

También puede iniciar el servidor mediante su comando instalado:

mcp-knowledge-assistant

Un proceso silencioso en espera es normal para un servidor stdio que no tiene ningún cliente conectado.

2. Ejecutar el servidor del almacén de vectores

Suba sample_data/cats.pdf a un almacén de vectores de OpenAI y luego establezca OPENAI_API_KEY y VECTOR_STORE_ID en .env.local. Puede sustituir su propio documento y consulta si lo prefiere. Inicie el servidor HTTP transmisible:

mcp-vector-store-assistant

Por defecto, su punto final MCP es:

http://127.0.0.1:8000/mcp

En una segunda terminal, pruebe el punto final directamente:

python vector_store_demo_client.py

La búsqueda vectorial opera sobre fragmentos, por lo que un documento largo puede producir varias coincidencias con el mismo ID de archivo. La herramienta MCP search colapsa deliberadamente esas coincidencias en un único resultado de documento. La herramienta fetch recupera y combina el contenido analizado de ese documento para el modelo.

3. Llamarlo a través de la API de Respuestas

Siga la guía de túneles MCP seguros de OpenAI para crear un túnel, configure su perfil local ignorado para que apunte a http://127.0.0.1:8000/mcp e inicie el cliente de túnel. Agregue el ID resultante a .env.local:

MCP_TUNNEL_ID=tunnel_your_tunnel_id

El cliente de túnel lee su propia credencial de tiempo de ejecución de CONTROL_PLANE_API_KEY. Mantenga ese valor también local. Con el servidor de vectores y el cliente de túnel ambos en ejecución, ejecute:

python api_client.py

La solicitud a la API de Respuestas declara únicamente las herramientas MCP de solo lectura search y fetch. El modelo puede buscar, recuperar una fuente seleccionada y componer una respuesta a partir del contenido recuperado.

Pruebas

Ejecute todas las pruebas con:

pytest

Las pruebas cubren la clasificación y recuperación local, la detección de herramientas MCP, la deduplicación de resultados vectoriales, el ensamblaje de contenido y la validación de entradas. Las llamadas a OpenAI están simuladas, por lo que el conjunto es repetible y no consume créditos de API.

Decisiones de diseño y alcance

• Solo lectura primero: ninguna herramienta MCP modifica archivos o estado externo.

• Contrato de compatibilidad estable: search(query) devuelve referencias de documentos; fetch(id) devuelve contenido completo y metadatos.

• Resultados de documentos, no resultados de fragmentos: los fragmentos son evidencia de recuperación dentro del almacén de vectores, mientras que el cliente MCP recibe IDs de archivo estables.

• MCP es una capa de abstracción: para un único almacén de vectores alojado en OpenAI, la herramienta File Search integrada de la API de Respuestas es más simple. MCP resulta útil cuando la misma interfaz de recuperación debe atender a múltiples clientes, ocultar detalles del backend, o agregar posteriormente autorización y lógica de dominio.

• Límite de integración verificado: los servidores locales, los clientes MCP directos y la ruta de la API de Respuestas a través del túnel seguro se probaron durante el desarrollo. Este repositorio no afirma tener un servidor público implementado ni una aplicación ChatGPT publicada.

Notas de seguridad

• Nunca confirme .env.local, claves de API, claves de tiempo de ejecución del túnel o IDs de organización.

• Use credenciales con alcance de proyecto y otorgue únicamente los permisos necesarios.

• Mantenga el servidor MCP local vinculado detrás del túnel saliente seguro en lugar de abrir un puerto de firewall entrante.

• Revise los permisos de las herramientas antes de agregar cualquier acción de escritura o de consecuencias.

Referencias

• Guía MCP de OpenAI

• Guía de File Search de OpenAI

• Guía de túneles MCP seguros de OpenAI

• Documentación de FastMCP