Archery MCP 2FA

@seaxlab/archery-mcp에 Archery TOTP 2FA(2단계 인증) 지원을 추가하는 영구 패치입니다.

이 프로젝트는 데이터베이스에 직접 연결하지 않으며 Archery의 권한, 마스킹, 속도 제한 또는 감사 메커니즘을 우회하지 않습니다. 로그인 흐름만 확장하여 TOTP가 활성화된 Archery 계정도 MCP 서비스를 통해 인증할 수 있도록 합니다.

현재 패치는 @seaxlab/archery-mcp@3.0.2에만 적용됩니다. 업스트림 의존성을 업그레이드하기 전에 패치가 여전히 호환되는지 확인하고 패치 파일을 다시 생성하십시오.

기능

• 시작 시 구성된 Archery 계정과 비밀번호로 자동 로그인합니다.

• TOTP 인증이 감지되면 대화형 터미널에서 6자리 인증 코드를 입력하라는 메시지를 표시합니다.

• 대화형 터미널이 없으면 MCP 도구를 통해 인증합니다.

• 인증 성공 후 동일한 Archery 세션을 재사용합니다.

• TOTP 인증 코드는 현재 요청에만 사용되며 구성 파일이나 메타데이터 캐시에 기록되지 않습니다.

• patch-package를 사용하여 의존성 설치 후 패치를 자동으로 적용합니다.

Related MCP server: auth-vault

환경 요구 사항

• Node.js 24 이상.

• npm 10 이상.

• 접근 가능한 Archery 서비스; 업스트림 패키지는 Archery v1.8.5를 지원합니다.

• TOTP가 활성화된 Archery 계정 또는 일반 계정 비밀번호.

빠른 시작

1. 프로젝트 가져오기 및 의존성 설치

git clone <repository-url>
cd archery-mcp-2fa
npm ci

npm ci가 완료되면 postinstall 스크립트가 patches/의 2FA 패치를 자동으로 적용합니다.

2. 구성 파일 준비

업스트림 패키지에서 제공하는 예제를 기반으로 구성을 만들 수 있습니다:

mkdir -p ~/.config/archery-mcp
cp node_modules/@seaxlab/archery-mcp/config.example.toml \
  ~/.config/archery-mcp/pro.toml
chmod 600 ~/.config/archery-mcp/pro.toml

~/.config/archery-mcp/pro.toml을 편집하여 최소한 다음을 입력합니다:

env = "pro"

[server]
host = "127.0.0.1"
port = 3000

[archery]
base_url = "https://archery.example.com"
username = "mcp_service"
password = "replace-with-a-strong-password"

[query]
default_limit = 100
max_limit = 500

[cache]
enabled = true
ttl_seconds = 604800
exclude_instance_names = []
exclude_instance_ids = []

구성 파일에는 일반 텍스트 비밀번호가 포함되어 있으므로 항상 파일 권한을 제한하고 실제 구성을 버전 관리에 커밋하지 마십시오.

전체 구성 옵션은 업스트림 프로젝트 설치 후 node_modules/@seaxlab/archery-mcp/README.md 및 config.example.toml을 참조하십시오.

3. 서비스 시작

명령줄 인수로 구성 파일 지정:

npm start -- --config ~/.config/archery-mcp/pro.toml

환경 변수를 사용할 수도 있습니다:

ARCHERY_MCP_CONFIG=~/.config/archery-mcp/pro.toml npm start

기본 MCP 주소:

http://127.0.0.1:3000/mcp

헬스 체크 주소:

http://127.0.0.1:3000/health

TOTP 인증 흐름

대화형 터미널

계정에 TOTP가 활성화된 경우 시작 시 터미널에 다음 메시지가 표시됩니다:

archery-mcp [env=pro] Archery requires TOTP authentication
请输入当前 6 位 TOTP 验证码:

인증 앱에 현재 표시된 인증 코드를 입력합니다. 인증에 성공하면 서비스가 포트 수신을 시작합니다:

archery-mcp [env=pro] TOTP authentication succeeded
archery-mcp [env=pro] listening on http://127.0.0.1:3000/mcp

인증 코드가 유효하지 않으면 바로 다시 시도할 수 있습니다. Archery 세션이 만료되거나 프로세스가 다시 시작되면 다시 인증해야 합니다.

비대화형 터미널

서비스가 컨테이너, 백그라운드 작업 또는 프로세스 관리자에 의해 시작되고 대화형 터미널이 없는 경우에도 서비스는 계속 시작되며 다음 MCP 도구가 등록됩니다:

인증 단계:

1. archery_auth_status를 호출합니다.

2. two_factor_required: true가 반환되면 사용자에게 인증 앱에 현재 표시된 6자리 인증 코드를 요청합니다.

3. archery_submit_otp를 { "otp": "123456" } 매개변수로 호출합니다.

4. authenticated: true가 반환되는지 확인한 후 쿼리 또는 SQL 감사 도구를 호출합니다.

위의 두 인증 도구를 제외한 나머지 MCP 도구는 업스트림 @seaxlab/archery-mcp와 동일합니다.

MCP 클라이언트 구성

Streamable HTTP를 지원하는 MCP 클라이언트로 연결:

{
  "mcpServers": {
    "archery": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

Codex는 ~/.codex/config.toml에서 구성할 수 있습니다:

[mcp_servers.archery]
url = "http://127.0.0.1:3000/mcp"

Claude Code는 명령줄에서 추가할 수 있습니다:

claude mcp add --transport http archery http://127.0.0.1:3000/mcp

프로젝트 구조

.
├── patches/
│   └── @seaxlab+archery-mcp+3.0.2.patch  # TOTP 支持补丁
├── package.json                           # 依赖和启动脚本
├── package-lock.json                      # 锁定依赖版本
└── README.md

일반 명령

npx -y @seaxlab/archery-mcp@3.0.2로 직접 시작하지 마십시오. 이 경우 이 프로젝트의 2FA 패치가 포함되지 않은 공식 npm 패키지가 실행됩니다.

보안 참고 사항

• 기본적으로 127.0.0.1만 수신합니다. MCP HTTP 엔드포인트에는 인증이 없으므로 공개 인터넷에 직접 노출해서는 안 됩니다.

• 원격 액세스가 필요한 경우 역방향 프록시 계층에서 TLS, 액세스 인증 및 네트워크 액세스 제어를 추가하십시오.

• Archery 비밀번호는 TOML 구성에 저장되므로 chmod 600을 설정하고 전용 최소 권한 서비스 계정을 사용하십시오.

• 실제 비밀번호, TOTP 인증 코드, 세션 쿠키, 내부 Archery 주소 또는 프로덕션 구성을 저장소, 이슈 또는 로그에 커밋하지 마십시오.

• TOTP는 MCP 요청을 통해 전송됩니다. 원격 MCP 클라이언트를 사용하는 경우 통신 링크가 신뢰할 수 있고 암호화되었는지 확인하십시오.

호환성 및 유지 관리

패치는 업스트림 패키지의 빌드 산출물에 직접 적용되므로 업스트림 버전이 변경되면 패치를 적용하지 못하거나 동작이 호환되지 않을 수 있습니다. 업그레이드 시 다음을 권장합니다:

1. package.json의 @seaxlab/archery-mcp 버전을 업데이트합니다.

2. npm install을 실행하고 패치 충돌을 확인합니다.

3. node_modules/@seaxlab/archery-mcp에서 2FA 수정 사항을 다시 구현하고 검증합니다.

4. npx patch-package @seaxlab/archery-mcp를 실행하여 새 패치를 생성합니다.

5. 대화형 터미널과 비대화형 터미널에서 각각 인증 흐름을 검증합니다.

기여

이슈 또는 풀 리퀘스트를 환영합니다. 코드를 제출하기 전에 실제 계정, 비밀번호, 인증 코드, 쿠키, 내부 도메인 이름 또는 기타 민감한 정보가 포함되어 있지 않은지 확인하십시오.

감사의 말 및 고지

이 프로젝트는 @seaxlab/archery-mcp의 공개 릴리스 패키지를 기반으로 패치를 만든 것으로, Archery 또는 업스트림 패키지 유지 관리자의 공식 프로젝트가 아닙니다. Archery 및 관련 이름의 권리는 각 소유자에게 있습니다.