dap-was-dapmt/docs/superpowers/plans/2026-08-25-mcp-header-contract.md

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.