forked from kimhyungsik/ax_hub_mcp_tool
62 lines
3.4 KiB
Markdown
62 lines
3.4 KiB
Markdown
# 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`.
|