# 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 |

근거: [ADR-0001](docs/decisions/ADR-0001-stateless-execution-boundary.md) · [ADR-0006](docs/decisions/ADR-0006-no-authentication-in-mcp.md)

## 2. 불변식 — 깨면 안 되는 것

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

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

정본은 [architecture.md](docs/architecture.md)와 [Tool Service 계약 v0.2](docs/contracts/tool-service-mcp/protocol-v0.2-bundle-discovery.md)다. Redis·부분 실패·시간 예산 처리는 **방어 코드가 아니라 계약이다.** 단순화 대상이 아니다.

## 3. 작업 절차

### 시작 전

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

### 변경 중

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

### 완료

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

## 4. 문서 소유 경계

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

| 사실의 종류 | 정본 |
|---|---|
| 외부와 약속한 요청·응답 모양 | `docs/contracts/` |
| 내부 흐름·클래스 책임·장애 시 동작 | `docs/architecture.md` |
| 실행 방법·endpoint·환경변수 | `README.md` |
| 아직 확정되지 않은 협의·보완 항목 | `docs/extension-points.md` |
| 되돌리지 않을 설계 판단과 근거 | `docs/decisions/` (ADR) |

## 5. 무엇을 만들 것인가

- **ADR**: 되돌리지 않을 판단을 할 때. 기존 ADR은 덮어쓰지 않고 새 ADR에서 대체 관계를 적는다.
- **테스트**: 문서로만 지키는 규칙은 결국 깨진다. 잠글 수 있는 불변식은 계약 테스트로 고정한다.
- **skill·hook**: 특정 영역에 독립적인 규칙이 반복될 때만. 일회성 지침은 만들지 않는다.

## 6. 이 저장소의 조건

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