AWR은 작업 레저를 MCP(Model Context Protocol)를 통해 노출합니다. MCP는 코딩 어시스턴트나 데스크톱 AI 클라이언트 같은 에이전트 호스트가 도구를 발견하고 호출할 수 있게 하는 표준 프로토콜입니다. MCP 서비스는 에이전트가 CLI를 직접 셸로 호출하지 않고도 프로젝트 상태를 읽고, 컨텍스트를 컴파일하고, 증적을 기록하고, 작업을 진행하는 방법입니다. 실행 방법은 두 가지입니다:
- stdio — 클라이언트가 직접 생성하는 로컬 프로세스로, 한 번에 하나의 프로젝트. 클래식한 설정이며 계속 사용할 수 있습니다.
- 공유 HTTP — 여러 프로젝트와 여러 독립 클라이언트를 서빙하는 단일 Streamable HTTP 엔드포인트. npm과 PyPI 패키지 모두 이 기능을 포함합니다.
이 문서는 공유 HTTP 서비스에 초점을 맞춥니다 — 두 명 이상의 사람이나 에이전트가 같은 프로젝트를 필요로 할 때 실행하는 것입니다. 연결 후 에이전트가 이 도구들로 무엇을 하는지는 에이전트를, 같은 연산의 사람용 대응은 AWR CLI를 참조하세요.
공유 서비스의 작동 방식
각 프로젝트를 서버에서 awr init으로 초기화한 다음, 다음 명령이 반환하는 project_id와 함께 정규 절대 루트를 등록합니다:
awr --json status
AWR은 시작 시와 모든 요청에서 이 식별자를 검증합니다. 소스 파일과 각 프로젝트의 .awr 데이터베이스는 분리된 상태를 유지합니다 — 서비스는 리포지터리를 클론하거나, 클라이언트 파일시스템을 마운트하거나, 프로젝트 레저를 머지하지 않습니다. 클라이언트에게 필요한 것은 로컬 AWR 실행 파일이 아니라 서비스에 대한 네트워크 접근이며, 프로젝트 파일은 서버에서 읽을 수 있어야 합니다: 클라이언트 노트북의 경로가 원격으로 읽을 수 있게 되지는 않습니다. 공유된 "현재 프로젝트"는 없습니다 — 모든 프로젝트 도구는 명시적 project 인자를 받으며, 임의의 서버 경로를 여는 도구는 없습니다.
서비스 구성
공개 리포지터리 밖에 운영자 소유의 TOML 파일을 만듭니다:
version = 1
allowed_hosts = ["awr.internal.example"]
[[projects]]
key = "billing"
root = "/srv/projects/billing"
project_id = "<actual project ID>"
[[projects]]
key = "support"
root = "/srv/projects/support"
project_id = "<actual project ID>"
[[clients]]
id = "engineering"
token_env = "AWR_ENGINEERING_TOKEN"
write = ["billing", "support"]
[[clients]]
id = "reviewer"
token_env = "AWR_REVIEWER_TOKEN"
read = ["billing"]
각 클라이언트 항목은 bearer 자격 증명을 담은 환경 변수를 지명합니다. 최소 32자의 서로 다른 무작위 생성 자격 증명을 제공하세요. write 권한은 읽기 접근을 포함하고, read 권한은 프로젝트를 변경할 수 없습니다. 자격 증명 로테이션 동안 클라이언트 ID를 안정적으로 유지하세요 — 대화와 요청 바인딩이 클라이언트 ID에 연결되며, 변경하면 별개의 범위가 생성됩니다. 구성 변경은 서비스 재시작 후에만 적용됩니다.
서비스 실행
awr-mcp --registry /etc/awr/service.toml --listen 127.0.0.1:8080
모든 HTTP 요청은 인증됩니다. 내장 메커니즘은 정적 bearer 인증입니다 — OAuth 인가 서버나 엔터프라이즈 아이덴티티 제공자가 아닙니다. 원격 접근의 경우 인증된 배포 경계에서 HTTPS를 종료하고 백엔드에 대한 직접 접근을 제한하세요. 추가 접근 제어:
- Origin은
allowed_origins에 명시적으로 나열되지 않으면 거부됩니다; 네이티브 클라이언트는 보통Origin헤더를 생략합니다. - SDK는
allowed_hosts를 검사하며, 구성되지 않은 경우 루프백 호스트가 기본값입니다. - 서비스는 Origin을 검증하지만 브라우저 CORS 프리플라이트를 구현하지 않으므로, 브라우저 프런트엔드에는 적절한 게이트웨이가 필요합니다.
Unix에서 SIGTERM과 Ctrl-C는 새 요청 수락을 정상적으로 중단하고 활성 HTTP 작업을 드레인합니다. 클라이언트 연결 해제나 서비스 재시작은 AWR 작업 세션을 절대 종료하지 않습니다 — 프로토콜 연결과 영구 세션은 별개의 신원입니다. AWR은 시스템 데몬을 설치하지 않습니다 — 시작과 재시작에는 배포 환경의 프로세스 슈퍼바이저를 사용하세요. 로컬 단일 클라이언트 사용에는 stdio 명령이 그대로 있습니다:
awr-mcp --project /absolute/project
클라이언트 연결
각 MCP 클라이언트를 /mcp 경로를 사용하는 동일한 서비스 URL의 Streamable HTTP로 구성하고, 해당 클라이언트의 자격 증명 메커니즘을 통해 전달되는 Authorization: Bearer … 헤더에 자체 bearer 자격 증명을 넣습니다. 연결되면 awr_projects_list를 호출하여 자격 증명이 인가된 프로젝트 키를 발견합니다. 모든 프로젝트 도구는 project를 요구합니다:
{"project": "billing", "work": "INVOICE-001"}
도구
공유 HTTP 서비스는 총 21개의 도구를 노출합니다(stdio는 프로젝트 나열 도구를 생략한 20개). 세 그룹으로 나뉩니다.
작업 및 컨텍스트 도구
일상적인 CLI 액션을 반영합니다:
| 도구 | 기능 |
|---|---|
awr_project_status | 현재 이어할 작업, 클레임 가능한 작업, 대기, 블로커, 이력 요약 |
awr_work_ready | 진단 및 클레임 힌트가 포함된 준비된 항목 |
awr_work_get | 작업 항목의 태스크, 인수 기준, 의존성, 결정, 증적 |
awr_context_compile | 작업 항목 또는 브랜치의 컨텍스트 패킷 컴파일 |
awr_work_transition | 작업 진행, 차단, 차단 해제, 취소, 재개, 완료 |
awr_event_append | 레저에 이벤트 추가 |
awr_evidence_record | 작업 및 인수 항목에 바인딩된 증적 기록 |
awr_search | 프로젝트 레저 전체 검색 |
세션 및 계속 도구
세션은 대화를 작업 단위에 바인딩합니다. 호스트에서 안정적인 conversation 식별자를 제공하세요 — HTTP 연결 식별자가 아닙니다. 다른 프로젝트나 클라이언트 아래의 같은 대화 문자열은 별개의 바인딩입니다.
| 도구 | 기능 |
|---|---|
awr_session_start | 작업에 바인딩된 세션 시작, 선택적으로 작업 클레임 |
awr_session_get | 바인딩, 세션, 클레임, 체크포인트, 중단된 저장 검사 |
awr_session_list | 이 클라이언트의 세션 이력 페이지 탐색 |
awr_session_checkpoint | 소비된 컨텍스트 해시, 다이제스트, 다음 액션, 열린 루프 저장 |
awr_session_claim | 세션의 클레임 획득 또는 해제 |
awr_session_end | 세션을 명시적으로 종료하거나 중단하고 클레임 해제 |
awr_session_resume | 상속된 체크포인트와 클레임으로 후속 세션 생성 |
awr_session_wait | 체크포인트를 저장하고 사용자를 위한 지속적인 질문 기록 |
awr_session_reply | 기록된 대기에 사용자의 답변 전달 |
awr_operation_get | 요청 ID로 쓰기의 기록된 결과 검사 |
awr_operation_recover | 증명이 있을 때 중단된 쓰기의 커밋된 결과 기록 |
awr_source_reindex | 권위 있는 소스로부터 프로젝트의 프로젝션 갱신 |
보류 중인 대기는 호스트가 답변을 기록할 때까지 작업 전이와 재개를 차단합니다. 답변은 그 차단을 해제하지만 작업 상태를 변경하거나 호스트의 다음 턴을 예약하지는 않습니다 — 호스트가 세션을 검사하고, 새 컨텍스트를 컴파일하고, 계속할지 후속 세션을 만들지 결정합니다.
쓰기, 리비전, 불확실한 결과
모든 공유 HTTP 쓰기는 두 가지를 요구합니다:
- 클라이언트가 생성한 안정적인
request_id(최대 256바이트), - 마지막으로 관찰한
expected_revision.
{
"project": "billing",
"request_id": "host-turn-42-start",
"expected_revision": 120,
"work": "INVOICE-001",
"conversation": "invoice-review",
"agent": "billing-assistant",
"provider": "example-provider",
"model": "example-model",
"claim": true
}
정확히 같은 요청 ID와 인자를 반복하면 액션을 다시 실행하지 않고 기록된 결과를 반환하므로, 타임아웃 후 재시도는 안전합니다. 변경된 인자는 새 ID가 필요합니다. 반환된 project_revision을 다음 쓰기를 위해 저장하고, 1을 더해 다음 리비전을 계산하지 마세요: 요청 저널과 도메인 연산 모두 리비전을 소비합니다.
타임아웃이나 연결 해제 후에는 같은 프로젝트와 요청 ID로 awr_operation_get을 호출하세요. 완료되지 않은 요청은 write_outcome: unknown을 보고합니다; 중단된 쓰기는 이미 커밋되었을 수 있으므로, 닫힌 HTTP 응답 스트림에서 실패를 추론하지 마세요. awr_operation_recover는 모호하지 않은 종료 이벤트가 요청에 바인딩된 경우에만 커밋된 결과를 기록할 수 있습니다 — 원래 도구를 다시 호출하지는 않습니다. 읽기는 동시에 실행될 수 있고, 쓰기는 프로젝트별로 직렬화되며, 서로 다른 프로젝트는 독립적인 잠금을 가집니다. 오래된 쓰기는 충돌을 반환합니다 — 재시도하기 전에 현재 상태를 읽고 재고하세요.
워크스트림 읽기(개발 중)
개발 소스는 YAML 워크스트림 레저를 사용하는 프로젝트에 대해 명시적으로 나열된 불변 워크스트림에 대한 읽기 전용 접근을 클라이언트에 부여하는 레지스트리 version = 2를 추가합니다. 이는 운영자 소유 권한입니다: 프로젝트 수준의 read/write 권한만으로는 어떤 격리된 워크스트림도 인가되지 않습니다.
[[clients.workstreams]]
project = "billing"
workstream_id = "<actual immutable workstream ID>"
authority_version = 1
인가된 클라이언트는 공유 전용 awr_workstream 도구를 사용하며, action: "capabilities"와 action: "list"로 시작하여 무엇을 읽을 수 있는지 발견합니다. 현재 한계를 알아두세요: 이 확장은 읽기만 부여합니다 — 뮤테이션, 콘텐츠 파일 읽기, Team PostgreSQL 연산은 불가 — 그리고 이를 활성화한 프로젝트는 인가된 구현이 제공될 때까지 모든 쓰기를 포함한 레거시 공유 도구를 거부합니다. 활성화와 재인덱스는 이 단계에서는 로컬 운영자 액션입니다.