whichtool

¿Realmente elige el modelo la herramienta correcta de tu servidor MCP?

Italiano

[!WARNING] La publicación está temporalmente en pausa. Los lanzamientos automáticos están deshabilitados, y el paquete npm puede no estar disponible mientras el repositorio público de GitHub permanezca en línea. Las instrucciones de registro y de Action a continuación se conservan intencionalmente para una posible republicación futura. Para usar el código fuente actual ahora:

git clone https://github.com/mattagame/whichtool.git
cd whichtool
bun install
bun run ./src/cli/main.ts inspect ./tools.json

Un servidor MCP puede tener esquemas válidos y aun así ser ilegible para un modelo. Publica list_users y search_users con descripciones similares y el modelo adivina. La validación de esquemas sigue pasando. Las pruebas de integración también pasan, porque llaman a la herramienta correcta por construcción.

whichtool pone esa superficie frente a un modelo real e informa qué herramienta se elige y qué pares se confunden.

whichtool nunca ejecuta una herramienta. Lee tools/list, registra lo que el modelo habría llamado y se detiene.

Es deliberadamente un punto de referencia de enrutamiento de una sola vuelta. Mide la decisión de selección de herramientas del modelo sobre un conjunto preparado de intenciones; no evalúa la ejecución de agentes de múltiples pasos, la corrección semántica de argumentos más allá de una verificación superficial de esquema, los resultados de herramientas, la recuperación ni la calidad de una respuesta final.

Cada llamada propuesta en esa vuelta se conserva en trials[].calls del informe JSON; los campos de primera llamada siguen siendo una vista de compatibilidad, no una razón para descartar llamadas adicionales.

Hace dos trabajos:

• inspect — presupuesto de tokens, anotaciones contradictorias, descripciones casi idénticas, valores x-mcp-header no válidos. Sin llamada a modelo ni clave de proveedor de modelo; un objetivo en vivo puede requerir su propia autorización.

• run — pruebas, orden de herramientas permutado, matriz de confusión, tasas con intervalos de Wilson al 95%.

inspect advierte cuando una superficie expone más de 6 herramientas. Las ejecuciones reales de CLI, MCP y GitHub Action se detienen antes de llamar a un modelo por encima de ese valor predeterminado. Después de revisar la superficie, un operador puede aumentar el límite con --max-tools N, trials.maxTools, el indicador de inicio de MCP o la entrada max-tools de la Action; 1,000 es el máximo absoluto. Seis es un valor predeterminado cauteloso, no una regla universal: más herramientas pueden aumentar la ambigüedad y el tamaño del prompt, pero el número correcto depende del modelo, los esquemas, las descripciones y las tareas. También establece --max-context-tokens para que un pequeño número de herramientas inusualmente grandes no pueda eludir el presupuesto de contexto.

Esos intervalos de Wilson describen la estabilidad a nivel de prueba en las tareas del archivo. Repetir una tarea mide si esa misma decisión de enrutamiento es estable; no estima cómo se desempeñará el modelo en intenciones no vistas.

Instalación

npx whichtool inspect ./tools.json
# or: bunx whichtool inspect ./tools.json

npm install --save-dev whichtool

Requiere Node 20.11+ o Bun 1.3+. Cero dependencias en tiempo de ejecución.

Los binarios independientes aún no se publican. Los ejecutables compilados con Bun incorporan componentes de tiempo de ejecución de terceros, por lo que la distribución permanece deshabilitada hasta que se revisen sus avisos de redistribución y puedan enviarse con cada binario. Esto es independiente de la pausa temporal de publicación del paquete anterior; usa el checkout del código fuente mientras esa pausa esté en vigor.

Related MCP server: TowerWatch Ops Agent MCP Server

Inicio rápido

# 1. Look at the surface (no model-provider key)
whichtool inspect ./tools.json
whichtool inspect https://example.com/mcp
whichtool inspect --transport stdio "bun run ./src/server.ts"

# Capture once, work offline afterwards
whichtool inspect --transport stdio "npx -y @modelcontextprotocol/server-filesystem ." \
  --save-snapshot ./tools.json

Las instantáneas pueden ser { "tools": [ … ] }, un sobre JSON-RPC tools/list o un arreglo simple.

# 2. Write a task set (whichtool.tasks.yaml)
version: 1
tasks:
  - id: users.list.basic
    prompt: 'Show me all the users in the workspace'
    expected: list_users
  - id: users.search.byname
    prompt: "Find the user whose name contains 'rossi'"
    expected: search_users
  - id: distractor.delete
    prompt: 'Permanently delete the account belonging to Rossi'
    expected: null

expected debe escribirse incluso cuando es null. Formato completo: docs/task-sets.md.

# Or draft one instead of writing step 2 by hand, then edit and commit the result
# (do not regenerate on every run). It refuses to overwrite without --force.
whichtool tasks generate ./tools.json --provider ollama --model qwen3:4b --out whichtool.tasks.yaml

# Seeded robustness variants, no model
whichtool tasks mutate --out whichtool.tasks.mutated.yaml --seed 0

# 3. Lint before spending anything
whichtool tasks lint ./tools.json --tasks ./whichtool.tasks.yaml

# 4. Preview the workload (no model call)
whichtool run ./tools.json --provider ollama --model qwen3:4b --repeat 5 --dry-run

# 5. Measure
whichtool run ./tools.json --provider ollama --model qwen3:4b --repeat 5
OPENAI_API_KEY=sk-… whichtool run ./tools.json --provider openai --model gpt-4.1-mini

--repeat tiene un valor predeterminado de 5 por tarea seleccionada, por lo que el total de pruebas son las tareas restantes después de --only / --skip, multiplicadas por repeat. Una ejecución real rechaza más de 50 pruebas totales por defecto. Después de revisar --dry-run, aumenta ese presupuesto con --max-trials N o trials.maxTrials; 1,000 es un máximo absoluto e inmodificable.

La cifra de tokens de prompt en el dry-run es un límite inferior, no una estimación de precio. Los tokens de salida y razonamiento son adicionales y pueden ser mucho mayores. Los reintentos automáticos están deshabilitados por defecto para los proveedores HTTP integrados.

Durante whichtool run, presiona Ctrl+C para abortar las solicitudes de proveedor en curso. El comando sale con el código 130 y no escribe un informe parcial. Las evaluaciones MCP siguen siendo cancelables a través del protocolo MCP.

Códigos de salida: 0 la ejecución fue saludable y los umbrales se mantuvieron, 1 falló un umbral de calidad, 2 un error de ejecución (incluyendo una ejecución incompleta o demasiados fallos de proveedor). Por defecto, una ejecución necesita al menos una prueba puntuada y permite como máximo una tasa de error de proveedor del 10%; anula estos valores con --min-scored y --max-error-rate.

# 6. Re-render, gate, compare
whichtool run … --format json --out run.json
whichtool report run.json --format markdown
whichtool report run.json --format html --out report.html
whichtool diff base-run.json head-run.json --max-accuracy-drop 0.05

diff se niega a restar ejecuciones que usaron un modelo, endpoint, huella de solicitud de proveedor no secreta, temperatura, semilla, recuento de repeticiones, configuración de permutación o conjunto de tareas diferente. Compara los resultados por tarea e índice de prueba, luego usa una prueba de signo pareada exacta de dos colas (p <= 0.05) para decidir si un movimiento es distinguible. Un aumento distinguible en el comportamiento inesperado de múltiples llamadas es una regresión incluso cuando las primeras selecciones no se movieron.

Comandos

whichtool <command> --help lista las banderas. Principales banderas en run:

--tasks --provider --model --repeat --max-trials --max-tools --concurrency --temperature --seed
--min-scored --max-error-rate
--permute / --no-permute --format --out --min-accuracy --max-over-trigger
--max-context-tokens --only --skip --dry-run --seconds-per-trial --reasoning-effort
--cache / --no-cache --cache-dir

Formatos: terminal, json, markdown, html, junit, badge.

Entorno: una credencial de objetivo HTTP necesita tanto WHICHTOOL_HTTP_AUTHORIZATION como el origen permitido exacto en WHICHTOOL_HTTP_AUTHORIZATION_ORIGIN (por ejemplo https://mcp.example). Las credenciales remotas requieren HTTPS. Las claves de proveedor provienen de ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, TOGETHER_API_KEY y WHICHTOOL_PROVIDER_API_KEY para un endpoint openai-compatible. Se respetan NO_COLOR / FORCE_COLOR.

Proveedores: anthropic, ollama, openai, openai-chat, openrouter, together, vllm, cualquier endpoint openai-compatible y un mock determinista. openai usa la API de Respuestas de OpenAI. Selecciona openai-chat explícitamente para OpenAI Chat Completions; los otros ajustes preestablecidos compatibles con OpenAI continúan usando sus endpoints de chat-completions.

anthropic habla la API de Mensajes en lugar de un dialecto de chat-completions. Ese proveedor no envía temperatura ni semilla y registra esas capacidades como no compatibles, por lo que sus ejecuciones se apoyan en --repeat y en los intervalos a nivel de prueba.

Configuración

import { defineConfig } from 'whichtool'

export default defineConfig({
  target: { transport: 'stdio', command: 'bun run ./src/server.ts' },
  tasks: './whichtool.tasks.yaml',
  provider: { name: 'ollama', model: 'qwen3:4b' },
  trials: {
    repeat: 5,
    maxTrials: 50,
    maxTools: 6,
    permute: true,
    temperature: 0,
    concurrency: 4,
  },
  thresholds: {
    minAccuracy: 0.9,
    maxOverTrigger: 0.05,
    maxContextTokens: 4000,
    maxErrorRate: 0.1,
    minScored: 1,
  },
  report: { formats: ['terminal', 'json'], out: './whichtool-report' },
})

whichtool.config.json también funciona. Las claves de API nunca son un campo de configuración. La CLI normal también puede descubrir configuración de JavaScript o TypeScript; el servidor MCP intencionalmente no lo hace, como se explica a continuación.

CI

- uses: mattagame/whichtool@v0.1.0
  with:
    target: ./tools.json
    tasks: ./whichtool.tasks.yaml
    provider: openai
    model: gpt-4.1-mini
    max-trials: '50'
    max-tools: '6'
    min-accuracy: '0.9'
    max-over-trigger: '0.05'

El almacenamiento en caché de pruebas en la acción compuesta está deshabilitado por defecto porque una caché puede contener prompts, definiciones de herramientas y respuestas de proveedor. Establece cache: 'true' solo cuando ese material no sea sensible y la persistencia alojada en GitHub sea aceptable.

La Action bloquea una invocación medida por encima de 6 herramientas por defecto; max-tools puede aumentar el límite solo hasta 1,000. Su presupuesto de max-trials se aplica a cada invocación medida. Un flujo de trabajo de comparación que mide tanto la revisión head como la base puede, por lo tanto, usar el presupuesto de pruebas una vez por ejecución; con el valor predeterminado, eso es como máximo 50 pruebas para head y 50 para base.

Omite provider para ejecutar solo el pase estático gratuito: inspect, más tasks lint cuando hay un conjunto de tareas. Un flujo de trabajo completo (incluyendo una comparación de rama base escrita en el resumen del trabajo) está en examples/github-action.

Como servidor MCP:

{
  "mcpServers": {
    "whichtool": {
      "command": "npx",
      "args": ["-y", "whichtool", "mcp", "--config", "whichtool.config.json"]
    }
  }
}

El servidor MCP está deliberadamente limitado en capacidades por sus argumentos de inicio. No auto-descubre ni ejecuta configuración de JavaScript/TypeScript: pasa un archivo JSON revisado explícitamente con --config. Las llamadas a herramientas usan el objetivo configurado y no pueden reemplazarlo con una ruta, URL o subproceso arbitrario. Las entradas de tareas/informes seleccionadas por el agente deben permanecer en el directorio de trabajo.

El flujo de trabajo de agente previsto comienza desde artefactos de evaluación que ya has preparado y revisado: inspect_surface, validate_task_file, run_evaluation, luego diff_saved_results en ejecuciones guardadas. La superficie MCP no genera ni muta conjuntos de tareas. Expone el mismo punto de referencia de enrutamiento de una sola vuelta; no es un evaluador ni ejecutor para un flujo de trabajo de agente completo.

run_evaluation siempre puede producir un plan de dry-run, pero no puede contactar a un proveedor a menos que el operador inicie el servidor con --allow-paid-runs. El presupuesto de ejecución real propiedad del operador es de 50 pruebas totales por defecto; solo el indicador de inicio --max-trials o trials.maxTrials en la configuración revisada puede aumentarlo, hasta el máximo absoluto de 1,000. El agente no puede anular ese presupuesto. La misma regla propiedad del operador se aplica al valor predeterminado de 6 herramientas a través del inicio --max-tools o trials.maxTools, con un máximo absoluto de 1,000. repeat y la concurrencia también tienen límites. Una ejecución completa devuelve un resumen compacto. Agrega --result-file ./latest-run.json para mantener el informe completo fuera del contexto del modelo. --allow-dynamic-targets existe para configuraciones de desarrollo aisladas y debe tratarse como una opción insegura. Las anulaciones de proveedor/modelo son igualmente solo de configuración a menos que el operador agregue --allow-provider-overrides. El almacenamiento en caché de pruebas persistente está desactivado en modo MCP; el operador debe agregar --cache explícitamente después de decidir que los prompts, llamadas y respuestas pueden escribirse en disco.

Ejemplos

En modelos de razonamiento como qwen3, una sola prueba puede tomar decenas de segundos de tokens de pensamiento que whichtool nunca lee. Mide una prueba, luego pasa --dry-run --seconds-per-trial. Su total de tokens de prompt sigue siendo un límite inferior, no una estimación de precio; los tokens de salida y razonamiento son adicionales.

Desarrollo

Bun es el conjunto de herramientas; Node es el objetivo de distribución. src/core/ es TypeScript portátil (sin builtins de Bun/Node).

bun install
bun test
bun run typecheck
bun run lint
bun run build

docker run --rm -v "$PWD:/work" ghcr.io/mattagame/whichtool inspect ./tools.json

Se aceptan parches: CONTRIBUTING.md enumera las restricciones que las pruebas aplican en lugar de los revisores.

Registro de diseño: SPEC.md. Seguridad: SECURITY.md. Contrato JSON: docs/report-schema.md. Cambios: CHANGELOG.md.

Descargo de responsabilidad

El software se proporciona tal cual, sin garantía. Consulte LICENSE.md.

• run cuesta dinero en los proveedores alojados. Las definiciones de herramientas y los prompts se envían al modelo que configure. Use --dry-run primero, pero trate su cifra de tokens de prompt como un límite inferior, en lugar de una estimación de precio. Ollama y otros endpoints locales permanecen en su máquina.

• Las herramientas del servidor bajo prueba nunca se invocan. stdio sí lanza el comando que usted pasa, con sus privilegios — trate ese comando como código.

• Los binarios independientes aún no se distribuyen. La publicación permanece deshabilitada hasta que se revisen los avisos de terceros del runtime integrado y puedan distribuirse junto a cada binario.

• No es un escáner de seguridad. Una superficie puede pasar inspect y seguir siendo peligrosa. Detalles: SECURITY.md.

Licencia

MIT — LICENSE.md.