⚡ Omni-Tester: 제로 할루시네이션 MCP 테스팅 에이전트

Omni-Tester는 AI 에이전트(Claude, Cursor, Windsurf 등)에 증명 기반의 할루시네이션 방지 검증 엔진을 제공하는 Model Context Protocol (MCP) 서버입니다. 더 이상 LLM이 엔드포인트가 동작하는지 "추측"하게 두지 마세요 — 프로그램적 증명을 요구하세요.

이 에이전트는 백엔드 서버와 직접 통신하며 HTTP 상태 코드, 응답 헤더, JSON 페이로드를 검사하여 결정적이고 기계 검증된 결과를 생성합니다.

✅ 현재 구현됨 (결정적 증명)

이 계층들은 현재 실행되며 기계 검증된 증거를 반환합니다 — LLM 판단이 개입되지 않습니다:

• 계층 1 — 프로토콜 및 상태 검증: 요청을 전송하고 반환된 HTTP 상태 코드가 명시적 기대값(예: 200 OK, 201 Created)과 일치하는지 확인하며, 불일치와 5xx 크래시를 표시합니다.

• 계층 2 — 스키마 및 페이로드 무결성: Content-Type 헤더가 application/json인지 확인하고, 본문을 JSON으로 파싱하여 페이로드 스냅샷을 반환합니다. 선택적 expected_schema를 전달하면 각 필드의 존재 여부와 타입을 결정적으로 강제합니다 — 최상위("id"), 점 표기 경로("address.geo.lat")를 통한 중첩, 리스트 인덱스("items.0.id"). 지원 타입: int, float/number, str/string, bool, list/array, dict/object, null. (JSON true/false는 int로 허용되지 않습니다.)

두 계층 모두 항상 실행됩니다 — 상태 코드 실패가 페이로드 진단을 억제하지 않으므로, 실패한 4xx/5xx 응답의 오류 본문도 계속 확인할 수 있습니다.

스키마 강제 적용 예시:

run_api_4_layer_validation(
    endpoint_url="https://jsonplaceholder.typicode.com/users/1",
    expected_status=200,
    method="GET",
    expected_schema={"id": "int", "email": "str", "address.geo.lat": "str"},
)

또한 헤드리스 브라우저에서 페이지를 로드하여 폼 개수, alt 태그가 없는 이미지, 콘솔 오류를 보고하는 실험적 run_ui_dom_checklist 도구(Playwright)도 있습니다.

Related MCP server: agentseed

🗺️ 로드맵 (아직 구현되지 않음)

다음은 계획되었지만 현재 코드에는 없습니다. 사용 가능한 기능이 아니라 투명성을 위해 여기에 문서화합니다:

• 계층 3 — 기능적 비즈니스 로직: LLM을 사용하여 반환된 데이터가 시나리오에 논리적으로 부합하는지 확인합니다. (참고: 이 계층은 LLM 기반 판단이며 결정적 증명이 아닙니다.)

• 계층 4 — 보안 및 경계 스트레스 테스트: 악성 페이로드(SQL 인젝션 문자열, 잘못된 형식의 헤더, 만료된 인증 토큰)를 주입하여 API가 안전하게 실패하는지 검증합니다.

• 더 깊은 계층 2 (중첩 타입 검사): ✅ 완료 — 최상위, 점 표기 중첩 경로, 리스트 인덱스가 모두 강제됩니다. 남은 아이디어: 전체 배열에 대한 요소별 검증(예: "모든 항목에 int id가 있어야 함") 및 enum/형식 제약.

• 독립 API 에이전트: 시나리오를 계획하고 Python 테스트 코드를 생성하며 스키마가 변경될 때 스스로 복구하는 자율 테스트 엔지니어입니다.

• API 탐색 에이전트: 액션을 동적으로 퍼징하고 연결합니다(예: GET에서 토큰을 가져와 PUT에 주입).

• 감사 추적: specs/api_plan.md, tests/api/, data/reports/api_report_*.html로 구조화된 출력.

📦 설치

uv 사용(권장):

uv venv
source .venv/bin/activate        # On Windows: .venv\Scripts\activate
uv sync                          # Install dependencies from pyproject.toml

UI 체크리스트 도구를 위해 Playwright 브라우저를 한 번 설치합니다:

uv run playwright install chromium

서버가 시작되는지 확인합니다(stdio를 통해 MCP를 사용하며 클라이언트를 기다립니다):

uv run omni-tester

🔌 MCP 클라이언트 연결

서버는 uv run omni-tester로 시작됩니다. 아래에서 원하는 클라이언트에 추가하세요. uv가 클라이언트의 PATH에 없으면 command 필드에 uv 바이너리의 절대 경로를 사용하세요.

Claude Code (CLI)

한 줄 명령으로 추가합니다:

claude mcp add --transport stdio omni-tester -- uv run omni-tester

또는 프로젝트 범위의 .mcp.json에 수동으로 추가합니다:

{
  "mcpServers": {
    "omni-tester": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "omni-tester"],
      "env": {}
    }
  }
}

Claude Desktop

claude_desktop_config.json 편집(설정 → 개발자 → 구성 편집):

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "omni-tester": {
      "command": "uv",
      "args": ["run", "omni-tester"],
      "env": {}
    }
  }
}

저장 후 Claude Desktop을 다시 시작합니다.

Cursor

.cursor/mcp.json(프로젝트 범위) 또는 ~/.cursor/mcp.json(전역) 편집:

{
  "mcpServers": {
    "omni-tester": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "omni-tester"],
      "env": {}
    }
  }
}

Windsurf (Cascade)

mcp_config.json 편집(설정 → MCP 서버 관리 → 원시 구성 보기):

• macOS/Linux: ~/.codeium/windsurf/mcp_config.json

• Windows: %APPDATA%\Codeium\Windsurf\mcp_config.json

{
  "mcpServers": {
    "omni-tester": {
      "command": "uv",
      "args": ["run", "omni-tester"],
      "env": {}
    }
  }
}

저장 후 Windsurf를 다시 시작합니다.

🛠️ 도구

명명 참고: 이 도구는 향후 호환성을 위해 run_api_4_layer_validation이라는 이름을 사용하지만, 현재는 계층 1–2만 구현되어 있습니다(로드맵 참조).

🧪 예시

실제 엔드포인트를 검증하며 200을 기대합니다:

run_api_4_layer_validation(
    endpoint_url="https://jsonplaceholder.typicode.com/users/1",
    expected_status=200,
    method="GET",
)

실행 결과:

Backend 4-Layer Validation Complete:
✅ Layer 1 PASS: Expected 200, received 200.
✅ Layer 2 PASS: Valid JSON payload returned.
Payload Snapshot: {'id': 1, 'name': 'Leanne Graham', ...}