Quaestio MCP Server

Quaestio — это сервер Model Context Protocol (MCP) для анализа, решения и проверки вопросов. Он предоставляет инструменты MCP, позволяющие совместимому хосту отправлять вопросы, вложения и учебные материалы и получать структурированные, прослеживаемые и консервативные результаты.

Сервер не является пользовательским интерфейсом и не языковой моделью. Это слой MCP, который организует входной контракт, вызывает настроенные компоненты, проверяет ответы и возвращает клиенту структурированное решение.

Что такое MCP в этом проекте

MCP — это открытый протокол для подключения хост-приложений к серверам, предоставляющим инструменты и данные стандартизированным образом. В 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

MCP Server в настоящее время предоставляет примитив tools. Он не публикует resources, resource templates или prompts как отдельные примитивы MCP. Материалы, OCR, PDF-файлы и возможности сервера доступны через инструменты.

Используемые ссылки на протокол:

• MCP — официальная документация;

• спецификация MCP 2026-07-28;

• обнаружение сервера;

• спецификация инструментов;

• спецификация stdio;

• официальный Python SDK;

• официальные эталонные серверы.

Возможности

• решать вопросы с множественным выбором и открытые вопросы;

• обрабатывать вопросы со встроенными изображениями;

• выполнять консенсус между двумя настраиваемыми LLM-бэкендами;

• подготавливать неанглийские вопросы для настроенных моделей;

• сохранять альтернативы, индексы, формулы, код и вложения;

• проверять предложение структурно и, если настроено, семантически;

• применять детерминированную и опциональную символьную математическую проверку;

• добавлять и искать локальные учебные материалы;

• использовать семантические эмбеддинги с запасным вариантом TF-IDF;

• извлекать текст из изображений с помощью Tesseract;

• извлекать и интерпретировать текст из PDF-файлов;

• анализировать код без его выполнения;

• компилировать/проверять синтаксис без выполнения кода;

• выполнять Python или JavaScript только в Docker-песочнице;

• оценивать пакеты с ключом ответов и вычислять метрики;

• возвращать trace выполненных шагов.

Принципы надёжности

Сервер спроектирован так, чтобы явно сообщать об ошибке, когда недостаточно доказательств.

• отсутствие бэкенда или допустимого предложения приводит к needs_review;

• разногласие между моделями не разрешается молча;

• семантическая проверка не рассматривается как детерминированное доказательство;

• verified зарезервирован для надёжных доказательств, таких как детерминированные математические проверки;

• уверенность, заявленная моделью, ограничивается сервером;

• входные данные, вложения, контекст и извлечённые материалы рассматриваются как ненадёжные данные, а не как системные инструкции;

• сбои внешних провайдеров преобразуются в предупреждения и структурированные состояния;

• сервер не должен использоваться для того, чтобы считать ответ LLM гарантией правильности.

Внутренняя архитектура

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

Основные внутренние компоненты:

• models.py: канонические контракты и публичные состояния;

• mcp_server.py: регистрация, диспетчеризация и MCP-транспорт;

• service.py: оркестрация конвейера;

• backends.py: детерминированные бэкенды, LLM, перевод и консенсус;

• verification.py: структурные и математические проверки;

• semantic_verifier.py: опциональная независимая семантическая проверка;

• knowledge.py и embeddings.py: локальная база и семантический поиск;

• ocr.py и pdf.py: локальное извлечение содержимого;

• sandbox.py: контролируемое выполнение кода в Docker.

Транспорт и цикл MCP

Основной транспорт — stdio, подходящий для локальных серверов. Хост запускает процесс и общается с ним через stdin и stdout; каждое сообщение — это JSON-RPC. Журналы инициализации отправляются в stderr, чтобы не повредить канал MCP.

Сервер реализует современные потоки:

1. server/discover — обнаружение версии, идентичности, возможностей и инструкций;

2. tools/list — детерминированное обнаружение инструментов, схем и кэша;

3. tools/call — выполнение инструмента со структурированным результатом.

Когда установлен официальный пакет mcp, сервер использует современный SDK с транспортом stdio. Без пакета используется минимальная реализация stdio, включённая в проект. Оба пути регистрируют один и тот же набор инструментов и следуют современному контракту. Каждый инструмент объявляет inputSchema и outputSchema; минимальный путь stdio также проверяет аргументы перед выполнением обработчика.

Сервер не открывает HTTP-порт. Streamable HTTP остаётся вне области действия этой версии.

Установка

Требования:

• Python 3.11 или выше;

• pip;

• учётные данные конечной точки LLM, совместимой с API чата OpenAI, для ассистированного решения;

• Tesseract только для локального OCR;

• Docker и локальные образы только для run_code;

• pypdf только для извлечения PDF-файлов.

Базовая установка:

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

Дополнительные опции:

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

Конфигурация

Скопируйте .env.example в .env и заполните только тех провайдеров, которых хотите использовать. .env не должен храниться в системе контроля версий и не должен передаваться другим.

LLM-решение

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

Это основной бэкенд. Если второй бэкенд полностью настроен, Quaestio выполняет консенсус:

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

Без бэкенда сервер остаётся доступным, но вопросы, которые не могут быть решены детерминированно, возвращают needs_review.

Языковая подготовка

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

Доступные режимы:

• never: никогда не переводит;

• auto: переводит, когда вопрос не на английском;

• required: требует переводчик, когда перевод необходим.

Оригинальное изображение не изменяется. При наличии OCR распознанный текст может использоваться как вспомогательный контекст, но изображение по-прежнему отправляется как визуальное доказательство.

Семантический поиск

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

Эмбеддинги необязательны. Если они недоступны, локальная база использует TF-IDF. База хранит материалы и векторы локально; не добавляйте содержимое, которое не может быть сохранено в этом файле.

Независимая семантическая проверка

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

Этот бэкенд должен быть отделён от решателя, когда важна независимость проверки. Он возвращает supports, contradicts или uncertain; он не превращает ответ LLM в verified.

Дополнительные локальные ресурсы

QUAESTIO_TESSERACT_PATH=
QUAESTIO_DOCKER_PATH=
QUAESTIO_SANDBOX_PYTHON_IMAGE=python:3.12-slim

Docker-песочница не загружает образы автоматически. Образы должны существовать локально.

Как запустить сервер

После установки в режиме редактирования:

quaestio

Без установки в режиме редактирования:

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

Процесс кажется ожидающим ввода, потому что транспорт stdio управляется MCP-клиентом. Это ожидаемое поведение.

Настройка в MCP-клиенте

MCP-хосту необходимо запустить команду сервера как подпроцесс. Общий пример для Windows:

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

Либо с помощью Python:

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

Переменные окружения могут быть предоставлены локальным .env или конфигурацией хоста. Предпочитайте механизм секретов хоста, если он доступен, и никогда не включайте реальные ключи в репозиторий.

Инструменты MCP

Решение и проверка

Материалы и поиск

Разбор, OCR и документы

Для визуальной обработки и OCR входные данные должны содержать встроенное изображение в base64. URI-ссылки принимаются в каноническом контракте, но текущий поток OCR и мультимодальной отправки использует встроенные байты.

Код

run_code не выполняет код на хосте. Если Docker, образ или язык недоступны, возвращается структурированное состояние недоступности.

Диагностика

Входной контракт

Канонический вопрос можно отправить так:

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

Основные поля:

• question: обязательный текст;

• options: необязательный список минимум с двумя уникальными альтернативами;

• question_id: идентификатор, сохраняемый в пакетах;

• context: дополнительный контекст или извлечённый материал;

• attachments: изображения или документы, обычно с mime_type и data_base64;

• expected_answer и expected_option_index: только для оценки с ключом ответов, не для направления решателя.

Выходной контракт

Ответ содержит, среди прочих полей:

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

Статус ответа

• verified: достаточно детерминированных доказательств;

• answered: предложение создано, но детерминированного доказательства нет;

• needs_review: не хватило консенсуса, доказательств или проверки;

• error: сбой в конвейере.

Поле correct заполняется только тогда, когда клиент предоставляет ключ ответов через expected_answer или expected_option_index.

Пример вызова MCP

После server/discover клиент может вызвать:

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

Результат MCP включает сериализованное текстовое содержимое и structuredContent для клиентов, поддерживающих структурированные результаты.

Разработка и проверка

Запустите автоматизированный набор тестов с помощью:

pytest -q

Модульные тесты должны выполняться без зависимости от реальных вызовов к провайдерам. Смоук-тесты против внешних API должны быть явными, с использованием локальных учётных данных и авторизованных запросов.

Связанная техническая документация:

• спецификация и план многоязычной подготовки / план;

• спецификация изоляции тестов / план;

• спецификация смоук-теста NIM / план;

• спецификация мультимодальной оценки / план;

• спецификация эмбеддингов / план;

• спецификация мультимодального верификатора / план;

• спецификация бенчмарка и уверенности / план.

Текущие ограничения

• публичный HTTP-транспорт ещё не реализован;

• сервер не предоставляет resources или prompts MCP;

• семантический верификатор принимает встроенные изображения; внешние URI, PDF-файлы и видео на этом этапе ещё не отправляются;

• индекс эмбеддингов требует переиндексации при смене настроенной модели;

• OCR и извлечение PDF зависят от дополнительных локальных установок;

• консенсус и семантическая проверка снижают риск, но не заменяют эталон, формальное доказательство или человеческую проверку.