mcpscope

Um workbench local-first para desenvolver, inspecionar e avaliar servidores MCP contra modelos locais (LM Studio, Ollama) ou remotos (OpenRouter) — um espaço de trabalho compartilhado com uma interface web para você e uma interface CLI + MCP para seu agente de codificação.

Seu runtime é distribuído separadamente como mcpscope-engine — um mecanismo de chat/agente TypeScript incorporável e sem dependências (chamada de ferramentas MCP, provedores de LLM local-first, sessões node:sqlite duráveis, eventos de transparência em streaming) para construir seu próprio aplicativo com MCP. Para começar com um aplicativo funcional em vez de um arquivo em branco, faça um fork de mcpscope-chat-template — um servidor MCP, o mecanismo e uma interface de chat incorporável em um único processo Node pequeno.

Construir um bom servidor MCP é um trabalho empírico, e raramente você o faz sozinho: um agente de codificação pode executar todos os benchmarks e ler todos os rastreamentos, mas os números só ficam bons quando o desenvolvedor permanece no ciclo — observando a execução que falhou, ajustando uma descrição de ferramenta ou uma rubrica, decidindo o que tentar em seguida e re-executando. O mcpscope é construído para essa parceria. Não é um harness de benchmark que um agente executa sem supervisão, nem uma GUI que um desenvolvedor opera manualmente: cada capacidade é exposta por meio de uma interface web moldada para uma pessoa e por meio de uma CLI e uma interface MCP moldadas para um agente, tudo sobre um modelo de dados compartilhado. O humano pode ver exatamente o que o agente fez, o agente pode inspecionar exatamente o que o humano fez, e um sistema de IDs com tags de tipo permite que ambos apontem para a mesma sessão, turno ou chamada de ferramenta.

Por que esse ciclo importa: um LLM é tão bom quanto as ferramentas que recebe — uma lição que aprendi construindo meus próprios servidores MCP para análise de dados e estatísticas. Minhas primeiras versões fizeram o óbvio: envolver a API existente e devolver os dados brutos ao modelo. Isso acabou sendo o pior design possível — consumia muitos tokens, era impreciso e dependia de um modelo grande com uma janela de contexto grande apenas para produzir algo útil. Os resultados só ficaram bons quando o servidor fez o trabalho em si — os cálculos, a agregação e a filtragem — e retornou respostas em vez de dados. Essa experiência é a premissa sobre a qual o mcpscope é construído: um bom servidor MCP não é um wrapper de API. É uma interface de usuário construída para um LLM, projetada para resolver um trabalho específico com eficiência, mesmo em um modelo local pequeno. E é um aplicativo como qualquer outro, então começa com casos de uso claros e critérios de qualidade, e a maior parte da engenharia de software comum se aplica ao projetá-lo e construí-lo.

A parte que não se transfere é o teste. Você não pode fixar o comportamento de ponta a ponta com asserções determinísticas, porque o modelo é não determinístico e tanto suas entradas quanto suas saídas são majoritariamente linguagem natural. Então, como o ecossistema de avaliação mais amplo, o mcpscope mede a qualidade estatisticamente — execute um conjunto de prompts muitas vezes contra um modelo e servidor MCP escolhidos e, em seguida, leia a confiabilidade por ferramenta e o custo de tokens, com pontuação opcional da qualidade das respostas por um modelo juiz separado. O que o mcpscope adiciona é manter essa medição dentro do ciclo de iteração, em vez de no final dele: cada execução permanece inspecionável até cada etapa de raciocínio, chamada de ferramenta e token de contexto, então "a pontuação caiu" imediatamente se torna "veja o que o modelo fez aqui".

Você executa um prompt, ou um benchmark repetível, contra um modelo local (LM Studio, Ollama) ou remoto (OpenRouter), observa cada etapa de raciocínio, chamada de ferramenta e token de contexto, depois muda uma coisa (uma descrição de ferramenta, um parâmetro, um payload de saída) e executa novamente. Tudo permanece na sua máquina.

Comece

Pré-requisito (2 minutos): um backend LLM em execução — local (LM Studio, Ollama) ou remoto (OpenRouter). Para LM Studio: abra a aba Developer → Start server, carregue um modelo e anote seu ID — a URL do servidor é http://localhost:1234/v1.

Aplicativo desktop — a maneira mais fácil de experimentar o mcpscope

Baixe o instalador para seu sistema operacional na página de Releases (macOS .dmg — somente Apple Silicon, Windows .exe, Linux AppImage/.deb/.rpm). Tudo está incluído — inicie-o e o workbench abre; os dados ficam em ~/.mcpscope. Enquanto está em execução, ele serve o mesmo backend que mcpscope serve em http://localhost:3066 (interface MCP em /mcp), então agentes de codificação e outros clientes MCP podem se conectar diretamente a ele — defina as variáveis de ambiente BACKEND_HOST / BACKEND_PORT antes de iniciar para alterar o endereço (mostrado no aplicativo em Configuration → Server). Os builds não são assinados por enquanto, então o Gatekeeper do macOS / SmartScreen do Windows avisam no primeiro início.

npm — para desenvolver um servidor MCP (adiciona a CLI)

Se você está construindo um servidor MCP, vai querer a CLI (e a interface MCP para seu agente de codificação). Requer Node.js 24+:

npm install -g mcpscope
mcpscope serve

Ou execute sem instalar: npx mcpscope serve.

mcpscope serve inicia o mcpscope em http://localhost:3066 e o abre no seu navegador. Os dados são armazenados em ~/.mcpscope; pare com Ctrl-C. Flags: --port <n>, --host <host>, --data-dir <path>, --no-open.

Primeiros passos (qualquer instalação)

1. Na interface web, abra Configuration e adicione uma conexão LM (a URL base acima) e uma configuração de modelo (o ID do modelo que você carregou) e defina-o como modelo padrão. Nenhum perfil MCP é necessário para começar — o mcpscope inclui servidores MCP complementares sem configuração. Prefere editar um arquivo? A mesma configuração como JSON: CONFIG.md.
2. Crie uma sessão, selecione um servidor complementar (por exemplo, Open-Meteo Weather), envie um prompt e inspecione o rastreamento completo: configuração, definições de ferramentas, raciocínio, chamadas de ferramentas e resultados, e uma divisão de contexto codificada por cores por turno.
3. Adicione um perfil de servidor MCP quando estiver pronto para apontar o mcpscope para seu próprio servidor.
4. Defina um benchmark e execute-o para testar um servidor MCP repetidamente entre modelos — depois entregue o mesmo ciclo ao seu agente de codificação.

O passo a passo completo está em TUTORIAL.md; o exemplo trabalhado com números reais está em EXAMPLE.md.

Para agentes de codificação

O mcpscope fala MCP por conta própria — conecte seu agente e ele pode conduzir todo o ciclo nas mesmas sessões que você vê na interface:

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

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

Então um prompt como este é suficiente para colocar o agente para trabalhar:

mcpscope está rodando em localhost:3066 (MCP em /mcp; a CLI mcpscope é a mesma superfície). Use suas ferramentas mcpscope_* para avaliar meu servidor MCP: comece com mcpscope_list_mcp_profiles e mcpscope_list_model_configs, crie sessões e envie prompts com wait: true para nunca fazer polling, e siga o ciclo em EXAMPLE.md.

Cada operação é tanto um comando CLI quanto uma ferramenta MCP (paridade garantida por testes), os resultados são JSON em snake_case, e create/send aceitam wait para que agentes obtenham resultados terminais em uma única chamada. Detalhes: MCP.md.

Outras maneiras de executar

• Docker: uma imagem publicada é publicada no GHCR. Veja TUTORIAL.md para o caminho passo a passo e RELEASING.md para tags de imagem.
• A partir do código-fonte: para trabalhar no próprio mcpscope, veja DEVELOPMENT.md.

O que você pode fazer

• Inspecionar sessões: observe como um modelo lê definições de ferramentas, raciocina, chama ferramentas e consome a janela de contexto, com atribuição de tokens auditável por parte.
• Avaliar servidores MCP: um conjunto reutilizável de prompts executado N× contra um modelo e servidor MCP escolhidos, produzindo um scorecard de erro/uso por ferramenta e confiabilidade por caso (pass@k / pass^k).
• Avaliar a qualidade das respostas com LLM: um modelo juiz separado pontua cada execução contra uma rubrica por caso (veja BENCHMARK.md).
• Conduzir pelo shell ou como ferramentas MCP: cada operação é tanto um comando CLI mcpscope <cmd> quanto uma ferramenta MCP mcpscope_<cmd>, então um agente de codificação pode executar todo o ciclo — nas mesmas sessões que você vê na interface.

Como se compara

Muitas ferramentas boas tocam partes desse espaço; a diferença é qual parte do ciclo elas atendem e quem elas mantêm nele.

• MCP Inspector cutuca um servidor MCP no nível do protocolo — lista ferramentas, chama-as manualmente. Não há modelo no ciclo; o mcpscope testa o que um modelo realmente faz com seu servidor.
• mcpsnoop captura tráfego MCP real cliente↔servidor na rede. O mcpscope executa o modelo em si e atribui cada token de contexto.
• MCPJam é o vizinho mais próximo: um playground de LLM com evals e rastreamentos. O mcpscope difere na atribuição de tokens por parte, estatísticas de confiabilidade pass@k / pass^k e na paridade humano+agente sobre um armazenamento compartilhado.
• promptfoo, mcp-eval e DeepEval são harnesses de eval orientados a configuração ou código, no seu melhor como portões de regressão não supervisionados em CI. O mcpscope é o workbench interativo para o ciclo de iteração antes disso — e expõe as mesmas operações via CLI/MCP para que um agente também possa conduzi-lo.
• MCPBench, MCP-Bench e MCPMark avaliam modelos contra conjuntos fixos de servidores. O mcpscope avalia seu servidor contra os modelos que você escolhe.
• LM Studio e Open WebUI são interfaces de chat com suporte a ferramentas — apenas para o humano, com contagens agregadas de tokens no máximo. O LM Studio é um dos backends suportados do mcpscope, não um concorrente.

Se um desses se encaixa melhor no seu fluxo de trabalho, use-o — vários são excelentes. O mcpscope é para o ciclo onde você e seu agente de codificação iteram juntos no seu próprio servidor MCP.

Documentação

Começando

• TUTORIAL.md - instalar, configurar, executar uma sessão e avaliar um servidor MCP
• EXAMPLE.md - o exemplo trabalhado: inspecionar → avaliar → mudar uma coisa → observar a métrica se mover
• CONFIG.md - a referência mcpscope.config.json, incluindo configuração totalmente headless
• COMPANIONS.md - servidores MCP complementares integrados e sem configuração que você pode selecionar sem qualquer setup
• BENCHMARK.md - modelo de suíte/caso/execução de benchmark, métricas determinísticas e avaliação de rubrica com LLM

Interfaces

• MCP.md - interface MCP: transporte, superfície de ferramentas e resultados estruturados
• CLI.md - comandos CLI, flags, formato de saída e códigos de saída
• EMBEDDING.md - incorpore o pacote mcpscope-engine no seu próprio aplicativo Node.js/TypeScript: createEngine(), configuração, sessões, eventos e uma integração completa com Express
• mcpscope-chat-template - um aplicativo inicial que pode ser bifurcado construído no mecanismo: servidor MCP + loop de agente + interface de chat incorporável em um processo Node, com documentação sobre design de ferramentas MCP

Internos e contribuição

• DEVELOPMENT.md - executar a partir do código-fonte, build, utilitários de desenvolvimento e notas do repositório
• AGENTS.md - guia para agentes de codificação de IA que trabalham no próprio mcpscope: formato do projeto, princípio de paridade, estilo de trabalho, validação
• ARCHITECTURE.md - design do sistema, persistência, streaming, replay e superfície da API
• PROVIDERS.md - detalhes internos dos provedores (LM Studio, Ollama, OpenRouter): tokens de raciocínio, contagem de tokens, janelas de contexto, carregamento/descarregamento de modelos (incl. troca automática)
• DATA-MODEL.md - árvore de runtime canônica, taxonomia de partes e IDs
• DATABASE-SCHEMA.md - tabelas SQLite, chaves estrangeiras e diagrama ER
• DESIGN-SYSTEM.md - sistema de design do frontend: os tokens, primitivos e padrões que mantêm a GUI consistente
• design-assets/ - SVGs mestres do logotipo (logo, marca, wordmark, favicon); veja o README dele
• TESTING.md - estratégia de testes, replay e como adicionar regressões
• RELEASING.md - fluxo de release orientado por tags: publicação npm, imagem GHCR e instaladores para desktop

Documentação interna/de contribuidores fica em docs/; guias voltados ao usuário permanecem na raiz do repositório.