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