@vitronai/alethia

검증 가능한 안전성을 갖춘 에이전트 네이티브 E2E. 에이전트가 자연어로 실제 브라우저를 조작하고, 파괴적 작업은 작동을 입증할 수 있는 안전 게이트로 차단됩니다 — 서명된 감사 추적 기록과 클라우드 없이.

설치

Claude Code — 가장 빠른 방법(플러그인):

/plugin marketplace add vitron-ai/alethia-mcp
/plugin install alethia@vitronai

이 방법은 MCP 서버와 스킬을 한 번에 설정합니다 — 수동 npm install이나 MCP 구성 편집이 필요 없습니다. 재시작하거나 /reload-plugins를 실행하면 활성화됩니다.

Claude Code — 스킬만(플러그인 매니저 없음):

mkdir -p ~/.claude/skills/alethia && \
  curl -fsSL https://raw.githubusercontent.com/vitron-ai/alethia-mcp/main/skills/alethia/SKILL.md \
    -o ~/.claude/skills/alethia/SKILL.md

Claude Code를 재시작하세요. 다음에 페이지 테스트를 요청하면 Alethia가 아직 구성되지 않았음을 감지하고 브리지 설치 과정을 직접 안내합니다.

그 외 모든 클라이언트(Claude Desktop, Cursor, Cline, Continue):

npm install -g @vitronai/alethia

그런 다음 클라이언트의 MCP 구성에 다음을 추가하세요:

{
  "mcpServers": {
    "alethia": {
      "command": "alethia-mcp"
    }
  }
}

저장 후 클라이언트를 재시작하세요. 에이전트가 Alethia 도구를 처음 호출할 때 런타임이 자동으로 다운로드됩니다(서명됨, 약 100MB). 기본적으로 콕핏 창이 열려 진행 상황을 지켜볼 수 있습니다 — 숨기려면 ALETHIA_HEADLESS=1을 설정하세요. CI 환경에서는 자동으로 숨겨집니다.

브리지 업그레이드: npm install -g @vitronai/alethia@latest. 0.6.0부터 새 런타임 버전을 위해 새 브리지가 필요하지 않습니다 — 시작할 때마다 GitHub Releases를 조회합니다.

수동 업그레이드 없이 항상 최신 버전 실행:

{
  "mcpServers": {
    "alethia": {
      "command": "npx",
      "args": ["-y", "@vitronai/alethia@latest"]
    }
  }
}

@latest 접미사가 중요합니다 — 없으면 npx -y가 오래된 캐시 버전을 제공할 수 있습니다. 트레이드오프: 콜드 캐시에서 10~30초가 추가되고, 실행할 때마다 npm이 현재 제공하는 버전을 가져옵니다(컴플라이언스가 중요한 작업에서는 명시적으로 업그레이드할 때만 변경되므로 전역 설치가 더 안전한 기본값입니다).

특정 런타임 버전 고정(재현 가능한 CI, 이분 탐색):

"env": { "ALETHIA_RUNTIME_VERSION": "0.4.0" }

Claude Code 스킬 설치(선택 사항, 각 도구를 언제 사용할지 Claude에게 알려줍니다):

alethia-mcp --install-skill

Related MCP server: titmas-agent-action-gate

무엇을 요청할까요?

이 도구들을 직접 호출할 필요는 없습니다 — 그냥 에이전트에게 자연어로 요청하면 적절한 도구를 선택합니다.

비밀번호, 토큰 또는 신용카드 필드에 입력하는 것은 실제 로그인 또는 결제 테스트로 요청을 구성한 경우에만 허용됩니다 — 에이전트가 이를 직접 활성화하므로 플래그를 지정할 필요가 없습니다.

바로 붙여넣을 수 있는 더 많은 예시: 에이전트 쿡북에 전체 워크스루가 있습니다 — 알 수 없는 페이지에서 테스트 부트스트래핑, 전체 컴플라이언스 패스, 병렬 다중 페이지 검사, 라이브 파트너 데모. 모두 그대로 붙여넣으면 되는 프롬프트입니다.

프로젝트에 Alethia 추가

프로젝트별 설치가 필요 없습니다 — MCP 서버가 구성되면 어떤 프로젝트의 어떤 에이전트도 사용할 수 있습니다.

1. .alethia 파일을 저장소가 테스트 코드로 취급하는 아무 곳에나 넣으세요 — tests/e2e/처럼 적절한 위치에.

   # tests/e2e/login.alethia
   name login flow
   navigate to http://127.0.0.1:5173
   assert "Sign in" is visible
   click Sign in
   type dev@company.com into the email field
   assert dashboard is visible

2. 에이전트에게 실행을 요청하세요: "tests/e2e/login.alethia를 http://127.0.0.1:5173 대상으로 실행해 줘."

3. CI에서 에이전트나 MCP 호스트 없이 실행하세요:

   alethia run tests/e2e/login.alethia

   통과 시 0, 실패 시 1로 종료됩니다. 바로 사용 가능한 워크플로: examples/github-actions.yml.

작동하는 참조 구현(데모 앱 + 스펙 + CI + 벤치마크)은 vitron-ai/alethia-anvil에 있습니다.

Cypress나 Playwright 대신 왜 Alethia인가?

테스트 도구일 뿐만도 아닙니다 — 에이전트가 현재 빌드 중인 페이지에서 getComputedStyle()이나 offsetWidth를 확인하도록 요청하면, 새로고침 후 검사하는 사이클 대신 DOM에서 직접 얻은 캐시되지 않은 실시간 답변을 받을 수 있습니다.

더 알아보기: 아키텍처 · 안전 게이트 · FAQ · 에이전트 주도 테스트를 위한 UI 패턴

CLI 플래그

alethia-mcp                  Run as a stdio MCP server (default)
alethia-mcp run <path>       Run an NLP test file from the shell (CI mode)
alethia-mcp run --nlp "..."  Run inline NLP from the shell
alethia-mcp run -            Read NLP from stdin
alethia-mcp --version        Print the version and exit
alethia-mcp --health-check   Probe the Alethia runtime and exit 0/1
alethia-mcp --debug          Run with debug logging on stderr

더 짧은 alethia 별칭(동일한 바이너리)도 설치되므로, run 하위 명령을 alethia run <path>로 호출할 수 있습니다.

환경 변수

브리지가 스스로 최신 상태를 유지하는 방법

• 런타임은 첫 사용 시 서명된 GitHub 릴리스(Ed25519 검증)에서 자동 설치됩니다. 브리지는 첫 시작 시 GitHub에 현재 버전을 조회합니다(1시간 캐시) — 브리지 소스에는 버전 고정이 없으므로, 전역 설치된 브리지는 새 런타임이 출시될 때마다 계속 최신 버전을 가져옵니다.

• 브리지도 자체 업데이트를 수행합니다(0.8.0부터): 시작 시 npm을 확인하고, tarball의 SHA-512를 검증하며, ~/.alethia/bridge/<version>/에 설치합니다. 명시적 조치 없이는 메이저 버전을 넘지 않습니다. 새 버전은 실제 MCP 핸드셰이크를 완료한 후에만 신뢰되며, 그 전에 충돌하는 버전은 3회 시도 후 격리됩니다.

• 번들된 Claude Code 스킬도 같은 방식으로 자동 갱신됩니다 — 실행할 때마다 ~/.claude/skills/alethia/SKILL.md와 비교하고 오래된 경우 덮어씁니다.

문제 해결

"Alethia desktop runtime is not running" — alethia-mcp --health-check를 실행하세요(없으면 자동 설치를 트리거합니다). 그래도 실패하면 GitHub까지의 네트워크 연결 가능 여부를 확인하세요.

"WRITE_HIGH" / "EA1 POLICY BLOCK" 감사 로그 항목 — 파괴적 작업이 차단되었습니다. 이는 올바른 fail-closed 동작이며, 수정해야 할 오류가 아닙니다. 이를 완화하려면 사람의 구성이 필요하며, 에이전트는 호출 내부에서 이를 수행할 수 없습니다.

"SENSITIVE_INPUT_DENIED" — 비밀번호/토큰/신용카드 필드가 감지되었습니다. 합법적인 인증/결제 테스트의 경우에만 allowSensitiveInput: true로 재정의하십시오.

MCP 클라이언트가 도구를 볼 수 없음 — alethia-mcp --health-check를 실행하고, 구성 형태를 확인하고, 클라이언트를 다시 시작하고, ALETHIA_DEBUG=1을 설정하여 브리지 트래픽을 기록하십시오.

"Server transport closed unexpectedly" / 브리지가 조용히 종료됨 — 일반적으로 오래된 캐시된 브리지입니다. npx -y @vitronai/alethia를 @latest 없이 사용하는 경우, @latest를 추가하거나 rm -rf ~/.npm/_npx를 실행하십시오. 전역 설치를 사용하는 경우 npm install -g @vitronai/alethia@latest를 실행하십시오. 그런 다음 클라이언트를 완전히 종료하고 다시 시작하십시오(macOS에서는 창을 닫는 것만으로는 부족하고 Cmd-Q).

"GitHub에서 새 릴리스를 확인했지만 런타임이 업그레이드되지 않음" — "현재 버전" 확인은 1시간 동안 캐시됩니다. rm ~/.alethia/.latest-release ~/.alethia/.bridge-registry-cache로 캐시를 지운 후 클라이언트를 다시 시작하십시오.

보안 태세

런타임은 아키텍처상 로컬 전용입니다. 서명된 바이너리는 file://, localhost, 127.0.0.1, .local 및 RFC1918 사설 범위 밖으로는 탐색을 거부합니다. 이는 컴파일 타임 상수이며, 이를 변경하는 플래그, 환경 변수 또는 UI 토글이 없습니다. 전체 위협 모델 및 공개 프로세스: SECURITY.md. 악용 신고: team@vitron.ai.

개인정보 보호

아키텍처상 로컬 전용 — 사용자 머신 외부로 수집, 전송, 저장되는 것이 없습니다. 페이지 콘텐츠, 스크린샷, 테스트 지침은 로컬에서 처리되며 어디에도 전송되지 않습니다. 증거 팩은 명시적 요청 시에만 파일 시스템에 기록됩니다. 텔레메트리, 분석, 크래시 리포트가 전혀 없습니다. 문의: team@vitron.ai.

라이선스 및 특허 고지

이 브리지는 MIT 라이선스입니다 — LICENSE 참조. Alethia 런타임 자체는 특허 출원 중입니다(미국 출원 번호 19/571,437). 이 브리지의 MIT 라이선스는 런타임에 대한 특허 라이선스를 부여하지 않습니다. 상업적 런타임 사용에는 별도의 라이선스가 필요할 수 있습니다. 라이선스 문의: team@vitron.ai.