Quaestio MCP Server

El Quaestio es un servidor Model Context Protocol (MCP) para análisis, resolución y verificación de preguntas. Expone herramientas MCP para que un host compatible pueda enviar preguntas, adjuntos y materiales de estudio y recibir resultados estructurados, trazables y conservadores.

El servidor no es una interfaz de usuario ni un modelo de lenguaje. Es la capa MCP que organiza el contrato de entrada, llama a los componentes configurados, valida las respuestas y devuelve una decisión estructurada al cliente.

Qué es MCP en este proyecto

MCP es un protocolo abierto para conectar aplicaciones host a servidores que ofrecen herramientas y datos de forma estandarizada. En Quaestio:

host MCP / cliente MCP
          │
          │ transporte stdio + JSON-RPC
          ▼
Quaestio MCP Server
          │
          ├── ferramentas de resolução e verificação
          ├── parsing, OCR e PDF
          ├── materiais de estudo e busca semântica
          ├── análise e execução controlada de código
          └── políticas de confiabilidade e auditoria

El MCP Server actualmente expone la primitiva tools. No publica resources, resource templates ni prompts como primitivas MCP separadas. Los materiales, OCR, PDFs y capacidades del servidor se acceden mediante herramientas.

Referencias de protocolo utilizadas:

• MCP — documentación oficial;

• especificación MCP 2026-07-28;

• descubrimiento del servidor;

• especificación de herramientas;

• especificación de stdio;

• Python SDK oficial;

• servidores de referencia oficiales.

Capacidades

• resolver preguntas de opción múltiple y abiertas;

• procesar preguntas con imágenes inline;

• ejecutar consenso entre dos backends LLM configurables;

• preparar preguntas no inglesas para los modelos configurados;

• preservar alternativas, índices, fórmulas, código y adjuntos;

• verificar estructuralmente y, cuando está configurado, semánticamente una propuesta;

• aplicar verificación matemática determinista y simbólica opcional;

• añadir y buscar materiales de estudio locales;

• usar embeddings semánticos con fallback a TF-IDF;

• extraer texto de imágenes con Tesseract;

• extraer e interpretar texto de PDFs;

• analizar código sin ejecutarlo;

• compilar/verificar sintaxis sin ejecutar el código;

• ejecutar Python o JavaScript solo en sandbox Docker;

• evaluar lotes con clave de respuestas y calcular métricas;

• devolver un trace de los pasos ejecutados.

Principios de confiabilidad

El servidor está diseñado para fallar de forma explícita cuando no hay evidencia suficiente.

• la ausencia de backend o de propuesta válida resulta en needs_review;

• el desacuerdo entre los modelos no se resuelve silenciosamente;

• la verificación semántica no se trata como prueba determinista;

• verified está reservado para evidencia confiable, como verificaciones matemáticas deterministas;

• la confianza declarada por un modelo está limitada por el servidor;

• las entradas, adjuntos, contexto y materiales recuperados se tratan como datos no confiables, nunca como instrucciones del sistema;

• las fallas de proveedores externos se convierten en avisos y estados estructurados;

• el servidor no debe usarse para considerar una respuesta de LLM como garantía de corrección.

Arquitectura interna

tools/call
   │
   ▼
MCP boundary
   │  valida argumentos e serializa resultado
   ▼
QuaestioService
   ├── classificação
   ├── recuperação de materiais
   ├── preparação linguística/OCR
   ├── solver determinístico ou LLM
   ├── consenso
   ├── verificação estrutural/semântica
   └── avaliação e trace

Los principales componentes internos son:

• models.py: contratos canónicos y estados públicos;

• mcp_server.py: registro, despacho y transporte MCP;

• service.py: orquestación del pipeline;

• backends.py: backends deterministas, LLM, traducción y consenso;

• verification.py: validaciones estructurales y matemáticas;

• semantic_verifier.py: revisión semántica independiente opcional;

• knowledge.py y embeddings.py: base local y recuperación semántica;

• ocr.py y pdf.py: extracción local de contenido;

• sandbox.py: ejecución controlada de código en Docker.

Transporte y ciclo MCP

El transporte principal es stdio, adecuado para servidores locales. El host inicia el proceso y se comunica con él mediante stdin y stdout; cada mensaje es JSON-RPC. Los registros de inicialización se envían a stderr para no corromper el canal MCP.

El servidor implementa los flujos modernos:

1. server/discover — descubrimiento de la versión, identidad, capacidades e instrucciones;

2. tools/list — descubrimiento determinista de las herramientas, esquemas y caché;

3. tools/call — ejecución de una herramienta con resultado estructurado.

Cuando el paquete oficial mcp está instalado, el servidor utiliza el SDK moderno con transporte stdio. Sin el paquete, utiliza la implementación stdio mínima incluida en el proyecto. Ambos caminos registran el mismo conjunto de herramientas y siguen el contrato moderno. Cada herramienta declara inputSchema y outputSchema; el camino stdio mínimo también valida argumentos antes de ejecutar el handler.

El servidor no inicia un puerto HTTP. Streamable HTTP permanece fuera del alcance de esta versión.

Instalación

Requisitos:

• Python 3.11 o superior;

• pip;

• credenciales de un endpoint LLM compatible con la API de chat de OpenAI para resolución asistida;

• Tesseract, solo para OCR local;

• Docker y imágenes locales, solo para run_code;

• pypdf, solo para extracción de PDFs.

Instalación básica:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

Extras opcionales:

pip install -e ".[sdk]"   # Python SDK oficial do MCP
pip install -e ".[math]"  # SymPy
pip install -e ".[pdf]"   # pypdf

Configuración

Copie .env.example a .env y complete solo los proveedores que desee utilizar. El .env no debe versionarse ni compartirse.

Resolución LLM

QUAESTIO_LLM_BASE_URL=https://integrate.api.nvidia.com/v1
QUAESTIO_LLM_API_KEY=...
QUAESTIO_LLM_MODEL=...
QUAESTIO_LLM_TIMEOUT_SECONDS=45

Este es el backend principal. Si el segundo backend está totalmente configurado, Quaestio ejecuta consenso:

QUAESTIO_SECONDARY_LLM_BASE_URL=https://integrate.api.nvidia.com/v1
QUAESTIO_SECONDARY_LLM_API_KEY=...
QUAESTIO_SECONDARY_LLM_MODEL=...

Sin backend, el servidor sigue disponible, pero las preguntas que no puedan resolverse deterministicamente devuelven needs_review.

Preparación lingüística

QUAESTIO_TRANSLATION_MODE=auto
QUAESTIO_TRANSLATION_TARGET_LANGUAGE=en
QUAESTIO_TRANSLATOR_BASE_URL=https://integrate.api.nvidia.com/v1
QUAESTIO_TRANSLATOR_API_KEY=...
QUAESTIO_TRANSLATOR_MODEL=...
QUAESTIO_TRANSLATOR_TIMEOUT_SECONDS=30
QUAESTIO_TRANSLATION_OCR=auto
QUAESTIO_TRANSLATION_OCR_LANGUAGE=por+eng

Modos disponibles:

• never: nunca traduce;

• auto: traduce cuando la pregunta no esté en inglés;

• required: exige el traductor cuando la traducción sea necesaria.

La imagen original no se altera. Cuando hay OCR, el texto reconocido puede usarse como contexto auxiliar, pero la imagen sigue enviándose como evidencia visual.

Búsqueda semántica

QUAESTIO_KNOWLEDGE_BASE_PATH=./data/knowledge.json
QUAESTIO_EMBEDDING_BASE_URL=https://integrate.api.nvidia.com/v1
QUAESTIO_EMBEDDING_API_KEY=...
QUAESTIO_EMBEDDING_MODEL=...
QUAESTIO_EMBEDDING_TIMEOUT_SECONDS=30

Los embeddings son opcionales. Cuando no están disponibles, la base local usa TF-IDF. La base almacena materiales y vectores localmente; no añada contenido que no pueda persistirse en ese archivo.

Verificación semántica independiente

QUAESTIO_VERIFIER_LLM_BASE_URL=https://integrate.api.nvidia.com/v1
QUAESTIO_VERIFIER_LLM_API_KEY=...
QUAESTIO_VERIFIER_LLM_MODEL=...
QUAESTIO_VERIFIER_LLM_TIMEOUT_SECONDS=45

Este backend debe estar separado del solver cuando la independencia de la revisión sea importante. Devuelve supports, contradicts o uncertain; no transforma una respuesta de LLM en verified.

Recursos locales opcionales

QUAESTIO_TESSERACT_PATH=
QUAESTIO_DOCKER_PATH=
QUAESTIO_SANDBOX_PYTHON_IMAGE=python:3.12-slim

El sandbox de Docker no descarga imágenes automáticamente. Las imágenes deben existir localmente.

Cómo iniciar el servidor

Después de la instalación editable:

quaestio

Sin instalación editable:

$env:PYTHONPATH = "src"
python -m quaestio.mcp_server

El proceso parece quedarse esperando entrada porque el transporte stdio está dirigido por el cliente MCP. Este es el comportamiento esperado.

Configuración en un cliente MCP

Un host MCP necesita iniciar el comando del servidor como subproceso. Ejemplo genérico para Windows:

{
  "mcpServers": {
    "quaestio": {
      "command": "C:\\caminho\\para\\Quaestio\\.venv\\Scripts\\quaestio.exe"
    }
  }
}

Alternativamente, usando Python:

{
  "mcpServers": {
    "quaestio": {
      "command": "C:\\caminho\\para\\Quaestio\\.venv\\Scripts\\python.exe",
      "args": ["-m", "quaestio.mcp_server"],
      "env": {
        "PYTHONPATH": "C:\\caminho\\para\\Quaestio\\src"
      }
    }
  }
}

Las variables de entorno pueden proporcionarse mediante el .env local o la configuración del host. Prefiera el mecanismo de secretos del host cuando esté disponible y nunca incluya claves reales en el repositorio.

Herramientas MCP

Resolución y verificación

Materiales y recuperación

Parsing, OCR y documentos

Para procesamiento visual y OCR, la entrada debe contener una imagen inline en base64. Las referencias URI se aceptan en el contrato canónico, pero el flujo actual de OCR y envío multimodal utiliza los bytes inline.

Código

run_code no ejecuta código en el host. Si Docker, la imagen o el lenguaje no están disponibles, devuelve un estado estructurado de indisponibilidad.

Diagnóstico

Contrato de entrada

Una pregunta canónica puede enviarse así:

{
  "question": "Qual é a capital do Brasil?",
  "options": ["Rio de Janeiro", "Brasília", "São Paulo"],
  "question_id": "q-001",
  "context": "Questão de geografia.",
  "attachments": []
}

Campos principales:

• question: texto obligatorio;

• options: lista opcional con al menos dos alternativas únicas;

• question_id: identificador preservado en lotes;

• context: contexto adicional o material recuperado;

• attachments: imágenes o documentos, normalmente con mime_type y data_base64;

• expected_answer y expected_option_index: solo para evaluación con clave de respuestas, no para orientar al solver.

Contrato de salida

Una respuesta contiene, entre otros campos:

{
  "question_type": "multiple_choice",
  "answer": "Brasília",
  "option_index": 1,
  "confidence": 0.75,
  "status": "answered",
  "method": "consensus",
  "verification": {
    "status": "answered",
    "verified": false,
    "semantic": {
      "status": "supports",
      "confidence": 0.91
    }
  },
  "sources": [],
  "warnings": [],
  "trace": []
}

Estado de la respuesta

• verified: evidencia determinista suficiente;

• answered: se produjo una propuesta, pero no hay prueba determinista;

• needs_review: faltó consenso, evidencia o validación;

• error: falla en el pipeline.

El campo correct solo se completa cuando el cliente proporciona una clave de respuestas mediante expected_answer o expected_option_index.

Ejemplo de llamada MCP

Después de server/discover, el cliente puede llamar:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": {"name": "example-client", "version": "1.0.0"},
      "io.modelcontextprotocol/clientCapabilities": {}
    },
    "name": "solve_question",
    "arguments": {
      "question": "Qual é a capital do Brasil?",
      "options": ["Rio de Janeiro", "Brasília", "São Paulo"]
    }
  }
}

El resultado MCP incluye contenido textual serializado y structuredContent para clientes que admiten resultados estructurados.

Desarrollo y validación

Ejecute la suite automatizada con:

pytest -q

Los tests unitarios deben ejecutarse sin depender de llamadas reales a los proveedores. Los smoke tests contra APIs externas deben ser explícitos, usando credenciales locales y preguntas autorizadas.

Documentación técnica relacionada:

• especificación y plan de preparación multilingüe / plan;

• especificación de aislamiento de tests / plan;

• especificación de smoke test NIM / plan;

• especificación de evaluación multimodal / plan;

• especificación de embeddings / plan;

• especificación del verificador multimodal / plan;

• especificación de benchmark y confianza / plan.

Límites actuales

• transporte público HTTP aún no está implementado;

• el servidor no expone resources ni prompts MCP;

• el verificador semántico acepta imágenes inline; URIs externos, PDFs y vídeo aún no se envían en esta etapa;

• el índice de embeddings exige reindexación cuando se cambia el modelo configurado;

• OCR y extracción de PDF dependen de instalaciones locales opcionales;

• el consenso y la revisión semántica reducen el riesgo, pero no sustituyen la clave de respuestas, la prueba formal ni la revisión humana.