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	テストデータを更新（取得後にマージ）
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 のリリースワークフローを使用しています。

• ユーザーに見える変更には変更セットを追加してください：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 ライセンス