# MCP Header Contract Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Replace the legacy Tool Pod request headers with the approved 12-header contract and propagate every value through execution and outbound HTTP calls.

**Architecture:** `McpRequestHeaders` is the normalized immutable carrier. Both MCP filtering and the legacy REST adapter populate it, `McpToolExecutionService` returns the transport-safe correlation headers, and `AxhubHttpComponent` forwards the complete contract to downstream HTTP services. All headers remain optional.

**Tech Stack:** Java 21, Spring Web, Jakarta Servlet, JUnit 5, AssertJ, Gradle

**Spec:** User-approved header list in the 2026-08-25 Codex task.

## Global Constraints

- Canonical headers are exactly `X-Guid`, `X-Praf-No`, `X-Request-Id`, `X-Request-Time`, `X-Vrtl-Praf-No`, `X-App-Code`, `X-Project-Code`, `X-User-Ip`, `X-Caller-Ip`, `X-Caller-Host`, `X-Channel`, and `X-Agent-Id`.
- Remove legacy `guid`, `employee-no`, and `virtual-employee-no`; do not retain aliases.
- Keep `mcp-session-id` because it is MCP transport metadata rather than a replaced business header.
- Do not reject absent headers; capture and propagate values only when present.
- Do not commit or push unless the user requests it separately.

---

### Task 1: Request Capture Contract

**Files:**
- Modify: `dat-was-lib/src/test/java/io/shinhanlife/dat/mcc/mcp/McpRequestHeaderFilterTest.java`
- Modify: `dat-was-lib/src/test/java/io/shinhanlife/dat/mcc/presentation/BusinessToolControllerHeaderContractTest.java`
- Modify: `dat-was-lib/src/main/java/io/shinhanlife/dat/lib/mcp/McpRequestHeaders.java`
- Modify: `dat-was-lib/src/main/java/io/shinhanlife/dat/lib/mcp/McpRequestHeaderFilter.java`
- Modify: `dat-was-lib/src/main/java/io/shinhanlife/dat/mcc/presentation/BusinessToolController.java`

**Interfaces:**
- Produces: `McpRequestHeaders` accessors for all 12 canonical values plus `mcpSessionId()`.

- [ ] Change the filter test fixture to send literal canonical headers and assert every record component.
- [ ] Change the controller contract test to assert the exact 12 canonical names plus `mcp-session-id`, all with `required=false`.
- [ ] Run the two tests and confirm failure because the record and controller still expose legacy fields.
- [ ] Expand the record and populate it from both HTTP entry points.
- [ ] Run the two tests and confirm they pass.

### Task 2: Execution Response and Downstream Propagation

**Files:**
- Modify: `dat-was-lib/src/test/java/io/shinhanlife/dat/lib/mcp/ToolExecutionServiceTest.java`
- Modify: `dat-was-lib/src/test/java/io/shinhanlife/dat/lib/integration/http/component/AxhubHttpComponentTest.java`
- Modify: `dat-was-lib/src/main/java/io/shinhanlife/dat/lib/mcp/McpToolExecutionService.java`
- Modify: `dat-was-lib/src/main/java/io/shinhanlife/dat/lib/integration/http/component/AxhubHttpComponent.java`

**Interfaces:**
- Consumes: the expanded `McpRequestHeaders` record from Task 1.
- Produces: response headers `X-Request-Id`, `X-Guid`, and `mcp-session-id`; downstream calls receive all 12 canonical headers plus the MCP session header.

- [ ] Update execution and HTTP integration tests with hand-written literal values for every field.
- [ ] Run both tests and confirm failure on missing canonical propagation.
- [ ] Return canonical correlation headers and forward all present request headers.
- [ ] Run both tests and confirm they pass.

### Task 3: Documentation and Console Contract

**Files:**
- Modify: `README.md`
- Modify: `dat-was-lib/src/main/resources/static/tool-test-console.html`
- Modify: `dat-was-lib/src/test/java/io/shinhanlife/dat/mcc/presentation/ToolTestConsoleResourceTest.java`

**Interfaces:**
- Consumes: the canonical header names from Tasks 1 and 2.
- Produces: runnable examples and console calls that no longer send removed headers.

- [ ] Update the console resource test to require canonical header labels and calls.
- [ ] Run the resource test and confirm failure on legacy header text.
- [ ] Update README examples/table and console request/response labels.
- [ ] Run the resource test and confirm it passes.
- [ ] Run `./gradlew.bat :dat-was-lib:test` and confirm the full module suite passes.