Quaestio MCP Server

Der Quaestio ist ein Server für Model Context Protocol (MCP) zur Analyse, Lösung und Verifizierung von Fragen. Er stellt MCP-Werkzeuge bereit, damit ein kompatibler Host Fragen, Anhänge und Studienmaterialien senden und strukturierte, nachvollziehbare und vorsichtige Ergebnisse erhalten kann.

Der Server ist weder eine Benutzeroberfläche noch ein Sprachmodell. Er ist die MCP-Schicht, die den Eingabevertrag organisiert, die konfigurierten Komponenten aufruft, die Antworten validiert und dem Client eine strukturierte Entscheidung zurückgibt.

Was ist MCP in diesem Projekt

MCP ist ein offenes Protokoll, um Host-Anwendungen mit Servern zu verbinden, die Werkzeuge und Daten standardisiert bereitstellen. Bei 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

Der MCP-Server stellt derzeit die Primitive tools bereit. Er veröffentlicht resources, resource templates oder prompts nicht als separate MCP-Primitive. Materialien, OCR, PDFs und Serverfähigkeiten werden über Werkzeuge zugänglich gemacht.

Verwendete Protokollreferenzen:

• MCP – offizielle Dokumentation;

• MCP-Spezifikation 2026-07-28;

• Server-Discovery;

• Werkzeug-Spezifikation;

• Stdio-Spezifikation;

• Offizielles Python SDK;

• Offizielle Referenzserver.

Funktionen

• Multiple-Choice- und offene Fragen lösen;

• Fragen mit Inline-Bildern verarbeiten;

• Konsens zwischen zwei konfigurierbaren LLM-Backends ausführen;

• nicht-englische Fragen für die konfigurierten Modelle aufbereiten;

• Alternativen, Indizes, Formeln, Code und Anhänge bewahren;

• einen Vorschlag strukturell und, wenn konfiguriert, semantisch verifizieren;

• optionale deterministische und symbolische mathematische Verifikation anwenden;

• lokale Studienmaterialien hinzufügen und durchsuchen;

• semantische Embeddings mit Fallback auf TF-IDF verwenden;

• Text aus Bildern mit Tesseract extrahieren;

• Text aus PDFs extrahieren und interpretieren;

• Code analysieren, ohne ihn auszuführen;

• Syntax kompilieren/prüfen, ohne den Code auszuführen;

• Python oder JavaScript nur in einer Docker-Sandbox ausführen;

• Stapel mit Lösungsschlüssel auswerten und Metriken berechnen;

• einen trace der ausgeführten Schritte zurückgeben.

Zuverlässigkeitsprinzipien

Der Server ist so konzipiert, dass er explizit fehlschlägt, wenn keine ausreichende Evidenz vorliegt.

• Fehlen eines Backends oder eines gültigen Vorschlags führt zu needs_review;

• Uneinigkeit zwischen den Modellen wird nicht stillschweigend aufgelöst;

• semantische Verifikation wird nicht als deterministischer Beweis behandelt;

• verified ist zuverlässiger Evidenz wie deterministischen mathematischen Prüfungen vorbehalten;

• das von einem Modell angegebene Vertrauen wird vom Server begrenzt;

• Eingaben, Anhänge, Kontext und abgerufene Materialien werden als unzuverlässige Daten behandelt, niemals als Systemanweisungen;

• Fehler externer Anbieter werden in Warnungen und strukturierte Zustände umgewandelt;

• der Server sollte nicht verwendet werden, um eine LLM-Antwort als Garantie für Korrektheit zu betrachten.

Interne Architektur

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

Die wichtigsten internen Komponenten sind:

• models.py: kanonische Verträge und öffentliche Zustände;

• mcp_server.py: Registrierung, Dispatch und MCP-Transport;

• service.py: Orchestrierung der Pipeline;

• backends.py: deterministische Backends, LLM, Übersetzung und Konsens;

• verification.py: strukturelle und mathematische Validierungen;

• semantic_verifier.py: optionale unabhängige semantische Prüfung;

• knowledge.py und embeddings.py: lokale Basis und semantische Suche;

• ocr.py und pdf.py: lokale Inhaltsextraktion;

• sandbox.py: kontrollierte Codeausführung in Docker.

Transport und MCP-Zyklus

Der primäre Transport ist stdio, geeignet für lokale Server. Der Host startet den Prozess und kommuniziert über stdin und stdout mit ihm; jede Nachricht ist JSON-RPC. Startprotokolle werden an stderr gesendet, um den MCP-Kanal nicht zu beschädigen.

Der Server implementiert die modernen Abläufe:

1. server/discover – Ermittlung von Version, Identität, Fähigkeiten und Anweisungen;

2. tools/list – deterministische Ermittlung der Werkzeuge, Schemas und Cache;

3. tools/call – Ausführung eines Werkzeugs mit strukturiertem Ergebnis.

Wenn das offizielle Paket mcp installiert ist, verwendet der Server das moderne SDK mit stdio-Transport. Ohne das Paket verwendet er die minimale Stdio-Implementierung, die im Projekt enthalten ist. Beide Pfade registrieren denselben Satz von Werkzeugen und folgen dem modernen Vertrag. Jedes Werkzeug deklariert inputSchema und outputSchema; der minimale Stdio-Pfad validiert ebenfalls Argumente, bevor er den Handler ausführt.

Der Server startet keinen HTTP-Port. Streamable HTTP bleibt außerhalb des Umfangs dieser Version.

Installation

Voraussetzungen:

• Python 3.11 oder höher;

• pip;

• Zugangsdaten für einen LLM-Endpunkt, der mit der Chat-API von OpenAI kompatibel ist, für die unterstützte Lösung;

• Tesseract, nur für lokale OCR;

• Docker und lokale Images, nur für run_code;

• pypdf, nur für die PDF-Extraktion.

Grundinstallation:

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

Optionale Extras:

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

Konfiguration

Kopieren Sie .env.example in .env und füllen Sie nur die Anbieter aus, die Sie verwenden möchten. Die .env sollte nicht versioniert oder geteilt werden.

LLM-Lösung

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

Dies ist das Haupt-Backend. Wenn das zweite Backend vollständig konfiguriert ist, führt Quaestio einen Konsens durch:

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

Ohne Backend bleibt der Server verfügbar, aber Fragen, die nicht deterministisch gelöst werden können, geben needs_review zurück.

Sprachliche Vorbereitung

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

Verfügbare Modi:

• never: übersetzt nie;

• auto: übersetzt, wenn die Frage nicht auf Englisch ist;

• required: erfordert den Übersetzer, wenn eine Übersetzung notwendig ist.

Das Originalbild wird nicht verändert. Wenn OCR vorhanden ist, kann der erkannte Text als zusätzlicher Kontext verwendet werden, aber das Bild wird weiterhin als visueller Beleg gesendet.

Semantische Suche

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

Embeddings sind optional. Wenn sie nicht verfügbar sind, verwendet die lokale Basis TF-IDF. Die Basis speichert Materialien und Vektoren lokal; fügen Sie keine Inhalte hinzu, die nicht in dieser Datei persistiert werden können.

Unabhängige semantische Verifikation

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

Dieses Backend sollte vom Solver getrennt sein, wenn die Unabhängigkeit der Prüfung wichtig ist. Es gibt supports, contradicts oder uncertain zurück; es wandelt eine LLM-Antwort nicht in verified um.

Optionale lokale Ressourcen

QUAESTIO_TESSERACT_PATH=
QUAESTIO_DOCKER_PATH=
QUAESTIO_SANDBOX_PYTHON_IMAGE=python:3.12-slim

Die Docker-Sandbox lädt Images nicht automatisch herunter. Die Images müssen lokal vorhanden sein.

So starten Sie den Server

Nach der editierbaren Installation:

quaestio

Ohne editierbare Installation:

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

Der Prozess scheint auf Eingaben zu warten, weil der stdio-Transport vom MCP-Client gesteuert wird. Das ist das erwartete Verhalten.

Konfiguration in einem MCP-Client

Ein MCP-Host muss den Serverbefehl als Unterprozess starten. Generisches Beispiel für Windows:

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

Alternativ mit Python:

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

Umgebungsvariablen können über die lokale .env oder die Host-Konfiguration bereitgestellt werden. Bevorzugen Sie den Secret-Mechanismus des Hosts, wenn verfügbar, und nehmen Sie niemals echte Schlüssel in das Repository auf.

MCP-Werkzeuge

Lösung und Verifikation

Materialien und Abruf

Parsing, OCR und Dokumente

Für die visuelle Verarbeitung und OCR muss die Eingabe ein Inline-Bild in Base64 enthalten. URI-Referenzen werden im kanonischen Vertrag akzeptiert, aber der aktuelle OCR- und Multimodal-Sendefluss verwendet die Inline-Bytes.

Code

run_code führt keinen Code auf dem Host aus. Wenn Docker, Image oder Sprache nicht verfügbar sind, wird ein strukturierter Nichtverfügbarkeitsstatus zurückgegeben.

Diagnose

Eingabevertrag

Eine kanonische Frage kann wie folgt gesendet werden:

{
  "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": []
}

Hauptfelder:

• question: erforderlicher Text;

• options: optionale Liste mit mindestens zwei eindeutigen Alternativen;

• question_id: Kennung, die in Stapeln beibehalten wird;

• context: zusätzlicher Kontext oder abgerufenes Material;

• attachments: Bilder oder Dokumente, normalerweise mit mime_type und data_base64;

• expected_answer und expected_option_index: nur für die Auswertung mit Lösungsschlüssel, nicht zur Steuerung des Solvers.

Ausgabevertrag

Eine Antwort enthält unter anderem folgende Felder:

{
  "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": []
}

Status der Antwort

• verified: ausreichende deterministische Evidenz;

• answered: ein Vorschlag wurde erzeugt, aber es gibt keinen deterministischen Beweis;

• needs_review: es fehlten Konsens, Evidenz oder Validierung;

• error: Fehler in der Pipeline.

Das Feld correct wird nur gefüllt, wenn der Client einen Lösungsschlüssel über expected_answer oder expected_option_index bereitstellt.

Beispiel für einen MCP-Aufruf

Nach server/discover kann der Client Folgendes aufrufen:

{
  "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"]
    }
  }
}

Das MCP-Ergebnis enthält serialisierten Textinhalt und structuredContent für Clients, die strukturierte Ergebnisse unterstützen.

Entwicklung und Validierung

Führen Sie die automatisierte Testsuite aus mit:

pytest -q

Die Unit-Tests müssen ausgeführt werden, ohne von tatsächlichen Aufrufen an die Anbieter abzuhängen. Smoke-Tests gegen externe APIs müssen explizit sein und lokale Anmeldedaten sowie autorisierte Abfragen verwenden.

Verwandte technische Dokumentation:

• Spezifikation und Plan für mehrsprachige Vorbereitung / Plan;

• Spezifikation der Testisolierung / Plan;

• Spezifikation für den NIM-Smoke-Test / Plan;

• Spezifikation für multimodale Bewertung / Plan;

• Spezifikation für Embeddings / Plan;

• Spezifikation des multimodalen Verifizierers / Plan;

• Spezifikation für Benchmark und Konfidenz / Plan.

Aktuelle Einschränkungen

• Öffentlicher HTTP-Transport ist noch nicht implementiert;

• der Server stellt keine MCP-Resources oder -Prompts bereit;

• der semantische Verifizierer akzeptiert Inline-Bilder; externe URIs, PDFs und Videos werden in dieser Phase noch nicht gesendet;

• der Embedding-Index erfordert eine Neuindizierung, wenn das konfigurierte Modell gewechselt wird;

• OCR und PDF-Extraktion hängen von optionalen lokalen Installationen ab;

• Konsens und semantische Überprüfung reduzieren das Risiko, ersetzen jedoch weder Referenzlösung, formalen Beweis noch menschliche Überprüfung.