Initial commit

.agents/skills/verify-mcp-server-change/references/change-checklist.md

@@ -0,0 +1,65 @@
+# MCP Server Change Checklist
+
+Read only the sections relevant to the requested change.
+
+## JSON-RPC and MCP contracts
+
+- Preserve the JSON-RPC envelope, request `id`, and HTTP-versus-JSON-RPC error behavior.
+- Confirm invalid JSON, invalid requests, unknown methods, invalid params, and tool failures map to the intended error codes.
+- Keep `initialize`, `notifications/initialized`, `tools/list`, and `tools/call` behavior internally consistent.
+- Update request samples when a public payload or response shape changes.
+
+## Method dispatch and execution
+
+- Ensure method resolution remains explicit and unsupported methods fail safely.
+- Validate arguments before calling an upstream Tool Service.
+- Preserve the requested Tool order and result-to-call correlation.
+- Keep tool selection outside this server; never infer or substitute a Tool implicitly.
+- Confirm timeout, partial failure, and upstream client errors produce safe normalized results.
+
+## Tool Registry and cache
+
+- Keep the request path free of Redis: `tools/list` and `tools/call` read the in-memory snapshot only.
+- Keep Redis on the background refresh path only, as a cross-replica sharing point rather than a source of truth.
+- Write to Redis only after a successful source fetch, and update memory before Redis.
+- Never let any failure path empty the Tool snapshot; replace it only on success.
+- Treat Redis health, serialization, read, and write failures as cache degradation rather than correctness failures.
+- Confirm cold-start behavior when no cache is available.
+- Keep metadata versioning and enabled/disabled Tool behavior explicit.
+- Preserve the Redis key namespace (`key-prefix:identity:schema-version`) when touching cache code.
+
+## Request context, trace, and audit
+
+- Propagate `traceId`, `requestId`, `mcpSessionId`, `agentId`, and `userId` where the contract requires them.
+- Clear ThreadLocal and MDC state on every completion and exception path.
+- Mask sensitive values only in log and audit copies; do not mutate execution payloads.
+- Keep payload logging disabled by default.
+- Verify audit hooks do not change business results.
+
+## Streaming
+
+- Preserve NDJSON framing and final response semantics.
+- Flush progress notifications without losing the original request correlation.
+- Handle upstream SSE `data:` lines and NDJSON consistently.
+- Consider client disconnect, proxy buffering, timeout, and back-pressure implications.
+- Test both streaming and non-streaming paths when shared code changes.
+
+## Configuration and deployment
+
+- Keep the `local` profile runnable without Redis.
+- Keep production values externally configurable; do not commit credentials or trust material.
+- Preserve stateless replicas, read-only container filesystem support, and arbitrary UID compatibility.
+- Review liveness, readiness, graceful shutdown, ingress buffering, timeouts, and egress policy when deployment behavior changes.
+- Explain compatibility impact when changing Java, Spring Boot, Spring AI BOM, Gradle, or container settings.
+
+## Tests and documentation
+
+- Mirror production responsibility in the corresponding test package.
+- Add regression coverage for the failure mode being fixed.
+- Prefer focused unit tests; use broader application tests for wiring and profile behavior.
+- For every added or modified `src/main/java` top-level type, add or refresh a Korean Javadoc directly above the declaration. Explain its responsibility, its HTTP/MCP request or processing stage (or state that it has none), and its key dependencies or external boundary.
+- For every added or modified explicit production method or constructor, add or refresh a Korean Javadoc. Explain its purpose, input/output or error handling, and invocation timing or impact. Exclude only compiler-generated record accessors, simple enum constants, and empty marker interfaces.
+- Review the changed source declarations and their Javadocs before test execution; comment coverage is required even when behavior tests pass.
+- Update `docs/architecture.md` for responsibility or flow changes.
+- Update `docs/extension-points.md` for new operational gaps, agreements, or extension guidance.
+- Run the Gradle wrapper test task before handoff.