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 リリースと、宣言された下限未満のセキュリティパッチレベルをブロックします。

Related MCP server: TestRail MCP Server

要件

• 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 testlink-mcp@1.0.0

MCP クライアント設定:

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

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

ツール

すべてのツールは以下を返します:

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

失敗時は ok: false と { code, message, retryable, details? } を返します。利用側はメッセージ本文ではなく error.code で分岐してください。

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

1. 既存のケースを検索し、現在のバージョンを取得します。

2. 目的のテストケースを検証します。

3. 該当するプレビューツールを呼び出します。

4. proposedChanges をユーザーに提示し、明示的な確認を得ます。

5. プレビュー ID と confirm: true を指定して 10 分以内に適用を呼び出します。

6. 適用が CONFLICT または PREVIEW_EXPIRED を返した場合は、新しいプレビューを作成して再確認します。

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

TESTLINK_WRITE_ENABLED=true npx -y testlink-mcp@1.0.0

デフォルトの台帳パスは ~/.local/state/testlink-mcp/operations.jsonl です。TESTLINK_LEDGER_PATH で上書きできます。台帳にはハッシュと秘匿化された結果のみが記録され、開発者キーは含まれません。

設定

デモモードは明示的であり、リモート設定よりも優先されます:

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/easonlin/testlink-mcp:1.0.0。

リリースポリシー

バージョン 1.0.0 はリリース準備完了ですが、公開は明示的な操作として残されています。保護されたリリースワークフローでは、署名付きバージョンタグの要求、完全なテスト/評価/監査/SBOM/パッケージゲートの再実行、provenance 付き npm 公開、SBOM と provenance 付きマルチアーキテクチャ GHCR イメージの公開、GitHub Release の作成、最後に検証済み MCP Registry エントリの公開が行われます。

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

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

mcp-publisher validate server.json

公開リファレンス

• TestLink 1.9.20 ソースとリリースブランチ

• Model Context Protocol TypeScript SDK

• 公式 MCP Registry パブリッシャーコマンド

ライセンス

MIT