Apidog tests MCP

apidog-tests-mcp

Servidor MCP (Model Context Protocol) para gerenciar casos de teste, cenários, suítes e dados de teste do Apidog. Dá aos assistentes de IA acesso total de leitura/escrita aos recursos de gerenciamento de testes do Apidog.

Este projeto não é uma integração oficial do Apidog.

Recursos

• Casos de Teste — Criar, ler, atualizar, excluir e criar em massa casos de teste para endpoints de API
• Cenários de Teste — Construir fluxos de teste de várias etapas encadeando múltiplas chamadas de API
• Suítes de Teste — Organizar testes em suítes executáveis para CI/CD
• Dados de Teste — Gerenciar iterações de teste orientadas por dados com dados formatados em CSV
• Pastas — Organizar cenários e suítes em estruturas de pastas aninhadas
• Ferramentas somente leitura — Listar ambientes, endpoints, categorias, tags, executores e estatísticas de cobertura

Documentação

• docs/PRACTICAL-USAGE.md — padrões comprovados para criar casos de teste/cenários/suítes estáveis
• SECURITY.md — diretrizes de relato de vulnerabilidades e uso seguro
• CONTRIBUTING.md — fluxo de contribuição
• CHANGELOG.md — notas de versão

Instalação

npm install -g @acabala/apidog-tests-mcp

Ou use diretamente com npx:

npx @acabala/apidog-tests-mcp

Configuração

O servidor requer estas variáveis de ambiente:

Variável	Obrigatória	Descrição
APIDOG_ACCESS_TOKEN	Sim	Seu token de acesso do Apidog
APIDOG_PROJECT_ID	Sim	O ID do projeto Apidog
APIDOG_BRANCH_ID	Sim	O ID do branch com o qual trabalhar
APIDOG_BASE_URL	Não	Substituir a URL base da API (padrão: https://api.apidog.com/api/v1)

Configuração do Cliente MCP

Adicione à configuração do seu cliente MCP (ex.: Claude Desktop claude_desktop_config.json):

{
	"mcpServers": {
		"apidog-tests": {
			"command": "npx",
			"args": ["@acabala/apidog-tests-mcp"],
			"env": {
				"APIDOG_ACCESS_TOKEN": "your-token",
				"APIDOG_PROJECT_ID": "your-project-id",
				"APIDOG_BRANCH_ID": "your-branch-id"
			}
		}
	}
}

Práticas Recomendadas de Token

• Use um token dedicado para automação.
• Limite o acesso ao(s) projeto(s) Apidog mínimo(s) necessário(s).
• Rotacione os tokens regularmente.
• Mantenha os arquivos de configuração do cliente MCP locais/privados.

Ferramentas Disponíveis

Somente leitura

Ferramenta	Descrição
list_environments	Listar todos os ambientes com URLs base
list_api_endpoints	Listar árvore de endpoints de API (filtrável por módulo e nome)
list_test_case_categories	Listar categorias de casos de teste
list_test_case_tags	Listar tags disponíveis
list_runners	Listar executores de teste auto-hospedados
get_endpoint_statistics	Obter estatísticas de cobertura de teste

Casos de Teste

Ferramenta	Descrição
list_test_cases	Listar todos os casos de teste (filtrável por endpoint)
get_test_case	Obter detalhes completos do caso de teste
create_test_case	Criar um caso de teste para um endpoint
create_test_cases_bulk	Criar vários casos de teste de uma vez
update_test_case	Atualizar um caso de teste (obter e depois mesclar)
delete_test_case	Excluir um caso de teste

Cenários de Teste

Ferramenta	Descrição
list_test_scenarios	Listar cenários com estrutura de pastas
get_test_scenario_steps	Obter etapas de um cenário
create_test_scenario	Criar um cenário de teste de várias etapas
update_test_scenario_steps	Definir/substituir etapas do cenário
delete_test_scenario	Excluir um cenário

Suítes de Teste

Ferramenta	Descrição
list_test_suites	Listar suítes com estrutura de pastas
get_test_suite	Obter detalhes completos da suíte
create_test_suite	Criar uma suíte de teste
update_test_suite_items	Definir itens da suíte (grupos estáticos/dinâmicos)
delete_test_suite	Excluir uma suíte

Dados de Teste

Ferramenta	Descrição
list_test_data	Listar registros de dados de teste para um caso de teste
get_test_data	Obter dados de teste com linhas e colunas CSV
create_test_data	Criar dados de teste para um caso de teste
update_test_data	Atualizar dados de teste (obter e depois mesclar)
delete_test_data	Excluir um registro de dados de teste

Pastas

Ferramenta	Descrição
create_scenario_folder	Criar uma pasta de cenário
delete_scenario_folder	Excluir uma pasta de cenário
create_suite_folder	Criar uma pasta de suíte

Desenvolvimento

# Install dependencies
npm install

# Run in development mode
npm run start:dev

# Type check
npm run typecheck

# Format
npm run format

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build for production
npm run build

Segurança

• Use um token de automação dedicado com as permissões mínimas necessárias.
• Nunca envie APIDOG_ACCESS_TOKEN ou IDs específicos de ambiente para o repositório.
• Mantenha os arquivos de configuração do cliente MCP locais e privados.
• Consulte SECURITY.md para a política de relato e resposta.

Lançamento e Versionamento

Este repositório usa Changesets e um fluxo de trabalho de lançamento com GitHub Actions:

• Adicione um changeset para alterações visíveis ao usuário: npm run changeset
• A automação de lançamento cria/atualiza um PR de versão em main
• O PR de lançamento mesclado publica no npm com proveniência

Diretrizes de Código Aberto

• Guia de contribuição: CONTRIBUTING.md
• Código de conduta: CODE_OF_CONDUCT.md
• Changelog: CHANGELOG.md

Dicas Práticas

• Sempre inclua path e parameters.path ao criar casos de teste com parâmetros de rota.
• Para operações de atualização, prefira as ferramentas de mesclagem deste servidor em vez de cargas úteis de substituição completa.
• Use pós-processadores customScript para asserções, a fim de evitar problemas de executor com asserções declarativas.
• Consulte docs/PRACTICAL-USAGE.md para exemplos completos.

Estrutura do Projeto

src/
  index.ts          Entry point, registers tools and starts MCP server
  client.ts         ApidogClient HTTP wrapper with auth headers
  types.ts          Shared TypeScript interfaces and MCP result helpers
  errors.ts         Custom error classes (ApidogApiError, ApidogConfigError)
  schemas.ts        Shared Zod schemas for request parameters
  tools/
    read.ts         Read-only tools (environments, endpoints, categories, etc.)
    test-cases.ts   Test case CRUD tools
    test-scenarios.ts  Test scenario CRUD tools
    test-suites.ts  Test suite CRUD tools
    test-data.ts    Test data CRUD tools
    folders.ts      Folder management tools

Licença

Licença MIT