BDC Doc RAG

El MCP RAG de documentación de bdc-assist

bdc_doc_mcp/config.py      env-driven embeddings/LLM/Chroma (replaces utils/__init__.set_emb_llm)
bdc_doc_mcp/ingest.py      .pkl/.md/.mdx/.txt/.pdf → embeddings → Chroma (replaces utils/chroma/utils.py)
bdc_doc_mcp/api.py         FastAPI: /health /search
bdc_doc_mcp/mcp_server.py  search_docs MCP tool for AI agents — self-contained, same search as the API
bdc_doc_mcp/preproc/       source-specific preprocessing pipeline
tests/                     self-checks + API / agent notebooks
data/                      preproc output (*.pkl), ingest input

Configuración

uv sync
cp .env.example .env    # then fill in keys/URLs

Repositorios fuente

Solo se necesitan para el preprocesamiento (--sources all); el servidor API/MCP y la ingesta de archivos .pkl existentes funcionan sin ellos. Clona junto a este repositorio (o apunta las variables de entorno a ellos):

git clone https://github.com/stagecc/interim-bdc-website ../interim-bdc-website   # BDC_WEBSITE_DIR
git clone https://github.com/stagecc/bdc-gitbook ../bdc-gitbook                   # BDC_GITBOOK_DIR

Modelos

Para la finalización, usa la API de OpenAI en Azure (gpt-4o-mini por defecto)

Para los embeddings, usa Ollama en Sterling (conéctate mediante la VPN de RENCI)

kubectl -n ner port-forward svc/ollama 11434:11434

O usando Ollama local con el modelo groonga/bge-m3-Q4_K_M-GGUF.

Related MCP server: okfy

Ingesta

Reconstrucción completa desde cada fuente (necesita los dos repositorios fuente clonados — ver Configuración; escribe data/*.pkl y luego los carga):

uv run python -m bdc_doc_mcp.preproc.pipeline --sources all --ingest --reset

Archivos o directorios individuales:

uv run python -m bdc_doc_mcp.ingest ./data/docs.pkl --doc-type docs   # BDC_Chatbot preproc .pkl
uv run python -m bdc_doc_mcp.ingest ../interim-bdc-website/src/pages --doc-type page --reset

Los modelos de embedding no son intercambiables dentro de una colección — bge-m3 es de 1024 dimensiones, text-embedding-3-small de 1536. Cambiar de modelo implica --reset y una re-ingesta completa.

API

uv run uvicorn bdc_doc_mcp.api:app --port 8000     # docs at /docs

mode es embedding (por defecto; similitud semántica, puntuación = distancia, menor es mejor) o keyword (coincidencia literal difusa de palabras — ignora mayúsculas/puntuación y tolera pequeños errores tipográficos, así que picsure encuentra "PIC-SURE"; puntuación = recuento de ocurrencias, mayor es mejor — úsalo para nombres/acrónimos exactos). doc_type es un CSV de tipos a buscar (p. ej. page,faq). Cuando se omite, solo se buscan docs, page, faq y video — nombra fellow, update o event explícitamente para buscarlos. date_from/date_to (YYYY-MM-DD, inclusive) filtran por fecha; solo los documentos de evento y actualización llevan fecha, por lo que un filtro de fecha se reduce implícitamente a esos tipos.

El servicio es solo de búsqueda por diseño; la ingesta ocurre sin conexión mediante la CLI (ver Ingesta) y responder es tarea del llamador — un agente trae su propio LLM.

MCP

uv run python -m bdc_doc_mcp.mcp_server           # stdio
uv run python -m bdc_doc_mcp.mcp_server --http    # streamable HTTP, port MCP_PORT (default 8001)

Expone una herramienta, search_docs — la misma búsqueda que la API pero consulta Chroma directamente, por lo que el servicio API no necesita ejecutarse. Necesita un .chroma_db ingerido + embeddings.

Los clientes Stdio (Claude Desktop/Code, Cursor) lanzan el servidor ellos mismos — regístralo:

{"mcpServers": {"bdc-doc-mcp": {
  "command": "uv",
  "args": ["--directory", "/path/to/bdc-doc-mcp", "run", "python", "-m", "bdc_doc_mcp.mcp_server"]
}}}

Clientes de red: ejecuta --http y apúntalos a http://host:8001/mcp en su lugar.

Prueba de humo: uv run python tests/test_mcp.py

Preprocesamiento

bdc_doc_mcp/preproc/ es el pipeline de BDC_Chatbot, portado:

--no-contextualize omite la llamada LLM por fragmento (mucho más rápido, recuperación más débil). Las rutas de origen provienen de BDC_WEBSITE_DIR / BDC_GITBOOK_DIR.

Pruebas

uv run python tests/test_ingest.py                             # batching + chunk-id logic, no network
uv run python tests/test_keyword.py                            # keyword ranking, pure function, no DB or API
uv run python tests/test_mcp.py                                # starts the server over stdio and exercises its tools; needs .chroma_db + embeddings

Notebooks (cada uno inicia la API en un puerto libre y la apaga al final; ambos necesitan un .chroma_db ingerido):

• tests/api_test.ipynb — recorrido simple de la API: /health, /search, filtro doc_type. Solo necesita los embeddings locales.

• tests/agent_test.ipynb — un agente que llama a herramientas (deepagents): el LLM configurado recibe search_docs como herramienta de LangChain y decide cuándo llamarla. También necesita que el proveedor de finalización sea accesible.