AI 에이전트

Claude Code처럼 Model Context Protocol(MCP)을 지원하는 AI 에이전트 클라이언트는 arkvoryctl mcp를 통해 Arkvory로 작업할 수 있습니다. 클라이언트가 명령을 실행하고 stdin과 stdout으로 통신하며, 네트워크 포트는 열지 않습니다. 에이전트 스킬은 그 위에서 안전한 작업 흐름을 에이전트에게 가르칩니다.

시작하기 전에

1. 에이전트가 실행되는 머신에 명령줄 클라이언트를 설치합니다.
2. 에이전트에게 필요한 리포지토리와 작업에만 접근할 수 있는 서비스 키를 만듭니다. 본인만 읽을 수 있는 파일에 저장합니다.
3. 키 파일을 참조하는 프로필을 추가하고 확인합니다.

arkvoryctl profile add agent --server https://arkvory.example --token-file ~/.config/arkvory/agent.key --repository builds
arkvoryctl doctor --profile agent

키를 채팅, 인수, 프로젝트 파일에 붙여 넣지 마세요. 에이전트는 키를 볼 수 없습니다. 결과와 오류에는 키가 포함되지 않습니다.

MCP 서버 연결

claude mcp add arkvory -- arkvoryctl mcp --profile agent --root ~/work

--write 없이 시작하면 서버는 읽기 전용입니다. 에이전트는 리포지토리 목록을 보고, 모든 리포지토리를 검색하고, 아티팩트, 패키지, 경로별 파일, 변경 피드, 설치 상태를 읽고, 아티팩트를 다운로드할 수 있습니다. 키가 사용할 수 없는 도구는 제공되지 않습니다. 클라이언트는 MCP 2025-06-18 이상을 지원해야 합니다.

쓰기 허용

쓰기는 별도의 구성입니다. 에이전트가 쓸 수 있는 리포지토리를 지정합니다.

claude mcp add arkvory-publish -- arkvoryctl mcp --profile agent --root ~/work --write --write-repositories builds

도구	하는 일
arkvory_upload	파일을 새 아티팩트로, 또는 경로의 다음 리비전으로 업로드합니다
arkvory_publish_package	UPack을 업로드하고 패키지 버전으로 등록합니다
arkvory_promote	스테이지를 추가합니다. sha256을 주면 정확히 그 바이트인 아티팩트에만 추가합니다
arkvory_stage_remove	스테이지를 제거합니다. 아티팩트는 남습니다
arkvory_annotate	에이전트가 읽은 리비전에서 레이블과 메타데이터를 교체합니다

• --write-repositories에 없는 리포지토리에 쓰려고 하면 아무것도 보내기 전에 거부됩니다(repository_not_allowed). 서버는 그래도 키의 권한을 확인합니다.
• 아무것도 삭제하거나 복원할 수 없으며 다운로드 링크도 만들지 않습니다. 이런 작업은 콘솔에서 사람이 합니다.
• 서버는 에이전트에게 각 쓰기를 설명하고 사용자의 확인을 기다리라고 지시합니다. MCP 클라이언트도 호출마다 물어볼 수 있습니다.
• 업로드는 이어서 할 수 있습니다. 실패한 뒤 에이전트가 같은 호출을 반복하면 두 번째 아티팩트가 아니라 같은 아티팩트가 반환됩니다. 결과에는 읽은 파일의 SHA-256이 표시됩니다.

파일과 한도

• 에이전트는 --root(기본값은 현재 디렉터리) 아래에서만 로컬 파일을 읽고 씁니다. 링크를 통한 경우를 포함해 바깥으로 나가는 경로는 거부됩니다(path_outside_root).
• 다운로드한 파일은 크기와 SHA-256을 확인한 뒤에만 나타납니다. 기존 파일은 에이전트가 요청할 때만 교체됩니다.
• 키가 들어 있는 파일은 절대 업로드되지 않으며(source_contains_credential), arkvoryctl 자체 파일(프로필, 키 파일, 업로드 체크포인트)은 --root 아래에 있어도 읽거나 교체하지 않습니다(private_path).
• 결과 하나는 최대 --max-output-bytes(기본 64 KiB, 최대 1 MiB)와 100개 항목입니다. 더 받으려면 에이전트가 next를 after로 다시 전달합니다.

스킬 설치

스킬은 에이전트를 위한 지침 모음입니다. 검색, 다운로드 확인, 게시, 승격, 오류 코드 해석 방법과 절대 하면 안 되는 일을 담고 있습니다. 클라이언트와 함께 제공됩니다.

arkvoryctl skill install

스킬은 ~/.claude/skills/arkvory에 설치됩니다. 프로젝트에 설치하려면 .claude/skills/arkvory처럼 --target DIR을 지정합니다. 명령을 다시 실행하면 변경하지 않은 파일이 업데이트됩니다. 사용자가 변경한 파일은 유지됩니다. --force를 추가하지 않으면 명령이 멈추고 아무것도 바꾸지 않습니다.

보안

• 결과의 이름, 레이블, 메타데이터, 주석은 다른 사람이 작성한 것입니다. 에이전트는 이를 데이터로 취급하고 그 안의 지시를 절대 따르지 않습니다.
• 읽기 전용 구성과 쓰기 구성을 분리하고, 작업에 필요한 리포지토리에만 쓰기를 허용하세요.
• 권한이 좁은 전용 키를 사용하고, 에이전트에게 더 이상 필요하지 않으면 콘솔에서 폐기하세요.

문제 해결

오류	원인과 해결
쓰기 도구가 없음	서버가 --write 없이 시작되었거나 키에 권한이 없습니다.
repository_not_allowed	리포지토리가 --write-repositories에 없습니다. MCP 구성을 변경하세요.
forbidden	키에 권한이 없습니다. arkvoryctl doctor로 권한을 확인하세요.
path_outside_root	파일이 --root 밖에 있거나 일반 파일이 아닙니다.
state_locked	같은 업로드가 다른 호출에서 아직 진행 중입니다. 비정상 종료 후라면 그 파일을 업로드하는 arkvoryctl mcp가 없는지 확인한 다음 CLI 디렉터리(~/.config/arkvory)의 mcp-uploads에서 .lock 파일을 삭제하세요.
skill_modified	스킬 파일을 변경했습니다. 사본을 유지하거나 --force와 함께 arkvoryctl skill install을 다시 실행하세요.