RAG Blob MCP

Un servidor de Model Context Protocol (MCP) que proporciona a un agente RAG acceso de búsqueda a una biblioteca de documentos almacenada en Azure Blob Storage, además de una aplicación Streamlit para subir documentos y chatear con ellos.

• Servidor MCP — FastMCP sobre Streamable HTTP, gestiona todo el acceso a Azure Blob Storage, expone 4 herramientas y 3 plantillas de prompt, mantiene un índice vectorial en memoria (embeddings de OpenAI) reconstruido desde Blob Storage en cada inicio.

• Aplicación Streamlit — una pestaña Biblioteca (subir / listar / eliminar documentos) y una pestaña Chat (hacer preguntas, respondidas por un agente LangGraph ReAct que llama a la herramienta de búsqueda del servidor).

Inicio rápido

1. Requisitos previos

• Python 3.11+ (desarrollado contra 3.13)

• Una cuenta de Azure Storage con un contenedor de blobs (consulta Configuración de Azure a continuación si no tienes una)

• Una clave de API de OpenAI

2. Instalación

Desde la raíz del repositorio:

python -m venv .venv
.venv\Scripts\activate          # Windows
pip install -r requirements.txt

3. Configuración

Copia .env.example (en la raíz del repositorio) a .env y completa tus valores:

OPENAI_API_KEY=sk-...
AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;EndpointSuffix=core.windows.net
AZURE_STORAGE_CONTAINER_NAME=rag-documents

Todo lo demás (OPENAI_MODEL, OPENAI_EMBEDDING_MODEL, MCP_SERVER_HOST/PORT/URL) tiene un valor predeterminado funcional — consulta Configuración.

4. Ejecución

Dos procesos, dos terminales, ambos desde la raíz del repositorio:

# Terminal 1 — MCP server
python server/mcp_server.py

# Terminal 2 — Streamlit app
streamlit run app/streamlit_app.py

Abre http://localhost:8501. Sube un archivo PDF/DOCX/TXT/MD en la pestaña Biblioteca y luego haz una pregunta sobre él en la pestaña Chat.

Related MCP server: Legal MCP Server

Configuración de Azure

Si aún no tienes una cuenta de Storage:

1. Azure Portal → Crear un recurso → Cuenta de almacenamiento. Rendimiento estándar, redundancia LRS es suficiente para uso personal.

2. En la nueva cuenta: Almacenamiento de datos → Contenedores → + Contenedor, asígnale un nombre (por ejemplo, rag-documents), nivel de acceso Privado.

3. Seguridad y redes → Claves de acceso → Mostrar claves, copia la cadena de conexión.

4. Pégala en .env como AZURE_STORAGE_CONNECTION_STRING, y establece AZURE_STORAGE_CONTAINER_NAME con el nombre del contenedor que elegiste.

Estructura del proyecto

.
├── server/
│   ├── mcp_server.py      # FastMCP server: tools, prompts, index rebuild, __main__ entrypoint
│   ├── blob_store.py      # Azure Blob Storage wrapper
│   ├── indexing.py        # text extraction (pdf/docx/txt/md) + chunking
│   ├── vector_index.py    # in-memory vector store wrapper
│   └── test_*.py          # automated tests (pytest)
├── agent/
│   └── rag_agent.py       # LangGraph ReAct agent used by the Chat tab
├── app/
│   ├── mcp_client.py      # direct MCP tool-call helpers used by the Library tab
│   └── streamlit_app.py   # the UI
├── scripts/
│   └── smoke_test_server.py  # manual end-to-end smoke test against a running server
├── docs_build/            # scripts that generate PROJECT.docx / PROJECT.pdf
└── pytest.ini

Configuración

Todas las variables están en el .env de la raíz del repositorio:

Uso

Pestaña Biblioteca — sube archivos PDF/DOCX/TXT/MD (límite de 200MB, establecido por Streamlit). Cada subida se divide en fragmentos, se incrusta y se añade al índice de búsqueda; la lista de documentos muestra el estado indexed / failed / pending con recuentos de fragmentos. Eliminar quita un documento tanto de Blob Storage como del índice.

Pestaña Chat — haz una pregunta en inglés sencillo. El agente decide cuándo llamar a la herramienta de búsqueda, recupera los fragmentos relevantes y responde citando el documento fuente por nombre de archivo. Con una biblioteca vacía o irrelevante, lo dice en lugar de adivinar.

Pruebas

pytest server/ -v

29 pruebas cubren la extracción/división de texto, el índice vectorial, el envoltorio de Azure Blob Storage (simulado) y las 4 herramientas MCP + prompts (a través de fastmcp.Client en proceso, usando fakes — sin llamadas reales a Azure/OpenAI). No hay cobertura automatizada para la interfaz de Streamlit ni para el cableado del agente/servidor en vivo; consulta scripts/smoke_test_server.py para una prueba de humo manual contra un servidor real en ejecución.

Limitaciones conocidas

• Índice en memoria, sin persistencia. Cada reinicio del servidor vuelve a descargar, extraer e incrustar cada documento del contenedor. Aceptable para una biblioteca personal pequeña; cuesta llamadas reales a la API de OpenAI y tiempo de inicio a medida que la biblioteca crece.

• Un solo usuario, solo local. Sin autenticación, sin seguridad de escritura concurrente, no desplegado en ningún sitio.

• Ambos procesos (servidor MCP, aplicación Streamlit) deben estar en ejecución para que la aplicación funcione — consulta el documento completo del proyecto para más detalles.

Para la imagen completa — arquitectura, decisiones de diseño, errores conocidos y próximos pasos — consulta PROJECT.md (también disponible como PROJECT.docx / PROJECT.pdf).