AX HUB MCP Server 작업 안내

상세 설계서가 아니라 작업 전에 확인할 지도다. 80줄을 넘기지 않는다. 길어지면 설명을 연결 문서로 옮기고 링크만 남긴다.

1. 경계 — 하지 않는 것과, 그럼 누가 하는가

Agent Builder와 Tool Service 사이의 stateless MCP 실행 계층이다. Agent Builder가 tools/call에 명시한 단일 Tool만 검증하고 실행한다.

하지 않는 것	하는 곳
Tool 선택, 의도 분류, LLM 추론	Agent Builder
인증·인가	NetworkPolicy(호출자 제한) · Agent Builder(Tool 권한) · Tool Service(업무 권한)
업무 규칙, 사원 식별자 복호화	Tool Service

값이 아니라 규칙만 적는다. 실제 숫자는 정본에 있고 여기 옮기지 않는다.

영역	불변식
보안	요청·응답 body, credential, 사원 식별자는 암호문이라도 로그에 남기지 않는다
보안	outbound 주소는 설정에서만 온다. 요청 값도 매니페스트도 호출 대상을 바꾸지 못한다
상태	요청 경로는 in-memory snapshot만 읽는다. Redis 실패는 언제나 cache miss다
상태	조회에 성공했을 때만 목록을 교체한다. 어떤 실패도 목록을 비우지 않는다
시간	`Agent Builder 대기 > MCP 예산 > Tool timeout`, `drain < grace period`

정본은 architecture.md와 Tool Service 계약 v0.2다. Redis·부분 실패·시간 예산 처리는 방어 코드가 아니라 계약이다. 단순화 대상이 아니다.

작업 성격	볼 것
전체 구조·요청 흐름·장애 동작	docs/architecture.md
MCP/JSON-RPC, Registry, Tool 실행, trace, profile·배포 변경	`verify-mcp-server-change` skill
Agent Builder / Tool Service 공개 계약	docs/contracts/

가까운 테스트를 먼저 보고, 가장 작은 일관된 변경만 한다. Java 21, constructor injection, 가능한 immutable model.
손대는 대상의 이름을 문서에서 grep해 그 서술이 아직 참인지 확인한다. 실패는 대개 누락이 아니라 낡음이다.
docs/contracts/*/examples/의 JSON은 테스트 fixture다. 공개 응답을 바꾸면 예제와 계약 테스트를 같은 변경에서 고친다. 테스트는 fallback이 아니라 운영에서 실제로 도는 경로를 태워야 한다.
추가·수정한 production class와 method에는 역할·처리 단계·협력 객체를 설명하는 한글 Javadoc을 단다. 주변에 주석이 없어도 예외가 아니다. 상세 규칙은 skill의 references/에 있다.
public endpoint·header·config·배포 기본값을 바꾸기 전에는 운영 영향을 설명한다.

동작 변경에는 테스트를 추가·수정하고 .\gradlew.bat check 를 실행한다. 서식 검사는 CodeStyleContractTest가 소유해 항상 돌고, 들여쓰기·줄바꿈은 IDEA_FORMATTER가 있을 때만 검증된다(README).
책임·흐름 변경은 docs/architecture.md, 운영·인터페이스 지침은 docs/extension-points.md에 반영한다.
확정된 항목을 extension-points.md에서 지우고 ADR이나 계약으로 옮겼는지 확인한다.
검증을 실행할 수 없으면 실행 명령, 실패 원인, 남은 위험을 남긴다.

같은 사실을 여러 문서에 적지 않는다. 하나가 정본이고 나머지는 링크한다. 고치기 전에 그 사실의 정본인지 먼저 확인한다. 정본이 아니면 링크로 바꾼다. README의 문서 표는 "읽을 때 어디를 보나", 아래 표는 "쓸 때 어디에 쓰나"다.

폐쇄망 반입 대상이다. 외부 네트워크를 요구하는 의존성·플러그인·마켓플레이스를 추가하기 전에 반입 환경에서 동작하는지 먼저 확인한다.
아직 git 저장소가 초기화되지 않았다. git log로 변경 이유를 찾을 수 없고, 되돌릴 이력도 없다. 파일을 지우거나 크게 바꾸기 전에 그 사실을 먼저 알린다. 왜 그렇게 되어 있는지는 코드가 아니라 docs/decisions/의 ADR에 있다.