apidog-tests-mcp

apidog-tests-mcp

用于管理 Apidog 测试用例、场景、套件和测试数据的 MCP（Model Context Protocol）服务。为 AI 助手提供对 Apidog 测试管理功能的完整读写权限。

此项目并非 Apidog 官方集成。

功能

• 测试用例 -- 为 API 端点创建、读取、更新、删除测试用例，也可批量创建
• 测试场景 -- 构建由多个 API 调用串联而成的多步骤测试流程
• 测试套件 -- 将测试整理为可在 CI/CD 中运行的套件
• 测试数据 -- 使用 CSV 格式的数据管理数据驱动测试迭代
• 文件夹 -- 将场景和套件整理到嵌套文件夹结构中
• 只读工具 -- 列出环境、端点、类别、标签、运行器和覆盖率统计数据

文档

• docs/PRACTICAL-USAGE.md -- 创建稳定的测试用例、场景和套件的成熟模式
• SECURITY.md -- 漏洞报告和安全使用指南
• CONTRIBUTING.md -- 贡献工作流
• CHANGELOG.md -- 发行说明

安装

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

或者使用 npx 直接运行：

npx @acabala/apidog-tests-mcp

配置

此服务需要设置以下环境变量：

变量	必需	描述
APIDOG_ACCESS_TOKEN	是	你的 Apidog 访问令牌
APIDOG_PROJECT_ID	是	Apidog 项目 ID
APIDOG_BRANCH_ID	是	要使用的分支 ID
APIDOG_BASE_URL	否	覆盖 API 基础 URL（默认值：https://api.apidog.com/api/v1）

MCP 客户端配置

添加到 MCP 客户端配置中（例如 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"
			}
		}
	}
}

推荐的令牌实践

• 使用专用令牌进行自动化操作。
• 将访问范围限制为所需的最少 Apidog 项目。
• 定期轮换令牌。
• 将 MCP 客户端配置文件保存在本地并妥善保管。

可用工具

只读

工具	描述
list_environments	列出所有环境及其基础 URL
list_api_endpoints	列出 API 端点树（可按模块和名称筛选）
list_test_case_categories	列出测试用例类别
list_test_case_tags	列出可用标签
list_runners	列出可自托管的测试运行器
get_endpoint_statistics	获取测试覆盖率统计数据

测试用例

工具	描述
list_test_cases	列出所有测试用例（可按端点筛选）
get_test_case	获取完整的测试用例详情
create_test_case	为端点创建测试用例
create_test_cases_bulk	一次创建多个测试用例
update_test_case	更新测试用例（先 GET 再合并）
delete_test_case	删除测试用例

测试场景

工具	描述
list_test_scenarios	列出场景及其文件夹结构
get_test_scenario_steps	获取场景的步骤
create_test_scenario	创建多步骤测试场景
update_test_scenario_steps	设置/替换场景步骤
delete_test_scenario	删除场景

测试套件

工具	描述
list_test_suites	列出套件及其文件夹结构
get_test_suite	获取套件完整详情
create_test_suite	创建测试套件
update_test_suite_items	设置套件项（静态/动态分组）
delete_test_suite	删除套件

测试数据

工具	描述
list_test_data	列出测试用例的测试数据记录
get_test_data	获取包含 CSV 行和列的测试数据
create_test_data	为测试用例创建测试数据
update_test_data	更新测试数据（先 GET，再合并）
delete_test_data	删除测试数据记录

文件夹

工具	描述
create_scenario_folder	创建场景文件夹
delete_scenario_folder	删除场景文件夹
create_suite_folder	创建套件文件夹

开发

# 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

安全

• 使用具有最低所需权限的专用自动化令牌。
• 切勿提交 APIDOG_ACCESS_TOKEN 或特定于环境的 ID。
• 妥善保管本地 MCP 客户端配置文件。
• 有关报告和响应政策，请参阅 SECURITY.md。

发布和版本管理

此代码库使用 Changesets 和 GitHub Actions 发布工作流：

• 对用户可见的更改，请添加一个 changeset：npm run changeset
• 发布自动化会在 main 上创建/更新版本 PR
• 合并发布 PR 后，会通过 npm 发布并附带来源证明

开源指南

• 贡献指南：CONTRIBUTING.md
• 行为准则：CODE_OF_CONDUCT.md
• 更新日志：CHANGELOG.md

实用技巧

• 创建包含路由参数的测试用例时，始终提供 path 和 parameters.path。
• 对于更新操作，优先使用此服务的合并式工具，而不是原始的完整替换负载。
• 使用 customScript 后处理器进行断言，避免声明式断言导致运行器问题。
• 完整示例请参阅 docs/PRACTICAL-USAGE.md。

项目结构

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

许可证

MIT 许可证