M00N Report

@m00nsolutions/mcp-server

Gerenciamento de testes agêntico via MCP. Este servidor permite que um assistente de IA faça o trabalho em vez de apenas ler sobre ele: criar casos de teste, planejar e preencher execuções de teste manuais, vincular automação de volta aos casos que cobre, cortar releases e ler a saúde do projeto no M00N Report, uma plataforma de gerenciamento de testes nativa de IA.

Qual Instalação Eu Preciso?

	Este pacote npm (stdio)	Conector remoto hospedado
Como executa	npx @m00nsolutions/mcp-server como um processo local	Sem processo local; o cliente fala com a API via HTTP
Autenticação	Uma chave MCP em M00N_API_KEY	OAuth 2.1 com PKCE, tela de consentimento do navegador
Clientes	Qualquer cliente MCP: Claude Code, Claude Desktop, Cursor e outros	somente claude.ai e claude.com

Se você não está conectando a partir de claude.ai ou claude.com, use este pacote com uma chave MCP. Esse é o restante deste README. Para o conector, veja o guia do conector.

Requisitos

Node 20 ou mais recente, e qualquer cliente compatível com MCP.

Instalação

Sem etapa de instalação. O cliente o inicia com npx, conforme configurado abaixo.

Para fixar uma versão em um ambiente compartilhado ou de CI, acrescente uma ao nome do pacote em args, como ["-y", "@m00nsolutions/mcp-server@<version>"]. npm view @m00nsolutions/mcp-server versions lista o que é publicado. Um espaço reservado em vez de um número de propósito: um exemplo concreto aqui fica desatualizado no próximo lançamento, e um desatualizado recomenda fixar uma versão que não tem mais as correções atuais.

Início Rápido

1. Obtenha uma chave MCP

No M00N Report, abra Configurações -> Chaves MCP e crie uma chave. Ela começa com m00n_mcp_ seguido de 48 caracteres hexadecimais. Esta não é a credencial que os relatores de teste usam; a deles começa com m00n_ e é recusada aqui.

Uma chave MCP carrega exatamente as permissões da conta à qual pertence, nunca mais, e pode ser reduzida ainda mais. O escopo remove ferramentas da lista que o cliente vê, então uma lista de ferramentas mais curta do que você esperava é uma decisão de escopo, não uma falha.

A chave vai na configuração do seu próprio cliente MCP na sua máquina. Não a coloque em um arquivo de workspace que vive em um repositório.

2. Conecte seu cliente

Claude Code, uma linha:

claude mcp add m00n --env M00N_API_URL=https://m00nreport.com --env M00N_API_KEY=m00n_mcp_... -- npx -y @m00nsolutions/mcp-server

Todo outro cliente usa o mesmo bloco JSON:

{
  "mcpServers": {
    "m00n": {
      "command": "npx",
      "args": ["-y", "@m00nsolutions/mcp-server"],
      "env": {
        "M00N_API_URL": "https://m00nreport.com",
        "M00N_API_KEY": "m00n_mcp_your_key_here"
      }
    }
  }
}

Onde esse bloco vai:

Cliente	Arquivo de configuração
Cursor	~/.cursor/mcp.json
Claude Desktop, macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop, Windows	%APPDATA%\Claude\claude_desktop_config.json

Para uma instância auto-hospedada, aponte M00N_API_URL para sua própria origem raiz, sem sufixo /api. Uma barra final é removida para você.

3. Confirme a conexão

Reinicie o cliente e então pergunte:

Liste meus projetos do M00N Report

Uma lista dos seus projetos significa que o servidor está conectado e a chave é válida. Um erro, ou o assistente dizendo que não tem tal ferramenta, significa que não está; veja Solução de Problemas.

Ferramentas

Oito áreas. A lista completa com argumentos está em /documentation/mcp/tools, mantida ao lado do código. O servidor busca sua própria lista da sua instância na inicialização, então o que seu cliente vê é o que sua instância suportava quando o cliente conectou.

Área	O que cobre
Projetos e análises	Projetos, tendências e estatísticas de lançamento, histórico por teste, busca em testes automatizados
Casos de teste	Criar, ler, atualizar, mover, excluir, editar em massa e vincular um teste automatizado ao caso que cobre
Pastas e suítes	A hierarquia de pastas e suítes, além de estatísticas por pasta
Coleções de teste	Conjuntos de casos nomeados reutilizáveis que entram em qualquer execução
Execuções manuais	Construir uma execução a partir de suítes, coleções ou casos individuais, depois registrar resultados por caso
Releases	Criar e gerenciar releases, e anexar ou desanexar os lançamentos que pertencem a elas
Saúde e cobertura	Uma verificação de saúde composta, lacunas de cobertura em ambas as direções, sugestões de casos, varredura de recursos, exportação de relatórios
Links externos	Anexar e remover tickets Jira ou Linear em um caso

Uma execução é uma execução de teste manual: responsáveis, ambiente, datas e resultados por etapa capturados contra um instantâneo de cada caso no momento em que foi adicionado.

Quantas ferramentas sua chave pode ver vem da sua instância:

curl -s -H "X-MCP-Key: $M00N_API_KEY" "$M00N_API_URL/api/mcp/tools" | jq .count

Uma chave com escopo vê menos. Nenhum número é citado aqui de propósito: a superfície muda com o lançamento, e um número em um README é o único lugar onde ninguém lembra de atualizar.

Prompts

Fluxos de trabalho guiados em várias etapas que o cliente pode oferecer pelo nome. Cada um aceita um único argumento opcional project, um nome ou UUID; omita-o e o servidor escolhe o projeto quando apenas um está no escopo.

Prompt	O que faz
analyze_flaky_tests	Encontrar testes que passam e falham sem uma mudança de código, e classificá-los
debug_test_failure	Trabalhar uma única falha de volta a uma causa a partir de seu histórico e rastros
release_readiness	Julgar se um release é seguro para enviar
generate_test_cases	Rascunhar casos manuais para uma área que não tem nenhum
weekly_health_report	Resumir a semana entre projetos
investigate_regression	Encontrar o que mudou entre uma execução que passou e uma que falhou
run_manual_execution	Levar um ciclo de teste manual da montagem aos resultados por caso

Recursos

Visualizações somente leitura que o cliente pode puxar sem chamar uma ferramenta: todos os projetos, resumo de saúde do projeto, relatório de testes instáveis, testes atualmente falhando, estrutura de pastas, relatório de lançamento, conteúdo de caso de teste, resumo de release.

Configuração

Variável de ambiente	Obrigatória	Padrão	Descrição
M00N_API_URL	para conectar		Sua URL do M00N Report. Origem raiz, sem sufixo /api. Uma barra final é removida para você.
M00N_API_KEY	para conectar		Uma chave MCP (m00n_mcp_...). Qualquer coisa sem esse prefixo é recusada antes da primeira solicitação.
M00N_DEBUG	não	false	Adiciona detalhes por solicitação ao stderr, incluindo os argumentos de cada chamada de ferramenta. Etapas de inicialização e erros são registrados de qualquer forma.
M00N_TIMEOUT_MS	não	30000	Tempo limite de solicitação, um número puro de milissegundos. 60s, 1e4, 30,000 e 1.5 são rejeitados com um aviso no stderr e o padrão é usado em vez disso.
M00N_INSECURE_SSL	não	false	Aceitar um certificado autoassinado. Somente instâncias auto-hospedadas.

Os dois booleanos estão ativados para true, 1 ou yes, em qualquer caso. Qualquer outro valor, false e 0 incluídos, os deixa desativados.

Defina os dois primeiros ou nenhum. Definir apenas um é tratado como um erro e recusado, porque um servidor meio configurado que inicia mesmo assim é mais difícil de diagnosticar do que um que não inicia.

A URL base é M00N_API_URL aqui; os relatores de teste chamam a mesma URL de M00N_SERVER_URL. Todos os seis pacotes leem M00N_API_KEY, mas a deles é uma chave de API de projeto em vez de uma chave MCP, então uma variável de shell exportada não pode servir para ambos.

Executando Sem uma Chave

Iniciado sem M00N_API_URL nem M00N_API_KEY, o servidor executa em modo de pré-visualização: ele lista suas ferramentas, prompts e recursos de um instantâneo empacotado e recusa toda chamada com uma mensagem dizendo o que definir. Nada é enviado a lugar nenhum, porque não há para onde enviar.

É isso que permite que um inspetor, um cliente ou um diretório mostre a superfície de ferramentas antes de alguém se inscrever. É uma descrição do servidor, nunca um funcionando, então as listagens vêm do instantâneo em vez da sua instância: uma chave com escopo normalmente vê menos ferramentas do que o instantâneo mostra.

Os mantenedores atualizam o instantâneo com npm run snapshot:refresh contra uma chave sem escopo.

Auto-Hospedado

Aponte M00N_API_URL para sua própria instância e emita a chave MCP dessa instância. Todo o resto é idêntico, o que importa quando o motivo de você auto-hospedar é que os dados de teste não podem sair da sua rede.

Com um certificado autoassinado, adicione "M00N_INSECURE_SSL": "true" ao mesmo bloco env. Notas completas: /documentation/mcp/self-hosted.

O Que É Enviado

Para M00N_API_URL via HTTPS: as chamadas de ferramenta que seu assistente faz e seus argumentos. O servidor é um proxy para sua própria instância e não armazena nada em si.

Toda chamada de ferramenta é escrita em um log de auditoria MCP com uma interface no aplicativo, e a limitação de taxa por chave limita um agente descontrolado. A chave nunca é escrita nesse log, nem no stderr. Sob M00N_DEBUG, os argumentos de toda chamada de ferramenta são impressos no stderr, então trate essa saída como trataria os próprios dados.

Solução de Problemas

Sintoma	Causa
O cliente não mostra ferramentas do M00N Report	A configuração não foi recarregada. Reinicie o cliente completamente, não apenas a conversa.
As ferramentas estão listadas, mas toda chamada responde running unconfigured	Nem M00N_API_URL nem M00N_API_KEY chegaram ao processo, então ele iniciou em modo de pré-visualização. Verifique se o bloco env realmente se aplica a este servidor.
M00N_API_KEY should start with "m00n_mcp_"	Essa é uma chave de API de projeto, o tipo que os relatores de teste usam. As chaves MCP são separadas: Configurações -> Chaves MCP.
Authentication failed: Invalid or expired MCP key	A chave está errada, revogada ou de outra instância. Ou M00N_API_URL carrega um sufixo /api, o que faz toda solicitação retornar 401 por melhor que seja a chave. Verifique a URL primeiro, depois emita uma nova chave.
WARNING: M00N_API_URL is http://...	Não é um erro, e o servidor continua executando. Significa que a chave é enviada sem criptografia em toda solicitação. Use https a menos que a instância esteja em uma rede privada confiável. Endereços de loopback não avisam.
... redirected to ...	A URL responde com um redirecionamento, e redirecionamentos não são seguidos porque a chave MCP viajaria para onde quer que apontem. Defina M00N_API_URL para o endereço que responde diretamente, geralmente a forma https://.
Cannot connect to M00N Report API at ...	Nada está escutando nessa URL. A instância está fora do ar, ou a porta está fechada para você.
Cannot resolve M00N Report API host	O nome do host não resolve. Um erro de digitação, ou um nome privado acessado de fora de sua rede.
Request to M00N Report API timed out	Aumente M00N_TIMEOUT_MS, ou verifique o caminho de rede.
SSL certificate error connecting to ...	Um certificado autoassinado em uma instância auto-hospedada. Defina M00N_INSECURE_SSL para true.
Not found during ...	O resto da linha é a própria resposta do servidor e geralmente nomeia a correção, como quais projetos existem. Leia antes de mudar uma configuração.
Rate limit exceeded. Retry after Ns.	1000 chamadas de ferramenta por minuto por chave, em uma janela deslizante. A mensagem carrega a espera. Um agente trabalhando em uma tarefa raramente chega perto; atingir isso geralmente significa um loop.
Menos ferramentas do que o esperado	A chave tem escopo de permissão, ou a instância é mais antiga que o pacote. A lista de ferramentas vem da sua instância.

O servidor registra no stderr com ou sem M00N_DEBUG, e a maioria dos clientes o exibe em seu painel MCP. Defina M00N_DEBUG para true para adicionar cada solicitação e seus argumentos.

Limitações Conhecidas

• A lista de ferramentas é lida uma única vez, na inicialização. Reescopar uma chave ou atualizar a instância faz com que o cliente mantenha a lista antiga até que você reinicie o cliente.
• GET /api/health deve estar acessível quando configurado. Ele é verificado antes de qualquer outra coisa e uma falha interrompe o servidor, então um proxy que encaminha apenas /api/mcp/* não mostra nenhuma ferramenta, mesmo que todas funcionariam.
• Uma chave com escopo para zero ferramentas não inicia. O servidor encerra em vez de conectar com uma lista vazia. Este é o caminho configurado; sem nenhuma credencial, ele inicia em modo de pré-visualização.
• Prompts e recursos são opcionais. Se suas listagens falharem, o servidor ainda inicia, com o motivo em stderr, e o cliente não vê nenhum deles durante toda a sessão.
• Redirecionamentos são recusados, não seguidos. A chave viaja em um cabeçalho personalizado, e os seguidores de redirecionamento removem apenas os cabeçalhos de autenticação que reconhecem, então seguir um entregaria a chave a qualquer host que respondesse em seguida. Um redirecionamento é relatado com o endereço para o qual apontava.
• Somente stdio. Para transporte HTTP, use o conector hospedado.

Suporte

• Pacote no npm
• Documentação
• Relatar problemas
• Discord da comunidade

Licença

Licença MIT. Consulte LICENSE.