dap-was-dapmt/docs/superpowers/plans/2026-08-06-mcp-sdk-validator-updater.md

MCP SDK Validator and Source Updater 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: Keep tool-name validation and source metadata updates functional after replacing the custom @McpFunction annotation with Spring AI's @McpTool.

Architecture: McpToolNameValidator will scan @McpTool(name = "...") declarations for naming and duplication rules. ToolSourceUpdater will update SDK-owned fields (name, description) on @McpTool and project-owned fields (group, register, requiresApproval) on adjacent @ToolHint, without trying to write unsupported fields to the SDK annotation.

Tech Stack: Java 21, JUnit 5, Spring AI MCP annotations, Gradle.

Global Constraints

• Preserve the existing tool-name convention and duplicate-name build validation.
• Do not reintroduce the removed custom McpFunction annotation.
• Keep project-specific metadata in io.shinhanlife.dat.lib.annotation.ToolHint.
• Verify with focused tests and gradlew.bat test.

---

Task 1: Migrate tool-name validation

Files:

• Modify: dat-was-lib/src/main/java/io/shinhanlife/dat/lib/validation/McpToolNameValidator.java
• Modify: dat-was-lib/src/test/java/io/shinhanlife/dat/lib/validation/McpToolNameValidatorTest.java

Interfaces:

• Consumes: Java source files containing @McpTool(name = "...").

• Produces: McpToolNameValidator.assertUnique(Path) that rejects duplicate or invalid SDK tool names.

• Write tests using @McpTool source snippets for duplicate, invalid, and valid names.

• Run :dat-was-lib:test --tests *McpToolNameValidatorTest and confirm current implementation does not detect those annotations.

• Replace the annotation scan target from @McpFunction to @McpTool.

• Re-run the focused test and confirm it passes.

Task 2: Migrate source metadata update behavior

Files:

• Modify: dat-was-lib/src/main/java/io/shinhanlife/dat/lib/util/ToolSourceUpdater.java
• Create: dat-was-lib/src/test/java/io/shinhanlife/dat/lib/util/ToolSourceUpdaterTest.java

Interfaces:

• Consumes: a tool interface source containing @McpTool and @ToolHint.

• Produces: ToolSourceUpdater.updateToolSource(String, String, String, boolean, Boolean) that updates SDK name/description and project metadata without emitting invalid @McpTool attributes.

• Write a temporary-source test defining one SDK annotation and one ToolHint annotation.

• Run the focused test and confirm the legacy updater cannot locate @McpTool declarations.

• Update annotation matching and replacements: description belongs to @McpTool; group, register, and requiresApproval belong to @ToolHint.

• Re-run the focused test and confirm it passes.

Task 3: Restore test-suite compilation after SDK migration

Files:

• Modify: stale tests referencing McpFunction or old package locations.

Interfaces:

• Consumes: McpTool, ToolHint, current ToolSchemaResolver, and current package names.

• Produces: compilation and behavioral coverage aligned with the SDK-based production code.

• Replace stale annotation and resolver signatures in tests.

• Fix package relocation and missing assertion imports without widening production visibility.

• Run gradlew.bat test.