사원 식별자를 암호화 전제 없이 불투명 값으로 서술한다

README와 계약 v0.3이 employee-no·virtual-employee-no를 "암호화된 사원번호"로 적고 MCP가 복호화하지 않는다고 설명했다. 암호화 여부는 MCP가 확인할 수 없고 계약이 요구하는 것도 아니므로, MCP 관점에서 참인 것만 남긴다. 해석하지 않고 그대로 전달하는 불투명 값이라는 사실이다. 로그 규칙은 그대로 둔다. 로그에는 guid와 x-request-id만 남기고 사원 식별자는 기록하지 않는다. IntelliJ 마크다운 포맷터가 표 정렬과 줄바꿈을 함께 정리해 diff가 크다. 서식 외의 실제 변경은 위 두 가지와 운영 설정 절의 미정 표기 추가다. 남은 정리: ADR-0006은 전제 2에서 여전히 "암호화되어 전달되고 복호화 키는 사내 KMS에서 발급받는다"고 적고 있어 이 변경과 어긋난다. ADR의 전제를 바꾸는 것은 별도 결정이므로 이 커밋에 포함하지 않는다. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-22 23:32:12 +09:00
parent d31e5ce0ab
commit 37fc0d5ebe
2 changed files with 99 additions and 71 deletions
--- a/README.md
+++ b/README.md
@@ -1,6 +1,7 @@
 # AX HUB MCP Server

-Agent Builder와 Tool Service 사이의 stateless MCP 실행 계층이다. Agent Builder가 `tools/call`에 명시한 단일 Tool을 JSON-RPC 2.0과 `inputSchema`로 검증하고, 서버가 관리하는 metadata에 따라 Tool Service를 호출한다.
+Agent Builder와 Tool Service 사이의 stateless MCP 실행 계층이다. Agent Builder가 `tools/call`에 명시한 단일 Tool을 JSON-RPC 2.0과 `inputSchema`로 검증하고, 서버가 관리하는 metadata에 따라 Tool
+Service를 호출한다.

 이 서버는 Tool을 추천하거나 사용자 의도를 판단하지 않는다. 업무 규칙은 Tool Service가, Tool 선택과 사용자·Agent별 노출 정책은 Agent Builder가 소유한다.

@@ -24,16 +25,18 @@ SDK 적용 경계는 [MCP Java SDK 선택적 도입 설계](docs/mcp-java-sdk-ad

 **빌드는 외부 저장소에서 코드 스타일 도구를 내려받지 않는다.** 폐쇄망에서 검사 하나 때문에 빌드 전체가 시작되지 못하는 상황을 만들지 않기 위해서다. 서식 검사는 저장소 안의 테스트가 소유한다.

-Java 포맷은 `.idea/codeStyles/Project.xml`의 IntelliJ IDEA 코드 스타일로 고정한다. 이 파일은 저장소에 포함되어 있어 IDE에서 자동으로 적용된다. Java 소스의 줄바꿈은 운영체제와 무관하게 LF이며 `.gitattributes`가 commit 시점에 이를 강제한다.
+Java 포맷은 `.idea/codeStyles/Project.xml`의 IntelliJ IDEA 코드 스타일로 고정한다. 이 파일은 저장소에 포함되어 있어 IDE에서 자동으로 적용된다. Java 소스의 줄바꿈은 운영체제와 무관하게 LF이며 `.gitattributes`가 commit
+시점에 이를 강제한다.

 두 가지가 보장하는 범위가 다르다.

-| 무엇이 | 보장하는 것 | 조건 |
-|---|---|---|
-| `CodeStyleContractTest` | LF 줄바꿈, 탭 없음, 후행 공백 없음, 파일 끝 개행, 미사용 import 없음 | 항상 (`test`에 포함) |
-| IntelliJ formatter | 4칸 들여쓰기, 줄바꿈 스타일, 단순 lambda·다중 표현식 분리 | `IDEA_FORMATTER` 설정 시에만 |
+| 무엇이                     | 보장하는 것                                         | 조건                      |
+|-------------------------|------------------------------------------------|-------------------------|
+| `CodeStyleContractTest` | LF 줄바꿈, 탭 없음, 후행 공백 없음, 파일 끝 개행, 미사용 import 없음 | 항상 (`test`에 포함)         |
+| IntelliJ formatter      | 4칸 들여쓰기, 줄바꿈 스타일, 단순 lambda·다중 표현식 분리          | `IDEA_FORMATTER` 설정 시에만 |

-**`IDEA_FORMATTER`가 없으면 IntelliJ formatter 단계는 경고를 남기고 건너뛴다.** IntelliJ가 없는 CI나 폐쇄망 빌드에서 빌드가 깨지지 않게 하기 위한 것이며, 그 환경에서는 들여쓰기와 줄바꿈이 검증되지 않는다는 뜻이다. **도구 없이 판정할 수 있는 규칙은 그때도 계속 검사된다.**
+**`IDEA_FORMATTER`가 없으면 IntelliJ formatter 단계는 경고를 남기고 건너뛴다.** IntelliJ가 없는 CI나 폐쇄망 빌드에서 빌드가 깨지지 않게 하기 위한 것이며, 그 환경에서는 들여쓰기와 줄바꿈이 검증되지 않는다는 뜻이다. **도구 없이 판정할 수
+있는 규칙은 그때도 계속 검사된다.**

 포맷터로 코드를 실제로 정리하려면 경로를 지정하고 `ideaFormat`을 실행한다. `CodeStyleContractTest`는 검사만 하고 고쳐 주지 않는다.

@@ -67,12 +70,13 @@ Agent Builder는 공개 URL마다 별도 MCP로 등록하고 initialize한다. U

 ## Tool metadata와 실행

-| 환경 | Tool 원천 | Redis |
-|---|---|---|
-| `local` | local JSON fixture | 사용 안 함 |
+| 환경        | Tool 원천                                 | Redis                           |
+|-----------|-----------------------------------------|---------------------------------|
+| `local`   | local JSON fixture                      | 사용 안 함                          |
 | 운영(`ocp`) | 이 배포가 보는 Tool Service 매니페스트를 주기적으로 pull | 성공 snapshot 공유와 warm start에만 사용 |

-요청 경로의 `tools/list`와 `tools/call`은 in-memory snapshot만 읽는다. 운영 refresh는 bundle별 last-good을 유지하고, 모든 bundle에 사용 가능한 성공본이 있을 때만 aggregate를 교체한다. 조회 실패만으로 Tool을 제거하지 않으며 정상 매니페스트에서 삭제가 확인될 때만 반영한다. 코드는 bundle N개 병합을 지원하지만 **운영 배포의 bundle은 항상 하나다**([ADR-0007](docs/decisions/ADR-0007-one-mcp-per-tool-service.md)).
+요청 경로의 `tools/list`와 `tools/call`은 in-memory snapshot만 읽는다. 운영 refresh는 bundle별 last-good을 유지하고, 모든 bundle에 사용 가능한 성공본이 있을 때만 aggregate를 교체한다. 조회 실패만으로 Tool을
+제거하지 않으며 정상 매니페스트에서 삭제가 확인될 때만 반영한다. 코드는 bundle N개 병합을 지원하지만 **운영 배포의 bundle은 항상 하나다**([ADR-0007](docs/decisions/ADR-0007-one-mcp-per-tool-service.md)).

 Tool 실행 주소는 local `_meta.endpoint` 또는 운영 `baseEndpoint` 설정에서만 정한다. Agent Builder의 `arguments`와 Tool Service 매니페스트는 호출 대상을 바꿀 수 없다.

@@ -82,17 +86,17 @@ Tool 실행 주소는 local `_meta.endpoint` 또는 운영 `baseEndpoint` 설정

 호출자가 보내는 헤더는 다섯 개이며 **모두 선택값**이다. 값은 그대로 Tool Service 요청 헤더로 bypass한다.

-| 헤더 | 의미 | 없을 때 |
-|---|---|---|
-| `guid` | 요청 하나를 끝까지 따라가는 상관 값(UUID) | 서버가 생성 |
-| `x-request-id` | 개별 HTTP 요청 ID | 서버가 생성 |
-| `mcp-session-id` | initialize lifecycle 상관 값 | 전달하지 않음 |
-| `employee-no` | 암호화된 사원번호 | 전달하지 않음 |
-| `virtual-employee-no` | 암호화된 가상사원번호(상담사 등 비사원) | 전달하지 않음 |
+| 헤더                    | 의미                         | 없을 때    |
+|-----------------------|----------------------------|---------|
+| `guid`                | 요청 하나를 끝까지 따라가는 상관 값(UUID) | 서버가 생성  |
+| `x-request-id`        | 개별 HTTP 요청 ID              | 서버가 생성  |
+| `mcp-session-id`      | initialize lifecycle 상관 값  | 전달하지 않음 |
+| `employee-no`         | 사원번호                       | 전달하지 않음 |
+| `virtual-employee-no` | 가상사원번호(상담사 등 비사원)          | 전달하지 않음 |

-`employee-no`와 `virtual-employee-no`는 **MCP가 복호화하지 않는 불투명 값**이다. 형식이나 의미를 해석하지 않고, 개행이 섞여 downstream 헤더가 조작되는 것만 막은 뒤 그대로 전달한다.
+`employee-no`와 `virtual-employee-no`는 **불투명 값**이다. 형식이나 의미를 해석하지 않고, 개행이 섞여 downstream 헤더가 조작되는 것만 막은 뒤 그대로 전달한다.

-MDC는 사용하지 않는다. 로그에는 `guid`와 `x-request-id`만 남기며 **사원 식별자는 암호문이라도 기록하지 않는다.** request/response body와 credential도 남기지 않는다.
+MDC는 사용하지 않는다. 로그에는 `guid`와 `x-request-id`만 남기며 **사원 식별자는 기록하지 않는다.** request/response body와 credential도 남기지 않는다.

 `Authorization`은 `mcp.tool-client.forward-authorization` 설정이 켜진 경우에만 전달한다. MCP는 이 값을 해석하지 않는다.

@@ -100,20 +104,24 @@ MDC는 사용하지 않는다. 로그에는 `guid`와 `x-request-id`만 남기

 **이 서버는 인증도 인가도 하지 않는다.** 요청자 신원을 검증하지 않고, Tool 실행 권한을 판단하지 않으며, 사원 식별자를 복호화하지 않는다. 결정과 근거는 [ADR-0006](docs/decisions/ADR-0006-no-authentication-in-mcp.md)이다.

-| 책임 | 주체 |
-|---|---|
+| 책임                        | 주체                           |
+|---------------------------|------------------------------|
 | 외부 호출자를 Agent Builder로 제한 | OpenShift Route IP allowlist |
-| MCP Pod 직접 접근 제한 | 플랫폼 NetworkPolicy |
-| 사용자 인증과 Tool 실행 권한 | Agent Builder |
-| 사원 식별자 복호화(KMS)와 업무 권한 | Tool Service |
+| MCP Pod 직접 접근 제한          | 플랫폼 NetworkPolicy            |
+| 사용자 인증과 Tool 실행 권한        | Agent Builder                |
+| 업무 권한                     | Tool Service                 |

-⚠️ **Route IP allowlist와 NetworkPolicy는 선택 사항이 아니다.** 외부 요청은 Route가 Agent Builder의 고정 egress CIDR만 받고, backend 요청은 ingress controller 또는 허용된 Agent Builder namespace에서만 MCP Pod에 도달한다. 실제 CIDR을 넣지 않은 배포는 운영에 사용할 수 없다. `HelmDeploymentContractTest`가 두 경계가 Chart에서 빠지지 않도록 고정한다.
+⚠️ **Route IP allowlist와 NetworkPolicy는 선택 사항이 아니다.** 외부 요청은 Route가 Agent Builder의 고정 egress CIDR만 받고, backend 요청은 ingress controller 또는 허용된 Agent Builder
+namespace에서만 MCP Pod에 도달한다. 실제 CIDR을 넣지 않은 배포는 운영에 사용할 수 없다.

 ## 운영 설정

+**아래 내용은 아직 미정으로 내부 CI/CD 정책에 따라 변경된다. (참고 용도로만 확인)**
+
 운영 설정은 Helm Chart가 만드는 ConfigMap이 담당한다. `identity`와 bundle 설정을 환경변수로 나열하지 않는 이유는 항목이 흩어질수록 인덱스 실수가 조용한 오라우팅이 되기 때문이다.

-`identity`는 `{배포 이름}-{global.env}`로 template이 조립한다. 현재 Redis cache 구현이 이 값을 사용하지만, Redis key namespace와 공유 정책은 아직 확정되지 않았으므로 [extension-points.md](docs/extension-points.md#운영-적용-전-필수-보완)에서 합의한다.
+`identity`는 `{배포 이름}-{global.env}`로 template이 조립한다. 현재 Redis cache 구현이 이 값을 사용하지만, Redis key namespace와 공유 정책은 아직 확정되지
+않았으므로 [extension-points.md](docs/extension-points.md#운영-적용-전-필수-보완)에서 합의한다.

 - 업무 포트: `SERVER_PORT`(기본 8080)
 - management 포트: `MANAGEMENT_SERVER_PORT`(운영 기본 9090)
@@ -123,7 +131,9 @@ MDC는 사용하지 않는다. 로그에는 `guid`와 `x-request-id`만 남기
 readiness는 첫 Tool discovery 시도가 끝나고 usable in-memory snapshot이 있을 때만 UP이다. 원천 장애 중에도
 기존 memory 또는 Redis last-good이 있으면 서비스를 유지하고, 아무 성공본도 없으면 트래픽을 받지 않는다.

-**MCP 배포 하나는 Tool Service 하나만 본다**([ADR-0007](docs/decisions/ADR-0007-one-mcp-per-tool-service.md)). 대상을 늘리는 방법은 bundle 목록을 늘리는 것이 아니라 배포를 하나 더 만드는 것이다. 외부에서는 같은 host의 고유 path로 각 배포를 노출하고 컨테이너가 그 path를 그대로 처리한다([ADR-0009](docs/decisions/ADR-0009-container-handles-public-mcp-path.md)). 배포는 업무 × 중요도 등급으로 나뉘며, 등급이 replica 수와 PodDisruptionBudget을 정한다.
+**MCP 배포 하나는 Tool Service 하나만 본다**([ADR-0007](docs/decisions/ADR-0007-one-mcp-per-tool-service.md)). 대상을 늘리는 방법은 bundle 목록을 늘리는 것이 아니라 배포를 하나 더 만드는 것이다. 외부에서는
+같은 host의 고유 path로 각 배포를 노출하고 컨테이너가 그 path를 그대로 처리한다([ADR-0009](docs/decisions/ADR-0009-container-handles-public-mcp-path.md)). 배포는 업무 × 중요도 등급으로 나뉘며, 등급이
+replica 수와 PodDisruptionBudget을 정한다.

 배포 정의는 [Helm Chart](deploy/helm/mcp-server/) 하나뿐이다. 배포 토폴로지는 `values.yaml`이, 환경 차이는 `values-{dev,test,prod}.yaml`이 소유한다. 설치할 배포 하나는 `--set`으로 고른다.

@@ -151,15 +161,15 @@ deployments:

 ## 문서 R&R

-| 문서 | 책임 |
-|---|---|
-| [README](README.md) | 프로젝트 진입점과 실행 방법 |
-| [architecture.md](docs/architecture.md) | 현재 코드 구조, 요청 흐름, 내부 책임과 장애 동작 |
-| [Agent Builder-MCP contracts](docs/contracts/agent-builder-mcp/README.md) | Agent Builder와의 HTTP/JSON-RPC wire 계약 |
-| [Tool Service-MCP contracts](docs/contracts/tool-service-mcp/README.md) | 매니페스트와 Tool 실행 wire 계약 |
-| [Portal-MCP contracts](docs/contracts/portal-mcp/README.md) | Portal registry의 Tool Server endpoint 목록 조회 wire 계약 |
-| [decisions](docs/decisions/README.md) | 결정 이유와 대안 이력 |
-| [extension-points.md](docs/extension-points.md) | 아직 미합의인 항목과 운영 보완 작업 |
-| [codex-workflow.md](docs/codex-workflow.md) | 저장소 작업 규칙과 공개 정책 |
+| 문서                                                                        | 책임                                                  |
+|---------------------------------------------------------------------------|-----------------------------------------------------|
+| [README](README.md)                                                       | 프로젝트 진입점과 실행 방법                                     |
+| [architecture.md](docs/architecture.md)                                   | 현재 코드 구조, 요청 흐름, 내부 책임과 장애 동작                       |
+| [Agent Builder-MCP contracts](docs/contracts/agent-builder-mcp/README.md) | Agent Builder와의 HTTP/JSON-RPC wire 계약               |
+| [Tool Service-MCP contracts](docs/contracts/tool-service-mcp/README.md)   | 매니페스트와 Tool 실행 wire 계약                              |
+| [Portal-MCP contracts](docs/contracts/portal-mcp/README.md)               | Portal registry의 Tool Server endpoint 목록 조회 wire 계약 |
+| [decisions](docs/decisions/README.md)                                     | 결정 이유와 대안 이력                                        |
+| [extension-points.md](docs/extension-points.md)                           | 아직 미합의인 항목과 운영 보완 작업                                |
+| [codex-workflow.md](docs/codex-workflow.md)                               | 저장소 작업 규칙과 공개 정책                                    |

 Superseded/Rejected 문서는 이력일 뿐 현재 구현 근거가 아니다. 코드나 공개 계약을 변경할 때는 가까운 테스트와 해당 현재 계약을 함께 수정한다. 변경을 마치기 전에 실행할 검증 명령은 [AGENTS.md](AGENTS.md)의 완료 기준이 정본이다.