pilot-training-rag
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pilot-training-rag Find the exact citation for Level D FFS QPS requirements in 14 CFR Part 60."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
pilot-training-rag
Corpus de instrucción de pilotos y simulación, indexado para que un agente pueda responder con cita exacta («14 CFR § 60.15(b)(1)», «Doc 9995 › Chapter 3 › 3.1 BACKGROUND», «p. 3-7»), y un servidor MCP que lo expone a cualquier cliente (Claude Desktop, Cursor, Hermes…).
Sin vector DB, sin embeddings obligatorios, sin servicios en la nube: SQLite + FTS5 y tres ficheros de Python. 9 documentos, 2.012 páginas, 6.179 fragmentos, 11 segundos de ingesta y 16 MB de índice.
raw/ 9 PDF/XML (descargables con scripts/fetch.py, no versionados)
src/pilot_rag/ ingesta, índice, búsqueda, árbol y servidor MCP
scripts/ CLI: fetch, ingest, build_tree, ask, eval, smoke_mcp
eval/ 21 preguntas con cita esperada + arnés de evaluación
data/ corpus.db + árboles (generados)
pageindex/ variante on-premise con PageIndex (opcional)
docs/ arquitectura, MCP, licencias, PageIndexArranque rápido
Requisitos: Python ≥ 3.10, pdftotext y qpdf (poppler / qpdf).
git clone https://github.com/fmanso/pilot-training-rag && cd pilot-training-rag
python3 scripts/fetch.py # ~490 MB (o sin --all: solo los pequeños)
python3 scripts/ingest.py # 11 s -> data/corpus.db
python3 scripts/build_tree.py # árboles navegables por documento
python3 scripts/eval.py # métricas de recuperación
python3 scripts/ask.py "¿Quién firma la declaración inicial de un FSTD?"scripts/ask.py no redacta respuestas: devuelve fragmentos con su cita. La
redacción es del agente. Es deliberado — así la capa de recuperación no puede
alucinar y el agente siempre tiene el texto fuente delante.
Related MCP server: PDF-RAG
Qué hay dentro
Documento | Aporta | Jurisdicción |
14 CFR Part 60 + apéndices A–F | QPS: tareas vs nivel de dispositivo, tolerancias, tests objetivos | FAA |
AC 120-54A Chg 1 | Diseño instruccional de programas de simulador (AQP, ISD, LOE) | FAA |
Aviation Instructor's Handbook (8083-9B) | Pedagogía: aprendizaje, enseñanza, evaluación | FAA |
Airplane Flying Handbook (8083-3C) | Maniobras y procedimientos | FAA |
Pilot's Handbook of Aeronautical Knowledge (8083-25C) | Teoría y sistemas | FAA |
Doc 9868 PANS-TRG | Formación por competencias y cualificación de instructores | ICAO |
Doc 9995 EBT | Competencias EBT, escenarios, grading | ICAO |
CS-FSTD(A) + AMC/GM | Niveles FFS A–D, FTD, FNPT, BITD | EASA |
EASA EBT Manual | Implementación práctica de EBT en la UE | EASA |
Los PDFs no se versionan (licencias, ver docs/LICENSING.md); sources.json
tiene URL, tamaño, licencia y para qué sirve cada uno.
Por qué recupera bien (y dónde no)
El corpus está en inglés y las preguntas llegan en castellano. BM25 no cruza
idiomas, así que el repo lleva un léxico de dominio ES→EN (src/pilot_rag/text.py)
que expande la consulta. Eso es lo que mueve la aguja:
configuración | hit@1 | hit@5 | MRR@10 | documento correcto |
BM25 puro | 0.33 | 0.38 | 0.363 | 0.47 |
BM25 + expansión léxica | 0.57 | 0.90 | 0.737 | 1.00 |
híbrido (expansión + rerank + atajo estructural) | 0.57 | 0.90 | 0.737 | 1.00 |
21 preguntas, python3 scripts/eval.py --verbose para ver cada fallo.
Dos cosas que sí aportan estructura:
Chunks con ruta de cita en vez de ventanas ciegas: el XML del eCFR ya trae la jerarquía (
§ 60.15→(b)→(1)), y los PDFs se parten por sus marcadores o por la numeración «capítulo-página» de la FAA.Atajo estructural: si la pregunta cita una sección o tabla («60.25», «Tabla A1B»), esa sección va primera aunque el texto no repita las palabras.
Y una que no: el rerank léxico empata con BM25 en este conjunto. Se mantiene porque es donde se inyectan señales que FTS5 no expresa (cobertura ponderada por IDF, frase exacta, coincidencia de cita) sin tocar la consulta.
Limitaciones conocidas: preguntas puramente semánticas («¿cada cuánto se
revisa?» cuando el texto dice «four evenly spaced inspections») siguen fallando;
el AC 120-54A trae algunos títulos de sección que vienen del índice embebido del
PDF y no del texto (la cita de página sigue siendo correcta). Para eso está
docs/PAGEINDEX.md: recuperación por razonamiento sobre el árbol, a cambio de un
LLM por consulta.
MCP
python3 -m pilot_rag.mcp_server # stdio
PILOT_RAG_TRANSPORT=http python3 -m pilot_rag.mcp_server # streamable-httpSeis herramientas: search_corpus, lookup_citation, get_chunk,
get_document_structure, get_page_content, list_documents.
Claude Desktop / Cursor / Hermes: ver docs/MCP.md (configuración lista para
copiar, contratos de cada tool y el prompt de sistema recomendado).
Verificación real de que habla MCP:
$ python3 scripts/smoke_mcp.py
servidor: pilot-training-rag v1.0.0
tools (6): list_documents, search_corpus, get_chunk, lookup_citation, get_document_structure, get_page_content
search_corpus -> 3 resultados
lookup_citation('60.19') -> 16 chunks; primero: 14 CFR § 60.19
get_document_structure -> 109 nodos de nivel<=2
SMOKE: OKPageIndex on-premise
pageindex/ monta el árbol con la librería real de PageIndex (MIT) contra un
endpoint compatible con OpenAI — Ollama, vLLM o cualquier API. Nuestro
get_document_structure devuelve el mismo contrato (title / start_index /
end_index / summary / nodes), así que un agente puede cambiar de motor sin tocar
el prompt. Detalles y veredicto en docs/PAGEINDEX.md.
Licencia
Código MIT (LICENSE). Los documentos conservan la suya: FAA es dominio público,
EASA permite reutilización con atribución, ICAO está bajo copyright — por eso el
repo trae descargadores, no PDFs. docs/LICENSING.md lo detalla documento a documento.
Available Tools
6 toolsget_chunkC
Devuelve un fragmento y sus contiguos (más contexto).
Inputs: chunk_id (required), neighbours.
get_document_structureC
Árbol de secciones del documento, con páginas y resumen de cada nodo.
Inputs: doc_id (required), max_level.
get_page_contentC
Texto de un rango de páginas, p. ej. pages='12-14'.
Inputs: pages (required), doc_id (required). Returns: result
list_documentsC
Documentos disponibles, jurisdicción y número de fragmentos.
Inputs: no named parameters. Returns: result
lookup_citationC
Acceso estructural: '60.15', '§ 60.25(b)', 'App. A', 'Table A1B'.
Inputs: citation (required). Returns: result
search_corpusA
Busca en el corpus (castellano o inglés) y devuelve fragmentos citables.
Args: query: pregunta o palabras clave, en cualquier idioma. k: número de fragmentos (1-20). doc_ids: opcional, limita a esos documentos.
Inputs: query (required), k, doc_ids. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
The tools are mostly clearly separated by purpose: corpus search, citation lookup, chunk retrieval, document listing, structure browsing, and page extraction. There is minor overlap between get_chunk and get_page_content as context-expansion tools, and between search_corpus and lookup_citation as retrieval paths, but descriptions make the intended use reasonably clear.
All tool names follow a consistent snake_case verb_noun pattern: list_documents, search_corpus, get_chunk, lookup_citation, get_document_structure, get_page_content. The verb choices vary appropriately by action while maintaining a predictable convention.
Six tools is well-scoped for a RAG retrieval server. Each tool has a distinct retrieval role: discovery, search, chunk context, citation lookup, structure navigation, and page extraction.
The surface covers the core RAG retrieval lifecycle: discovering documents, searching, expanding chunks, resolving citations, inspecting structure, and reading page ranges. Minor gaps exist, such as no explicit document-level metadata retrieval beyond list_documents, but these are not likely to block most agent workflows.
Maintenance
Related MCP Connectors
Free no-key search over CASA, FAA, EASA & ICAO aviation regulations. By Deepsky (deepskyai.com).
Page-cited retrieval for embedded docs, datasheets, MISRA, CMSIS, and RTOS references.
SEC filings, Wikipedia, arXiv, US Census and more for AI agents, with every answer source-linked.
License-checked research archive and technical-spec search for AI agents. Pay per call via x402.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables semantic retrieval over locally indexed PDF manuals and books, exposing tools to list available sources and search excerpts by query with page, chapter, source, and relevance metadata.2MIT
- AlicenseNot gradedqualityBmaintenanceEnables agents to search local component-manual corpora via hybrid semantic, full-text, and substring retrieval with table recognition and OCR fallback for scanned pages. Provides tools for literal/regex grepping, reading single or multiple pages, navigating bookmarks and outlines, listing categories and indexed files, and checking index and dependency status.AGPL 3.0
- AlicenseNot gradedqualityCmaintenanceEnables agents to search a curated catalog of practical AI books and retrieve book records, topics, reading paths, free chapters, glossary definitions, and verified claim citations. It also supports checking claims and generating citations from the catalog’s published free material.MIT
- AlicenseAqualityCmaintenanceExposes seven read-only tools that let an existing chat model search a private, incrementally ingested PDF library, fetch full parent sections with provenance and hash validation, check evidence completeness, audit literal quote anchors, view original PDF pages, and explore a frozen citation snapshot. It provides source-first retrieval and provenance without invoking another model or certifying scientific conclusions.71MIT