testlink-mcp

testlink-mcp

TestLink 1.9.20 向けの、AI に配慮した安全性優先の Model Context Protocol サーバーです。正規化された探索・分析ツール、上限付きカーソルページネーション、構造化出力、適用前プレビューを介した書き込み機能を stdio 経由で提供します。

このリポジトリは、TestLink の公開 XML-RPC インターフェースと公開 MCP SDK を基にした、クリーンな実装です。非公開の TestLink パッケージや非公開のソースツリーには依存していません。

主な機能

• 認証情報なしで起動し、MCP クライアントからすべてのツール、リソース、プロンプトを検出できます。
• 評価とオンボーディング向けに、明示的な決定論的デモモードを備えています。
• structuredContent、outputSchema、ツールのアノテーション、カーソルページネーション、安定したエラーコードに対応しています。
• 添付ファイルのメタデータのみを扱い、添付ファイルの内容と base64 ペイロードは除外されます。
• 書き込みはデフォルトで無効です。削除ツールはありません。
• すべての適用には、confirm: true、有効期限が切れていない単回使用の10分間プレビュー、変更されていないサーバースナップショットが必要です。
• 副作用のある呼び出しは自動的に再試行されません。適用の試行は、機密情報を除去した操作台帳に記録されます。
• 実行時ガードにより、サポート対象外／EOL の奇数 Node リリースと、宣言された下限を下回るセキュリティパッチレベルをブロックします。

安全な書き込みのデモ

デモでは合成データのみを使用します。必須の安全境界を示しています。 変更案をプレビューし、上限付きの差分を確認してから、正確なプレビュー ID と confirm: true を指定して apply を呼び出します。プレビュー中に書き込みは行われません。 編集可能なソースフレームは docs/assets/testlink-safety にあります。

要件

• Node.js ^22.23.2 || ^24.18.1 || ^26.5.1
• XML-RPC API が有効な TestLink 1.9.20

開発環境およびコンテナーのベースラインは Node 24.19.0 LTS です。CI では Node 22.23.2 と 26.7.0 でも実行します。

クイックスタート

nvm use
npm ci
npm run build
TESTLINK_DEMO_MODE=true node dist/cli.js

公開後の npm 呼び出し：

npx -y [email protected]

MCP クライアントの設定：

{
  "mcpServers": {
    "testlink": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "TESTLINK_URL": "https://testlink.example.com/testlink",
        "TESTLINK_DEV_KEY": "your-testlink-dev-key"
      }
    }
  }
}

実際の認証情報を追跡対象ファイルに記載しないでください。.env.example を無視対象の .env にコピーするか、MCP クライアント／シークレットマネージャーから環境変数を注入してください。

ツール

ワークフロー	ツール	目的
開始	testlink_get_server_capabilities	設定、互換性、デモモード、書き込みポリシーを確認する
探索	testlink_list_projects	プロジェクトを一覧表示する
探索	testlink_list_test_plans	プロジェクト内のテスト計画を一覧表示する
探索	testlink_list_builds	テスト計画内のビルドを一覧表示する
探索	testlink_list_test_suites	1階層分のテストスイートをたどる
分析	testlink_search_test_cases	範囲を限定したプロジェクト／スイート内でテストケースを検索する
分析	testlink_get_test_case	正規化されたテストケースを1件取得する
分析	testlink_list_test_case_attachments	安全な添付ファイルのメタデータを取得する
分析	testlink_get_traceability	要件リンクと、必須のテスト計画1件への所属を確認する
分析	testlink_get_execution_history	最近の実行エビデンスを確認する
検証	testlink_validate_test_case	不完全または曖昧なテストケースの内容を検出する
プレビュー	testlink_preview_test_case_sync	作成／更新とテスト計画への所属をプレビューする
適用	testlink_apply_test_case_sync	変更されていない、確認済みの同期プレビューを適用する
プレビュー	testlink_preview_execution_result	passed／failed／blocked の報告をプレビューする
適用	testlink_apply_execution_result	変更されていない、確認済みの結果プレビューを適用する

すべてのツールは次を返します。

{
  "ok": true,
  "data": {},
  "meta": {
    "source": "testlink",
    "requestId": "..."
  }
}

失敗時は { code, message, retryable, details? } を伴う ok: false が返されます。利用側ではメッセージ文ではなく、error.code に基づいて処理を分岐してください。

安全な書き込みワークフロー

1. 既存のケースを検索し、現在のバージョンを取得します。
2. 目的のテストケースを検証します。
3. 該当するプレビューツールを呼び出します。
4. 作成する場合は、TestLink の authorLogin を指定します。TestLink 1.9.20 では、desiredCase.suiteId、summary、steps も必須です。
5. proposedChanges をユーザーに提示し、明示的な確認を得ます。
6. プレビュー ID と confirm: true を指定して、10 分以内に適用を呼び出します。
7. 確認済みの適用では、副作用が発生する前にプレビューが消費されます。成功、競合、失敗のいずれの場合も、再試行する前に新しいプレビューを作成して確認してください。
8. 適用が OUTCOME_UNKNOWN を返した場合は、再試行しないでください。リモートへの書き込みが成功した可能性があるため、まず TestLink のケース、プランのメンバーシップ、または実行結果を照合してください。

書き込みを有効にするのは、書き込みを実行するサーバープロセスだけにしてください。

TESTLINK_WRITE_ENABLED=true npx -y [email protected]

デフォルトの台帳パスは ~/.local/state/testlink-mcp/operations.jsonl です。TESTLINK_LEDGER_PATH で変更できます。リモートへの書き込み前に、サーバーは attempted 行を永続化し、その後 applied または outcome_unknown を記録します。台帳にはハッシュと秘匿化された結果のみが含まれ、開発者キーは含まれません。

設定

変数	デフォルト	意味
TESTLINK_URL	未設定	TestLink のベース URL または完全な XML-RPC エンドポイント
TESTLINK_DEV_KEY	未設定	TestLink の個人用 API キー
TESTLINK_DEMO_MODE	false	決定論的なローカルのデモデータを使用します
TESTLINK_WRITE_ENABLED	false	確認済みの適用ツールを許可します
TESTLINK_REQUEST_TIMEOUT_MS	30000	リクエストのタイムアウト。100～300000 ms
TESTLINK_MAX_RESPONSE_BYTES	5242880	XML レスポンスの最大サイズ
TESTLINK_LEDGER_PATH	ユーザーの状態ディレクトリ	秘匿化された JSONL 操作台帳
NODE_EXTRA_CA_CERTS	未設定	追加の CA バンドル（任意）。TLS 検証は引き続き有効です

デモモードは明示的に指定し、リモート設定より優先されます。

TESTLINK_DEMO_MODE=true TESTLINK_WRITE_ENABLED=true node dist/cli.js

開発

npm ci
npm run check
npm test
npm run eval
npm run build
npm audit --omit=dev --audit-level=high
npm pack --dry-run

オフラインのツール選択評価では、一般的なユーザーの意図に応じて、検索、検証、プレビュー、適用の各ツールが個別に選択されることを確認します。これは決定論的に実行され、外部モデルにデータを送信しません。

Docker

イメージは非 root ユーザーとして実行され、Node 24.19.0 を使用します。プッシュせずにビルドするには、次のコマンドを実行します。

docker buildx build --platform linux/amd64,linux/arm64 --tag testlink-mcp:local --output type=oci,dest=testlink-mcp.oci.tar .

承認および公開後のイメージ名：ghcr.io/eason0in/testlink-mcp:1.0.8。

リリースポリシー

バージョン 1.0.8 はリリース可能な状態ですが、公開は明示的な操作として行います。保護されたリリースワークフローでは、署名済みのバージョンタグが必要です。テスト／評価／監査／SBOM／パッケージのすべてのゲートを再実行し、プロベナンス付きで npm に公開します。さらに、SBOM とプロベナンスを含むマルチアーキテクチャの GHCR イメージを公開し、GitHub Release を作成した後、検証済みの MCP Registry エントリーを公開します。

これとは別の保護されたライブスモークワークフローでは、読み取り専用の呼び出しを使い、インストール済みパッケージを実際の TestLink 1.9.20 インスタンスに対して検証します。URL と開発者キーは環境シークレットとして保存する必要があり、ログに書き込まれることはありません。

パッケージマニフェストと server.json は、MCP 名 io.github.Eason0in/testlink-mcp を共有します。公開せずにレジストリの検証を実行できます。

mcp-publisher validate server.json

npm、MCP Registry、Glama、MCP.so のアカウント側の設定と提出データは、マーケットプレイス提出チェックリストで管理されています。

公開情報

• TestLink 1.9.20 のソースとリリースブランチ
• Model Context Protocol TypeScript SDK
• MCP Registry 公式パブリッシャーコマンド

ライセンス

MIT