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;

• 公式リファレンスサーバー.

機能

• 選択式および記述式の質問を解決する;

• インライン画像付きの質問を処理する;

• 設定可能な2つの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 — バージョン、ID、機能、指示の検出;

2. tools/list — ツール、スキーマ、キャッシュの決定的な検出;

3. tools/call — 構造化された結果によるツールの実行。

公式の mcp パッケージがインストールされている場合、サーバーは stdio トランスポートを備えた最新の SDK を使用します。パッケージがない場合は、プロジェクトに含まれている最小限の stdio 実装を使用します。どちらのパスも同じツールセットを登録し、最新の契約に従います。

各ツールは inputSchema と outputSchema を宣言します。最小限の stdio パスも、ハンドラーを実行する前に引数を検証します。

サーバーは HTTP ポートを起動しません。Streamable HTTP はこのバージョンの範囲外です。

インストール

要件:

• Python 3.11 以上;

• pip;

• 支援付き解決のための OpenAI チャット API 互換の LLM エンドポイントの資格情報;

• 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

これが主要なバックエンドです。2番目のバックエンドが完全に設定されている場合、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、ドキュメント

コード

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: 少なくとも2つの一意な選択肢を持つオプションのリスト;

• 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トランスポートはまだ実装されていません;

• サーバーはリソースまたはMCPプロンプトを公開していません;

• セマンティック検証器はインライン画像を受け入れます; 外部URI、PDF、ビデオはまだこの段階では送信されません;

• エンベディングインデックスは、設定されたモデルが変更されると再インデックスが必要です;

• OCRとPDF抽出は、オプションのローカルインストールに依存します;

• コンセンサスとセマンティックレビューはリスクを軽減しますが、模範解答、形式証明、人間によるレビューを代替するものではありません。