AI Ops MCP

English | 简体中文

AI Ops MCP는 로컬 SSH 자격 증명 브로커이자 stdio MCP 서버입니다. AI 클라이언트가 비밀번호, 개인 키 내용 또는 개인 키 암호문을 받지 않고도 안정적인 server_id 별칭을 통해 SSH 및 SFTP 작업을 수행할 수 있게 해줍니다.

[!WARNING] AI Ops MCP는 인증 경계만 보호합니다. 원격 명령을 분류, 승인 또는 차단하지 않습니다. 모든 명령은 구성된 SSH 계정의 권한으로 실행됩니다. 전용 최소 권한 계정과 서버 측 제어를 사용하십시오.

버전 0.1.0은 소스에서만 배포됩니다. 이 프로젝트는 npm에 게시되지 않습니다.

기능

• 대화형 서버 등록 및 신뢰할 수 있는 Host key 고정

• SSH Agent, 시스템 자격 증명 저장소 비밀번호 및 개인 키 인증

• Windows Credential Manager, macOS Keychain 및 Linux Secret Service 통합

• 서버별 및 전역 동시성 제한이 있는 연결 풀링

• 원격 명령, 업로드, 다운로드 및 디렉터리 목록

• 로컬 및 원격 파일 경로 경계, 시간 제한, 출력 제한 및 파일 크기 제한

• 안정적인 공개 오류 코드가 포함된 구조화된 감사 로그

보안 모델

비밀번호와 개인 키 암호문은 숨겨진 프롬프트를 통해 요청되며 운영 체제 자격 증명 저장소에 저장됩니다. 비밀번호가 아닌 연결 메타데이터는 개인 로컬 구성 파일에 저장됩니다. 개인 키는 로컬 머신의 파일로 유지되며 연결 시에만 읽힙니다. Host key 지문은 등록 중에 확인되며 이후 변경은 거부됩니다.

MCP 인터페이스는 자격 증명을 열거하거나 내보낼 수 없습니다. 기본적으로 로컬 파일 작업은 MCP 프로세스 작업 디렉터리로 제한됩니다. 추가 로컬 및 원격 루트는 서버별로 구성할 수 있습니다. 감사 로그에는 명령과 경로가 포함될 수 있으므로 운영 데이터로 보호하십시오. 취약점 보고는 SECURITY.md를 참조하십시오.

이 모델은 손상된 로컬 사용자 계정, 악의적인 원격 출력, 손상된 원격 호스트 또는 유효한 SSH 권한으로 실행되는 파괴적인 명령으로부터 보호하지 않습니다.

요구 사항

• Node.js 22 또는 24

• Git 및 접근 가능한 SSH 서버

• 검증된 SSH Host key 지문

• 지원되는 인증 방법 하나

• Linux 비밀번호/암호문 사용자: 실행 중인 Secret Service 제공자

Windows Credential Manager는 Windows 10에서 Node.js 24로 검증되었습니다. macOS Keychain과 Linux Secret Service는 더 넓은 실기기 피드백이 필요합니다.

설치 및 빌드

git clone https://github.com/Finn-Aigc/ai-ops-mcp.git
cd ai-ops-mcp
npm ci
npm run typecheck
npm test
npm run build
npm link
ai-ops doctor

npm link는 ai-ops와 ai-ops-mcp를 로컬에 노출합니다. CLI 개발 중에는 npm run dev -- --help를 실행하고, 빌드 후에는 npm start -- --help를 실행하십시오.

인증

SSH Agent

시스템 Agent에 키를 로드한 다음 ai-ops add --auth agent를 실행하거나 유효한 OpenSSH 메타데이터를 가져옵니다:

ai-ops import-ssh my-host-alias

시스템 자격 증명 저장소 비밀번호

ai-ops add --id dev-box --host ssh.example.com --user deploy --auth password

비밀번호는 대화형으로 요청되며 명령줄 값으로 전달할 수 없습니다.

개인 키 파일

ai-ops add --id dev-key --host ssh.example.com --user deploy \
  --auth private-key --key <path-to-private-key>

키는 제공된 경로에 유지됩니다. 암호화된 경우 암호문이 대화형으로 요청되고 시스템 자격 증명 저장소에 저장됩니다.

CLI 참조

모든 옵션은 ai-ops <command> --help를 사용하십시오. 명령 인수를 통해 비밀번호나 암호문 입력을 자동화하지 마십시오.

MCP 클라이언트 구성

npm link 후 다음으로 모든 stdio MCP 클라이언트를 구성합니다:

{
  "mcpServers": {
    "ai-ops": {
      "command": "ai-ops-mcp"
    }
  }
}

링크 없이 개발하려면 먼저 빌드하고 유일한 인수로 node와 "<absolute-path-to-repository>/dist/mcp-entry.js"를 사용하십시오.

MCP 도구

기본값은 명령당 30초, 결합된 명령 출력 10MiB, 파일당 100MiB, 서버당 4개의 동시 작업, 전역 16개입니다. 서버 설정으로 이러한 제한을 줄이거나 조정할 수 있습니다.

문제 해결

• 먼저 ai-ops doctor를 실행하여 키링, Agent, 구성 및 서버 진단을 수행하십시오.

• HOST_KEY_MISMATCH: 새 지문을 대역 외로 검증한 다음 ai-ops trust-host <id>를 실행하십시오.

• AGENT_UNAVAILABLE: SSH Agent를 시작하고 ssh-add로 키를 로드하십시오.

• CREDENTIAL_STORE_UNAVAILABLE: 플랫폼 자격 증명 서비스를 잠금 해제하거나 시작하십시오.

• LOCAL_PATH_NOT_ALLOWED 또는 REMOTE_PATH_NOT_ALLOWED: ai-ops edit <id> --allowed-local ... --allowed-remote ...로 루트를 업데이트하십시오.

• MCP 프로세스가 즉시 종료됨: npm run build를 실행하고 구성된 실행 파일 또는 절대 진입 경로를 확인하십시오.

로컬 라이브 E2E 테스트

라이브 테스트는 의도적으로 GitHub Actions에서 제외됩니다. 격리된 홈과 /tmp 아래에 임시 파일을 만들고 자체 ~/.ssh/authorized_keys를 업데이트할 수 있는 전용 저권한 서버 계정을 사용하십시오:

$env:AI_OPS_HOME = "<isolated-ai-ops-home>"
$env:AI_OPS_E2E_SERVER_ID = "test-server"
npm run build
npm run test:e2e:core
npm run test:e2e:mcp
npm run test:e2e:auth
npm run test:e2e:agent
npm run test:e2e:cleanup

각 테스트는 고유한 리소스를 사용하고 finally 블록에서 정리합니다. 프로덕션 자격 증명이나 구성을 절대 사용하지 마십시오. CONTRIBUTING.md, docs/PRD.md 및 docs/IMPLEMENTATION_PLAN.md를 참조하십시오.

라이선스

MIT © 2026 AI Ops MCP 기여자.