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 서버는 현재 tools 프리미티브를 노출합니다. resources, resource templates 또는 prompts를 별도의 MCP 프리미티브로 게시하지 않습니다. 자료, OCR, PDF 및 서버 기능은 도구를 통해 접근됩니다.

사용된 프로토콜 참조:

• MCP — 공식 문서;

• MCP 2026-07-28 사양;

• 서버 검색;

• 도구 사양;

• stdio 사양;

• 공식 Python SDK;

• 공식 참조 서버.

기능

• 객관식 및 주관식 문제 해결;

• 인라인 이미지가 포함된 질문 처리;

• 구성 가능한 두 LLM 백엔드 간 합의 실행;

• 영어가 아닌 질문을 구성된 모델에 맞게 준비;

• 대안, 인덱스, 수식, 코드 및 첨부 파일 보존;

• 제안의 구조적 검증 및 구성된 경우 의미론적 검증;

• 선택적 결정론적 및 기호 수학 검증 적용;

• 로컬 학습 자료 추가 및 검색;

• TF-IDF 폴백이 포함된 의미론적 임베딩 사용;

• Tesseract로 이미지에서 텍스트 추출;

• PDF에서 텍스트 추출 및 해석;

• 코드를 실행하지 않고 분석;

• 코드를 실행하지 않고 컴파일/구문 검사;

• Docker 샌드박스에서만 Python 또는 JavaScript 실행;

• 정답지로 배치 평가 및 지표 계산;

• 실행된 단계의 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입니다. 초기화 로그는 MCP 채널을 오염시키지 않도록 stderr로 전송됩니다.

서버는 최신 흐름을 구현합니다:

1. server/discover — 버전, ID, 기능 및 지침 검색;

2. tools/list — 도구, 스키마 및 캐시의 결정론적 검색;

3. tools/call — 구조화된 결과로 도구 실행.

공식 mcp 패키지가 설치되어 있으면 서버는 stdio 전송과 함께 최신 SDK를 사용합니다. 패키지가 없으면 프로젝트에 포함된 최소 stdio 구현을 사용합니다. 두 경로 모두 동일한 도구 집합을 등록하고 최신 계약을 따릅니다. 각 도구는 inputSchema 및 outputSchema를 선언합니다. 최소 stdio 경로도 핸들러를 실행하기 전에 인수를 검증합니다.

서버는 HTTP 포트를 열지 않습니다. Streamable HTTP는 이 버전의 범위에 포함되지 않습니다.

설치

요구 사항:

• Python 3.11 이상;

• pip;

• 지원되는 문제 해결을 위한 OpenAI 채팅 API 호환 LLM 엔드포인트의 자격 증명;

• 로컬 OCR 전용 Tesseract;

• run_code 전용 Docker 및 로컬 이미지;

• PDF 추출 전용 pypdf.

기본 설치:

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

이 백엔드는 검토의 독립성이 중요할 때 solver와 분리되어야 합니다. 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: solver를 안내하는 것이 아니라 정답지 평가에만 사용됩니다.

출력 계약

응답에는 다른 필드 외에도 다음이 포함됩니다:

{
  "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 전송은 아직 구현되지 않았습니다;

• 서버는 MCP 리소스나 프롬프트를 노출하지 않습니다;

• 시맨틱 검증기는 인라인 이미지를 허용합니다; 외부 URI, PDF 및 비디오는 아직 이 단계에서 전송되지 않습니다;

• 임베딩 인덱스는 구성된 모델이 교체될 때 재인덱싱이 필요합니다;

• OCR 및 PDF 추출은 선택적 로컬 설치에 의존합니다;

• 합의와 시맨틱 검토는 위험을 줄이지만, 정답지, 공식 증명 또는 인간 검토를 대체하지는 않습니다.