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