@testneo/mcp-server (v1)

用于 TestNeo 质量工作流的模型上下文协议 (MCP) 服务器。

该服务器向兼容 MCP 的 IDE 客户端（Cursor、Claude Desktop、VS Code MCP 客户端等）公开 TestNeo 项目/执行工具。

公共镜像 (MCP Market / GitHub)

用于列表展示和共享的独立开源镜像地址为：

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

此目录是 TestNeo API 单体仓库内的事实来源。在修改此包后，若要刷新公共仓库，请运行：

./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

响应

• 每个工具都会将 _telemetry 合并到 JSON 结果中：包含 request_id、tool、duration_ms、backend_paths（从该进程追踪到的每个后端调用的 METHOD path），以及模式标记 telemetry_schema_version 和尽力而为的维度（project_id，可为空的 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 保持同步）。

• 项目执行前提条件（默认开启）： 生成和执行类工具会返回 project_precondition_failed，除非项目解析出一个真实的 http(s) 基础 URL（website_url 或环境变量 base_url）。拒绝 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（只读：使用短语映射规范化模糊的导航行）

• 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（默认） — 设置为 true 以将每个工具调用的 JSON 行输出到 stderr（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，因此当 auth 预设为 SauceDemo 且您没有自定义环境变量映射（profile 为 none，JSON 映射为空）时，导航行会获取 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 草案格式预览生成的测试

• 通过受保护的写入操作执行已批准的生成测试