@testneo/mcp-server (v1)

TestNeo品質ワークフロー用のModel Context Protocol (MCP) サーバー。

このサーバーは、TestNeoのプロジェクト/実行ツールをMCP互換のIDEクライアント（Cursor、Claude Desktop、VS Code MCPクライアントなど）に公開します。

公開ミラー (MCP Market / GitHub)

リスト掲載および共有に使用されるスタンドアロンのオープンソースミラーは以下の通りです：

https://github.com/gururajhm-neo/testneo-mcp

このディレクトリは、TestNeo APIモノレポ内の信頼できる唯一の情報源 (source of truth) です。このパッケージを変更した後に公開リポジトリを更新するには、以下を実行してください：

./scripts/sync-public-mcp-repo.sh /path/to/your/local/testneo-mcp-clone

その後、そのクローンから git commit + git push を実行します。ライセンス: GPL-3.0 — LICENSE を参照してください。セキュリティ報告: SECURITY.md を参照してください。

Related MCP server: code-graph-mcp

レスポンス

• すべてのツールは、JSON結果に _telemetry をマージします：request_id、tool、duration_ms、backend_paths（このプロセスからトレースされたバックエンド呼び出しごとの METHOD path）、さらにスキーママーカー telemetry_schema_version とベストエフォートのディメンション（project_id、NULL許容の tenant_id）。

• testneo_get_failure_bundle（およびトリアージ重視の testneo_run_agent_workflow ステップ）には、include_nlp_patch_suggestion が true（デフォルト）の場合、suggested_nlp_patch が含まれることがあります。ツールの全リストとコントラクト：docs/MCP_TOOL_REFERENCE.md（scripts/sync-public-mcp-repo.sh を介してモノレポの docs/mcp-tool-reference.md と同期が保たれています）。

• プロジェクト実行の前提条件（デフォルトでオン）： 生成および実行系のツールは、プロジェクトが実際の http(s) ベースURL（website_url または環境変数 base_url）を解決しない限り、project_precondition_failed を返します。example.com プレースホルダーは拒否されます。特別なケースでのみ無効にしてください：TESTNEO_MCP_RELAX_PROJECT_PRECONDITIONS=true。

• 実行コントラクトの正規化： 実行インテリジェンスツールは、生のバックエンドステータスを保持しつつ、contract_version: execution_intelligence.v1 および正規化されたステータス（queued | running | passed | failed | cancelled | unknown）を出力します。

v1 スコープ

読み取り重視のツール + 保護された書き込みアクション：

• testneo_validate_connection

• testneo_list_projects

• testneo_get_project_route_map（プロジェクトレベルのルート強化マップ/プロファイルの読み取り）

• testneo_list_unified_contexts（名前とIDでコンテキストをブラウズ）

• testneo_get_unified_context_by_name（UIなしで context_id を解決）

• testneo_list_recent_executions

• testneo_get_execution_status

• testneo_get_execution_summary

• testneo_get_execution_logs

• testneo_get_pass_fail_trend

• testneo_watch_execution

• testneo_get_failure_bundle

• testneo_run_agent_workflow (triage_failure_workflow, rerun_decision_workflow, qa_intelligence_workflow)

• testneo_ingest_figma_context（Figma ETL + 統合コンテキスト作成）

• testneo_generate_tests_from_context（統合コンテキスト -> NLPテスト生成；オプションでルート強化）

• testneo_preview_generated_tests（人間によるプレビュー：NLP + Playwright仕様ドラフト）

• testneo_apply_route_hardening（読み取り専用：曖昧なNavigate-to行をフレーズマップを使用して正規化）

• testneo_set_project_route_map（プロジェクトレベルのルートマップ/プロファイルを永続化；保護された書き込み）

• testneo_execute_generated_test_case（承認された生成済みテストの保護された実行）

• testneo_update_test_case_nlp（生成済みテストのNLPコマンドを更新）

• testneo_export_playwright_spec（生成済みテストをPlaywright SDK .spec.ts としてエクスポート）

• testneo_run_playwright_spec_preview（仕様ドラフトから解析された ai.run フローを実行）

• testneo_figma_to_tests_workflow（エンドツーエンドのFigma -> コンテキスト -> テスト -> プレビュー）

• testneo_search_failures

• testneo_rerun_failed（デフォルトでプレビュー；実行には TESTNEO_MCP_ALLOW_WRITE=true および confirm=true が必要）

• testneo_trigger_playwright_execution（TESTNEO_MCP_ALLOW_WRITE=true および confirm=true が必要）

• Swagger/OpenAPI インテリジェンス

  • testneo_swagger_preview（読み取り専用：base64から仕様を解析 → タグ、エンドポイント数）

  • testneo_swagger_upload_and_generate（Webプロジェクト：Swagger + オプションのビジネスルール → コンテキスト + NLPテスト；書き込み + 確認）

  • testneo_swagger_impact_analysis / testneo_swagger_impact_actions（Web：スナップショットとの差分、トリアージアクション；書き込み + 確認）

  • testneo_api_project_upload_openapi / testneo_api_project_openapi_impact（従来のAPIプロジェクト；書き込み + 確認）

セットアップ

cd packages/testneo-mcp-server
npm install
npm run build

必要な環境変数：

• TESTNEO_BASE_URL（例：http://localhost:8001）

• TESTNEO_API_KEY

オプション：

• TESTNEO_MCP_ALLOW_WRITE=false（デフォルト）

• TESTNEO_MCP_RELAX_PROJECT_PRECONDITIONS=false（デフォルト） — 生成/実行ツールで実行可能ベースURLチェックをスキップする場合のみ true に設定

• TESTNEO_MCP_TELEMETRY_JSONL=false（デフォルト） — ツール呼び出しごとに1行のJSONをstderrに出力する場合 true に設定（outcome, request_id, duration_ms, backend_paths）

• TESTNEO_MCP_POLICY_MODE=strict（デフォルト）または warn — 前提条件ポリシーの動作（strict はブロッキング要因の発見時にブロックし、warn は一部のチェックをダウングレードします）

• TESTNEO_MCP_TIMEOUT_MS=20000

• TESTNEO_MCP_SWAGGER_TIMEOUT_MS=120000（Swaggerマルチパート + 大規模なOpenAPIインパクトJSON呼び出し）

• TESTNEO_MCP_USER_AGENT=@testneo/mcp-server

• TESTNEO_ROUTE_HARDENING=true（デフォルト） — フレーズ→パスの書き換えをグローバルに無効にするには false に設定

• TESTNEO_ROUTE_PROFILE=none（デフォルト）または saucedemo — オプションのプリセットフレーズマップ（他のアプリには不要）

• TESTNEO_ROUTE_MAP_JSON — フレーズ→パスのJSONオブジェクト（例：{"checkout overview":"/checkout"}）；プロファイルが saucedemo の場合はプリセットにマージされ、none の場合は単独で使用されます。パスは / で始まる必要があります。

生成： testneo_generate_tests_from_context はデフォルトで auto_align_saucedemo_route_map=true となるため、認証プリセットがSauceDemoでカスタム環境マップがない場合（profile が none、空のJSONマップ）、Navigate行はSauceDemoのURLを取得します。

テスト (APIなし)

プロダクションビルドを実行し、その後ルート強化、統合コンテキスト検出、プロジェクト前提条件分類器を実行します（TestNeo APIへのHTTP呼び出しは行いません）：

npm test

スモークチェック

TESTNEO_BASE_URL="http://localhost:8001" TESTNEO_API_KEY="tn_xxx" npm run smoke

Cursor/IDE コマンド

MCPコマンドは以下を実行する必要があります：

node /absolute/path/to/testneo-api/packages/testneo-mcp-server/dist/index.js

設定のガイダンスとプロンプトの例については、docs/IDE_SETUP.md を参照してください。

セキュリティに関する注意

• APIキーは環境変数からのみ読み取られます。

• 書き込みツールはデフォルトで無効になっています。

• トリガーツールには明示的な confirm=true が必要です。

• 書き込みツールは、再試行時のリプレイや重複実行を防ぐためのオプションの idempotency_key をサポートしています。

エージェントワークフロー (フェーズ 2A)

testneo_run_agent_workflow はコアツールの上にオーケストレーション層を追加し、構造化されたステップトレースを返します：

• triage_failure_workflow: 最近の失敗 -> 上位の失敗バンドル -> 繰り返されるテーマ

• rerun_decision_workflow: 最近の失敗 -> 再実行候補の計画（プレビュー優先）

• qa_intelligence_workflow: 統合インテリジェンスレポート（トレンド + 失敗 + トリアージ + 再実行プレビュー）

Figmaからテストへのワークフロー (フェーズ 2B)

MCPは、人間の承認を伴うコンテキスト駆動型の生成をサポートするようになりました：

• Figmaメタデータをインジェストし、ETL出力を統合コンテキストにリンク

• 既存のLangGraphパイプラインを介して、コンテキストエンティティからNLPテストを生成

• NLPおよびPlaywright SDK .spec.ts ドラフト形式の両方で生成されたテストをプレビュー

• 保護された書き込みアクションを通じて、承認された生成済みテストを実行