@testneo/mcp-server (v1)

Servidor del Protocolo de Contexto de Modelo (MCP) para flujos de trabajo de calidad de TestNeo.

Este servidor expone herramientas de ejecución/proyecto de TestNeo a clientes IDE compatibles con MCP (Cursor, Claude Desktop, clientes MCP de VS Code, etc.).

Espejo público (MCP Market / GitHub)

El espejo de código abierto independiente utilizado para listados y uso compartido es:

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

Este directorio es la fuente de verdad dentro del monorepo de la API de TestNeo. Para actualizar el repositorio público después de cambiar este paquete, ejecute:

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

Luego git commit + git push desde ese clon. Licencia: GPL-3.0 — consulte LICENSE. Reporte de seguridad: consulte SECURITY.md.

Related MCP server: code-graph-mcp

Respuestas

• Cada herramienta fusiona _telemetry en los resultados JSON: request_id, tool, duration_ms, backend_paths (METHOD path por llamada al backend rastreada desde este proceso), además del marcador de esquema telemetry_schema_version y dimensiones de mejor esfuerzo (project_id, tenant_id anulable).

• testneo_get_failure_bundle (y los pasos de testneo_run_agent_workflow con mucha clasificación) pueden incluir suggested_nlp_patch cuando include_nlp_patch_suggestion es verdadero (predeterminado). Lista completa de herramientas y contratos: docs/MCP_TOOL_REFERENCE.md (mantenido sincronizado con el docs/mcp-tool-reference.md del monorepo a través de scripts/sync-public-mcp-repo.sh).

• Precondiciones de ejecución del proyecto (activadas por defecto): las herramientas de generación y de la familia de ejecución devuelven project_precondition_failed a menos que el proyecto resuelva una URL base http(s) real (website_url o variable de entorno base_url). Rechaza marcadores de posición example.com. Deshabilite solo para casos especiales: TESTNEO_MCP_RELAX_PROJECT_PRECONDITIONS=true.

• Normalización del contrato de ejecución: las herramientas de inteligencia de ejecución emiten contract_version: execution_intelligence.v1 y estados canónicos (queued | running | passed | failed | cancelled | unknown) mientras preservan el estado crudo del backend.

Alcance de v1

Herramientas de lectura intensiva + acciones de escritura protegidas:

• testneo_validate_connection

• testneo_list_projects

• testneo_get_project_route_map (leer mapa/perfil de endurecimiento de rutas a nivel de proyecto)

• testneo_list_unified_contexts (explorar contextos por nombre + id)

• testneo_get_unified_context_by_name (resolver context_id sin la interfaz de usuario)

• 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 (ETL de Figma + creación de contexto unificado)

• testneo_generate_tests_from_context (contexto unificado -> generación de pruebas NLP; endurecimiento de rutas opcional)

• testneo_preview_generated_tests (vista previa con intervención humana: NLP + borradores de especificaciones de Playwright)

• testneo_apply_route_hardening (solo lectura: normalizar líneas vagas de Navegación usando mapas de frases)

• testneo_set_project_route_map (persistir mapa/perfil de rutas a nivel de proyecto; escritura protegida)

• testneo_execute_generated_test_case (ejecución protegida de pruebas generadas aprobadas)

• testneo_update_test_case_nlp (actualizar comandos NLP para una prueba generada)

• testneo_export_playwright_spec (exportar prueba generada como .spec.ts del SDK de Playwright)

• testneo_run_playwright_spec_preview (ejecutar flujo ai.run analizado desde el borrador de especificación)

• testneo_figma_to_tests_workflow (flujo de extremo a extremo Figma -> Contexto -> Pruebas -> Vista previa)

• testneo_search_failures

• testneo_rerun_failed (vista previa por defecto; la ejecución requiere TESTNEO_MCP_ALLOW_WRITE=true y confirm=true)

• testneo_trigger_playwright_execution (requiere TESTNEO_MCP_ALLOW_WRITE=true y confirm=true)

• Inteligencia Swagger/OpenAPI

  • testneo_swagger_preview (solo lectura: analizar especificación desde base64 → etiquetas, conteo de endpoints)

  • testneo_swagger_upload_and_generate (proyecto web: Swagger + reglas de negocio opcionales → contexto + pruebas NLP; escritura + confirmación)

  • testneo_swagger_impact_analysis / testneo_swagger_impact_actions (web: diferencia vs instantánea, acciones de clasificación; escritura + confirmación)

  • testneo_api_project_upload_openapi / testneo_api_project_openapi_impact (proyectos API clásicos; escritura + confirmación)

Configuración

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

Entorno requerido:

• TESTNEO_BASE_URL (ejemplo: http://localhost:8001)

• TESTNEO_API_KEY

Opcional:

• TESTNEO_MCP_ALLOW_WRITE=false (predeterminado)

• TESTNEO_MCP_RELAX_PROJECT_PRECONDITIONS=false (predeterminado) — establezca true solo para omitir las comprobaciones de URL base ejecutable en herramientas de generación/ejecución

• TESTNEO_MCP_TELEMETRY_JSONL=false (predeterminado) — establezca true para emitir una línea JSON por invocación de herramienta a stderr (outcome, request_id, duration_ms, backend_paths)

• TESTNEO_MCP_POLICY_MODE=strict (predeterminado) o warn — comportamiento de la política de precondiciones (strict bloquea ante hallazgos bloqueantes, warn degrada algunas comprobaciones)

• TESTNEO_MCP_TIMEOUT_MS=20000

• TESTNEO_MCP_SWAGGER_TIMEOUT_MS=120000 (Swagger multipart + llamadas pesadas de impacto OpenAPI JSON)

• TESTNEO_MCP_USER_AGENT=@testneo/mcp-server

• TESTNEO_ROUTE_HARDENING=true (predeterminado) — establezca false para deshabilitar las reescrituras de frase→ruta globalmente

• TESTNEO_ROUTE_PROFILE=none (predeterminado) o saucedemo — mapa de frases preestablecido opcional (no requerido para otras aplicaciones)

• TESTNEO_ROUTE_MAP_JSON — objeto JSON de frase → ruta (ej. {"checkout overview":"/checkout"}); fusionado sobre el preajuste cuando el perfil es saucedemo, o usado solo cuando el perfil es none. Las rutas deben comenzar con /.

Generación: testneo_generate_tests_from_context tiene como valor predeterminado auto_align_saucedemo_route_map=true, por lo que las líneas de Navegación obtienen URLs de SauceDemo cuando el preajuste de autenticación es SauceDemo y no tiene un mapa de entorno personalizado (profile none, mapa JSON vacío).

Pruebas (sin API)

Ejecuta una compilación de producción, luego el endurecimiento de rutas, el descubrimiento de contexto unificado y los clasificadores de precondiciones del proyecto (sin llamadas HTTP a la API de TestNeo):

npm test

Verificación de humo

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

Comando Cursor/IDE

El comando MCP debería ejecutar:

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

Consulte docs/IDE_SETUP.md para obtener orientación sobre la configuración y ejemplos de prompts.

Notas de seguridad

• La clave API solo se lee desde el entorno.

• La herramienta de escritura está deshabilitada por defecto.

• La herramienta de activación requiere explícitamente confirm=true.

• Las herramientas de escritura admiten idempotency_key opcional para evitar la repetición/ejecución duplicada en reintentos.

Flujos de trabajo de agentes (Fase 2A)

testneo_run_agent_workflow añade una capa de orquestación sobre las herramientas principales y devuelve rastros de pasos estructurados:

• triage_failure_workflow: fallos recientes -> paquetes de fallos principales -> temas recurrentes

• rerun_decision_workflow: fallos recientes -> planificación de candidatos para reejecución (primero vista previa)

• qa_intelligence_workflow: informe de inteligencia unificado (tendencia + fallos + clasificación + vista previa de reejecución)

Flujos de trabajo de Figma a pruebas (Fase 2B)

MCP ahora admite la generación basada en contexto con aprobación humana:

• Ingerir metadatos de Figma y vincular la salida ETL en un contexto unificado

• Generar pruebas NLP a partir de entidades de contexto a través de la tubería LangGraph existente

• Previsualizar las pruebas generadas tanto en formato NLP como en formato de borrador .spec.ts del SDK de Playwright

• Ejecutar las pruebas generadas aprobadas a través de acciones de escritura protegidas