mcpscope

Un banco de trabajo local-first para desarrollar, inspeccionar y comparar servidores MCP contra modelos locales (LM Studio, Ollama) o remotos (OpenRouter) — un espacio de trabajo compartido con una interfaz web para ti y una interfaz CLI + MCP para tu agente de codificación.

Su runtime se distribuye por separado como mcpscope-engine — un motor de chat/agente TypeScript embebible y sin dependencias (llamadas a herramientas MCP, proveedores de LLM local-first, sesiones node:sqlite duraderas, eventos de transparencia en streaming) para construir tu propia aplicación impulsada por MCP. Para empezar desde una aplicación funcional en lugar de un archivo en blanco, haz un fork de mcpscope-chat-template — un servidor MCP, el motor y una interfaz de chat embebible en un solo proceso Node pequeño.

Construir un buen servidor MCP es trabajo empírico, y rara vez lo haces solo hoy en día: un agente de codificación puede ejecutar cada benchmark y leer cada traza, pero los números solo se vuelven buenos cuando el desarrollador permanece en el bucle — mirando la única ejecución que falló, ajustando una descripción de herramienta o una rúbrica, decidiendo qué probar a continuación y volviendo a ejecutar. mcpscope está construido para esa colaboración. No es un harness de benchmark que un agente ejecute sin supervisión, ni una GUI que un desarrollador maneje manualmente: cada capacidad se expone a través de una interfaz web diseñada para una persona y a través de una CLI y una interfaz MCP diseñadas para un agente, todo sobre un modelo de datos compartido. El humano puede ver exactamente lo que hizo el agente, el agente puede inspeccionar exactamente lo que hizo el humano, y un sistema de IDs con etiquetas de tipo permite que ambos apunten a la misma sesión, turno o llamada a herramienta.

Por qué importa ese bucle: un LLM es tan bueno como las herramientas que se le dan — una lección que aprendí construyendo mis propios servidores MCP para análisis de datos y estadísticas. Mis primeras versiones hicieron lo obvio: envolver la API existente y devolver los datos crudos al modelo. Eso resultó ser el peor diseño posible — hambriento de tokens, impreciso y dependiente de un modelo grande con un gran contexto solo para producir algo útil. Los resultados solo mejoraron cuando el servidor hizo el trabajo por sí mismo — los cálculos, la agregación y el filtrado — y devolvió respuestas en lugar de datos. Esa experiencia es la premisa sobre la que se construye mcpscope: un buen servidor MCP no es un envoltorio de API. Es una interfaz de usuario construida para un LLM, diseñada para resolver un trabajo específico de manera eficiente incluso en un modelo local pequeño. Y es una aplicación como cualquier otra, por lo que comienza con casos de uso claros y criterios de calidad, y la mayor parte de la ingeniería de software ordinaria se aplica cuando la diseñas y construyes.

La parte que no se traslada es la prueba. No puedes fijar el comportamiento de extremo a extremo con aserciones deterministas, porque el modelo es no determinista y tanto sus entradas como sus salidas son mayormente lenguaje natural. Entonces, como el ecosistema de evaluación más amplio, mcpscope mide la calidad estadísticamente — ejecuta un conjunto de prompts muchas veces contra un modelo y servidor MCP elegidos, luego lee la confiabilidad por herramienta y el costo de tokens, con puntuación opcional de la calidad de las respuestas por un modelo juez separado. Lo que mcpscope añade es mantener esa medición dentro del bucle de iteración en lugar de al final: cada ejecución permanece inspeccionable hasta cada paso de razonamiento, llamada a herramienta y token de contexto, de modo que "la puntuación bajó" se convierte inmediatamente en "mira lo que hizo el modelo aquí".

Ejecutas un prompt, o un benchmark repetible, contra un modelo local (LM Studio, Ollama) o remoto (OpenRouter), observas cada paso de razonamiento, llamada a herramienta y token de contexto, luego cambias una cosa (una descripción de herramienta, un parámetro, un payload de salida) y lo ejecutas de nuevo. Todo permanece en tu máquina.

Comenzar

Requisito previo (2 minutos): un backend LLM en ejecución — local (LM Studio, Ollama) o remoto (OpenRouter). Para LM Studio: abre la pestaña Developer → Start server, carga un modelo y anota su id de modelo — la URL del servidor es http://localhost:1234/v1.

Aplicación de escritorio — la forma más fácil de probar mcpscope

Descarga el instalador para tu sistema operativo desde la página de Releases (macOS .dmg — solo Apple Silicon, Windows .exe, Linux AppImage/.deb/.rpm). Todo está incluido — ejecútalo y el banco de trabajo se abre; los datos viven en ~/.mcpscope. Mientras se ejecuta, sirve el mismo backend que mcpscope serve en http://localhost:3066 (interfaz MCP en /mcp), por lo que los agentes de codificación y otros clientes MCP pueden conectarse directamente — establece las variables de entorno BACKEND_HOST / BACKEND_PORT antes de iniciarlo para cambiar la dirección (mostrada en la aplicación bajo Configuration → Server). Las compilaciones no están firmadas por ahora, por lo que macOS Gatekeeper / Windows SmartScreen advierten en el primer inicio.

npm — para desarrollar un servidor MCP (añade la CLI)

Si estás construyendo un servidor MCP, querrás la CLI (y la interfaz MCP para tu agente de codificación). Requiere Node.js 24+:

npm install -g mcpscope
mcpscope serve

O ejecútalo sin instalar: npx mcpscope serve.

mcpscope serve inicia mcpscope en http://localhost:3066 y lo abre en tu navegador. Los datos se almacenan en ~/.mcpscope; detén con Ctrl-C. Banderas: --port <n>, --host <host>, --data-dir <path>, --no-open.

Primeros pasos (cualquier instalación)

1. En la interfaz web, abre Configuration y añade una conexión LM (la URL base anterior) y una configuración de modelo (el id de modelo que cargaste), luego establécelo como modelo predeterminado. No se necesita ningún perfil MCP para comenzar — mcpscope incluye servidores MCP complementarios sin configuración. ¿Prefieres editar un archivo? La misma configuración como JSON: CONFIG.md.
2. Crea una sesión, selecciona un servidor complementario (por ejemplo, Open-Meteo Weather), envía un prompt e inspecciona la traza completa: configuración, definiciones de herramientas, razonamiento, llamadas a herramientas y resultados, y un desglose de contexto codificado por colores por turno.
3. Añade un perfil de servidor MCP cuando estés listo para apuntar mcpscope a tu propio servidor.
4. Define un benchmark y ejecútalo para probar un servidor MCP de manera repetible entre modelos — luego entrega el mismo bucle a tu agente de codificación.

El recorrido completo está en TUTORIAL.md; el ejemplo trabajado con números reales está en EXAMPLE.md.

Para agentes de codificación

mcpscope habla MCP por sí mismo — conecta tu agente y puede manejar todo el bucle en las mismas sesiones que ves en la interfaz:

claude mcp add --transport http mcpscope http://localhost:3066/mcp

{ "mcpServers": { "mcpscope": { "type": "http", "url": "http://localhost:3066/mcp" } } }

Entonces un prompt como este es suficiente para poner al agente a trabajar:

mcpscope se está ejecutando en localhost:3066 (MCP en /mcp; la CLI mcpscope es la superficie idéntica). Usa sus herramientas mcpscope_* para comparar mi servidor MCP: comienza con mcpscope_list_mcp_profiles y mcpscope_list_model_configs, crea sesiones y envía prompts con wait: true para que nunca hagas polling, y sigue el bucle en EXAMPLE.md.

Cada operación es tanto un comando CLI como una herramienta MCP (paridad verificada por pruebas), los resultados son JSON en snake_case, y create/send toman wait para que los agentes obtengan resultados terminales en una sola llamada. Detalles: MCP.md.

Otras formas de ejecutar

• Docker: una imagen publicada está disponible en GHCR. Consulta TUTORIAL.md para el camino paso a paso y RELEASING.md para las etiquetas de imagen.
• Desde el código fuente: para trabajar en mcpscope en sí, consulta DEVELOPMENT.md.

Lo que puedes hacer

• Inspeccionar sesiones: observa cómo un modelo lee definiciones de herramientas, razona, llama a herramientas y consume la ventana de contexto, con atribución de tokens auditable por parte.
• Comparar servidores MCP: un conjunto reutilizable de prompts ejecutado N× contra un modelo y servidor MCP elegidos, produciendo una tarjeta de puntuación de errores/uso por herramienta y confiabilidad por caso (pass@k / pass^k).
• Evaluar la calidad de respuestas con LLM: un modelo juez separado puntúa cada ejecución contra una rúbrica por caso (consulta BENCHMARK.md).
• Controlarlo desde el shell o como herramientas MCP: cada operación es tanto un comando CLI mcpscope <cmd> como una herramienta MCP mcpscope_<cmd>, por lo que un agente de codificación puede ejecutar todo el bucle — en las mismas sesiones que ves en la interfaz.

Cómo se compara

Muchas buenas herramientas tocan partes de este espacio; la diferencia es qué parte del bucle sirven y a quién mantienen en él.

• MCP Inspector sondea un servidor MCP a nivel de protocolo — lista herramientas, llámalas a mano. No hay modelo en el bucle; mcpscope prueba lo que un modelo realmente hace con tu servidor.
• mcpsnoop captura tráfico MCP real cliente↔servidor en el cable. mcpscope ejecuta el modelo en sí y atribuye cada token de contexto.
• MCPJam es el vecino más cercano: un playground de LLM con evaluaciones y trazas. mcpscope difiere en la atribución de tokens por parte, estadísticas de confiabilidad pass@k / pass^k y la paridad humano+agente sobre un almacén compartido.
• promptfoo, mcp-eval y DeepEval son harnesses de evaluación impulsados por configuración o código, en su mejor momento como puertas de regresión sin supervisión en CI. mcpscope es el banco de trabajo interactivo para el bucle de iteración antes de eso — y expone las mismas operaciones a través de CLI/MCP para que un agente también pueda manejarlo.
• MCPBench, MCP-Bench y MCPMark comparan modelos contra conjuntos fijos de servidores. mcpscope compara tu servidor contra los modelos que elijas.
• LM Studio y Open WebUI son interfaces de chat con soporte de herramientas — solo para el humano, con conteos de tokens agregados en el mejor caso. LM Studio es uno de los backends compatibles de mcpscope, no un competidor.

Si uno de estos se ajusta mejor a tu flujo de trabajo, úsalo — varios son excelentes. mcpscope es para el bucle donde tú y tu agente de codificación iteran juntos en tu propio servidor MCP.

Documentación

Comenzar

• TUTORIAL.md - instalar, configurar, ejecutar una sesión y comparar un servidor MCP
• EXAMPLE.md - el ejemplo trabajado: inspeccionar → comparar → cambiar una cosa → observar cómo se mueve la métrica
• CONFIG.md - la referencia mcpscope.config.json, incluida la configuración completamente headless
• COMPANIONS.md - servidores MCP complementarios incluidos y sin configuración que puedes seleccionar sin ningún setup
• BENCHMARK.md - modelo de suite/caso/ejecución de benchmark, métricas deterministas y evaluación de rúbrica con LLM

Interfaces

• MCP.md - interfaz MCP: transporte, superficie de herramientas y resultados estructurados
• CLI.md - comandos CLI, banderas, formato de salida y códigos de salida
• EMBEDDING.md - embebe el paquete mcpscope-engine en tu propia aplicación Node.js/TypeScript: createEngine(), configuración, sesiones, eventos y una integración completa con Express
• mcpscope-chat-template - una aplicación inicial bifurcable construida sobre el motor: servidor MCP + bucle de agente + interfaz de chat embebible en un proceso Node, con documentación sobre diseño de herramientas MCP

Internos y contribución

• DEVELOPMENT.md - ejecutar desde el código fuente, compilar, ayudas de desarrollo y notas del repositorio
• AGENTS.md - guía para agentes de codificación de IA que trabajan en mcpscope: estructura del proyecto, principio de paridad, estilo de trabajo, validación
• ARCHITECTURE.md - diseño del sistema, persistencia, streaming, reproducción y superficie de API
• PROVIDERS.md - detalles internos de proveedores (LM Studio, Ollama, OpenRouter): tokens de razonamiento, conteo de tokens, ventanas de contexto, carga/descarga de modelos (incl. intercambio automático)
• DATA-MODEL.md - árbol de ejecución canónico, taxonomía de partes e IDs
• DATABASE-SCHEMA.md - tablas SQLite, claves foráneas y diagrama ER
• DESIGN-SYSTEM.md - sistema de diseño del frontend: los tokens, primitivas y patrones que mantienen la GUI consistente
• design-assets/ - SVGs maestros del logotipo (logo, marca, wordmark, favicon); consulta su README
• TESTING.md - estrategia de pruebas, reproducción y cómo añadir regresiones
• RELEASING.md - flujo de trabajo de lanzamiento basado en etiquetas: publicación npm, imagen GHCR e instaladores de escritorio

Los documentos internos/para contribuidores viven en docs/; las guías orientadas al usuario permanecen en la raíz del repositorio.