tutu-mcp-proxy

Proxy MCP de compactación/verificación de fundamentos para mcp.tutu.ru, hecho para el hackatón de Tutu (track 2 — «optimización de herramientas»). Los mismos 16 instrumentos, el mismo comportamiento, además:

• Catálogo recortado siempre cargado. tools/list del servidor real es de ~108 KB incluso antes de la primera búsqueda (uv run python tutu.py measure, reproducible desde fixtures/). Los tres instrumentos más pesados (search_rail, get_rail_seatmap, search_hotels) reciben una description de nivel superior corta; la prosa recortada no se pierde, sino que se traslada al resultado de la llamada del get_<domain>_instructions emparejado (tutu_mcp/proxy/compact_tools.py) — solo la paga la sesión que realmente la lee. inputSchema no se toca en ningún sitio.

• check_groundedness. Verifica de forma determinista el borrador de la respuesta contra los tool_result en los que se apoya: extrae del texto precios/horas/números de trenes-vuelos/enlaces y comprueba su presencia real en el JSON, sin juez LLM (tutu_mcp/groundedness.py).

• Explicación para resultados vacíos. El fallo más frecuente: el agente lee una búsqueda filtrada vacía como «este tren no circula», aunque el instrumento solo devolvía lo que está a la venta. Los contadores del propio Tutu meta.post_filter_dropped_* indican qué filtro vació la lista — el proxy los convierte en una frase y la adjunta al resultado (_empty_result_note), para que el agente nombre el hecho en lugar de adivinar un horario que no se le ha dado (tutu_mcp/proxy/empty_results.py).

• Premise gate + assess_request. check_groundedness verifica la SALIDA del turno; esto es la ENTRADA: un valor que estrecha la búsqueda debe venir del usuario o de un tool_result anterior. Un filtro inventado por el agente (clásico: asumir silenciosamente la hora de fin de un evento y filtrar con él los vuelos de regreso) recibe clarification_required en lugar de datos (tutu_mcp/premises.py).

• Modo mock. Responde con fixtures grabadas en lugar del servidor real — se puede ejecutar tantas veces como se quiera sin tocar el límite de tasa compartido del hackatón.

Visor de trazas

Cada ejecución de evaluaciones se convierte en un único archivo HTML autocontenido: doble clic, sin servidor y sin red. El escaparate publicado es https://trum-ok.github.io/tutu-mcp-hackathon/trace-viewer.html.

make viewer        # из последнего настоящего прогона эвалов
make viewer-demo   # из рукописных демо-трейсов — без модели и без ключа

En la interfaz: modo resumen — toda la matriz de escenarios × variantes en una sola tabla; solo fallos reduce la lista a lo que ha caído; lado a lado coloca un escenario de ambas variantes juntos, con resaltado de las comprobaciones divergentes. Un clic en cualquier valor resaltado de la respuesta abre un panel con el fragmento exacto de la respuesta del servidor del que procede — o con la constatación directa de que no está en ninguna de ellas. Las ejecuciones sintéticas (demo:/scripted:) están marcadas con una insignia ámbar «NO ES MEDICIÓN» — una demostración escrita a mano no puede confundirse con una medición.

Cómo se construye — docs/deploy.md.

Related MCP server: Yourttoo MCP Server

Qué ha salido

Cuatro ejecuciones de 22 escenarios en gpt-5.6-luna con --effort low, 19 de agosto de 2026. La dispersión entre ejecuciones proviene del propio modelo: el backend es el mismo, el conjunto de escenarios también.

La fila sobre afirmaciones inventadas conviene leerla antes que el porcentaje: 4 invenciones de 189 afirmaciones verificables y 1 de 184 — es 97,9 % frente a 99,5 %, la brecha parece ruido. En términos absolutos son cuatro veces menos hechos incorrectos que llegan al usuario, y es precisamente eso lo que recibe, no un porcentaje. Los porcentajes se calculan sobre las afirmaciones verificables: un umbral que el propio usuario ha mencionado («más barato de 3000 ₽») el payload no está obligado a confirmarlo y no entra en el denominador.

El ahorro de superficie es del 39 % y no depende de la ejecución: es una magnitud estática que el agente paga en cada sesión antes de la primera búsqueda. Todo lo demás es comportamiento del modelo, por eso se da un rango.

La última fila es tan importante como la primera: el gate se activó 8–12 veces por ejecución y, sin embargo, nunca formuló una pregunta en un escenario donde no había nada que preguntar (control negativo no_overask más la comprobación did_not_over_ask). Un mecanismo que lo aclara todo habría obtenido métricas de premisas perfectas y habría estropeado el producto.

Las variantes divergen en cinco escenarios, y en los cinco gana proxy: una salida filtrada vacía no se lee como «el tren no circula», una errata en el día de la semana se detecta antes de la búsqueda, un número de huéspedes sustituido silenciosamente lo detiene el gate, los asientos contiguos se buscan con el instrumento correcto. El único fallo persistente de proxy es multitransport_basic: el agente imprime la diferencia de precios (2 275,07 − 1 700 = 575), cuyas dos mitades están confirmadas, pero el número en sí no está en el payload. Distinguir esa aritmética de una incorrecta (multiplicar el precio del hotel por el número de noches — escenario aparte, y ahí es un error) una comprobación determinista no puede; es el límite del método, no un defecto del proxy.

Dos cosas por honestidad del informe: los fallos de fixtures se cuentan aparte de los errores de los instrumentos — un agujero en la grabación no debe leerse como un fallo de Tutu; y las cifras de tokens llevan ~ si son estimaciones — OpenAI no tiene endpoint de recuento de tokens, la cifra exacta se toma de una única petición de prueba real (usage.prompt_tokens), --estimate-tokens sustituye en su lugar una estimación offline de tiktoken.

El modelo y el esfuerzo de razonamiento son por ejecución (--model/OPENAI_MODEL, --effort/OPENAI_EFFORT); sin ambos, el campo reasoning no se envía en absoluto y el modelo aplica su valor por defecto — no es lo mismo que un --effort none explícito. El runner por defecto apunta a /v1/responses — Chat Completions no acepta function tools junto con razonamiento en los modelos de razonamiento actuales; --api chat — para pasarelas compatibles con OpenAI sin /v1/responses. El emparejamiento de fixtures ignora los valores por defecto de inputSchema (el modelo escribe page: 1, sort: "price_asc" y demás donde una persona, al grabar la fixture, no escribe nada) — de lo contrario casi cada llamada en una ejecución con modelo fallaría contra la grabación.

Cómo está organizada la ejecución, qué calcula cada métrica y por qué la autocomprobación del harness está en CI — docs/evals.md.

Inicio rápido

Se necesitan uv y Python ≥ 3.13 (lo instalará el propio uv sync).

git clone https://github.com/Trum-ok/tutu-mcp-hackathon
cd tutu-mcp-hackathon
uv sync
uv run python tutu.py serve            # mock-режим (по умолчанию) — http://127.0.0.1:8800/mcp

TUTU_PROXY_MODE=live uv run python tutu.py serve   # проксирует настоящий mcp.tutu.ru

Cualquier cliente MCP — en http://127.0.0.1:8800/mcp (Streamable HTTP, sin autorización, como en upstream). Abajo, <URL> — esta dirección o la del proxy desplegado (ver docs/deploy.md).

claude mcp add --transport http tutu <URL>          # Claude Code

// Cursor · ~/.cursor/mcp.json
{ "mcpServers": { "tutu": { "url": "<URL>" } } }

// Claude Desktop · claude_desktop_config.json — через mcp-remote, он не умеет HTTP напрямую
{ "mcpServers": { "tutu": { "command": "npx", "args": ["-y", "mcp-remote", "<URL>"] } } }

Qué debe salir. En el log — dos líneas: modo y dirección de escucha. El cliente tras conectarse muestra 18 instrumentos: los 16 nativos de Tutu más assess_request y check_groundedness. Si son 16 — el cliente se ha conectado al propio Tutu, no al proxy.

Cuánto se ha conseguido recortar

tools/list: 110 164 → 79 411 bytes (−27,9 %), y teniendo en cuenta las instrucciones initialize de cada lado — −33,1 % (el proxy entrega su bloque de instrucciones de 1,9 KB en lugar de los 11,2 KB de Tutu). Ambas cifras — ya después de añadir sus dos instrumentos (assess_request 1 313 bytes, check_groundedness 1 100).

Desglose por capas del catálogo, el precio de compresión nombrado y el límite que conscientemente no se cruzó — docs/compaction.md.

Documentación

El desglose para el usuario es una página aparte: make docs compila site/index.html, o abra la ya publicada: https://trum-ok.github.io/tutu-mcp-hackathon/.

Equipo rezo

• Artamonov Arkadi (@OpSonata)

Licencia

MIT