@testneo/mcp-server (v1)

TestNeo 품질 워크플로우를 위한 MCP(Model Context Protocol) 서버입니다.

이 서버는 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, nullable tenant_id).

• testneo_get_failure_bundle (및 트리아지 중심의 testneo_run_agent_workflow 단계)는 **include_nlp_patch_suggestion**이 true(기본값)일 때 **suggested_nlp_patch**를 포함할 수 있습니다. 전체 도구 목록 및 계약: docs/MCP_TOOL_REFERENCE.md (모노레포의 docs/mcp-tool-reference.md와 scripts/sync-public-mcp-repo.sh를 통해 동기화 유지).

• 프로젝트 실행 전제 조건(기본값 켜짐): 생성 및 실행 계열 도구는 프로젝트가 실제 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 (웹 프로젝트: Swagger + 선택적 비즈니스 규칙 → 컨텍스트 + NLP 테스트; 쓰기 + 확인)

  • testneo_swagger_impact_analysis / testneo_swagger_impact_actions (웹: 스냅샷 대비 차이, 트리아지 작업; 쓰기 + 확인)

  • 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 (기본값) — 도구 호출당 하나의 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이고 사용자 지정 환경 맵이 없는 경우(프로필 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를 지원합니다.

에이전트 워크플로우 (Phase 2A)

testneo_run_agent_workflow는 핵심 도구 위에 오케스트레이션 계층을 추가하고 구조화된 단계 추적을 반환합니다:

• triage_failure_workflow: 최근 실패 -> 상위 실패 번들 -> 반복되는 테마

• rerun_decision_workflow: 최근 실패 -> 재실행 후보 계획 (미리보기 우선)

• qa_intelligence_workflow: 통합 인텔리전스 보고서 (추세 + 실패 + 트리아지 + 재실행 미리보기)

Figma-to-tests 워크플로우 (Phase 2B)

MCP는 이제 인간의 승인을 통한 컨텍스트 기반 생성을 지원합니다:

• Figma 메타데이터를 수집하고 ETL 출력을 통합 컨텍스트에 연결

• 기존 LangGraph 파이프라인을 통해 컨텍스트 엔터티에서 NLP 테스트 생성

• NLP 및 Playwright SDK .spec.ts 초안 형식 모두에서 생성된 테스트 미리보기

• 보호된 쓰기 작업을 통해 승인된 생성 테스트 실행