66 lines
4.1 KiB
Markdown
66 lines
4.1 KiB
Markdown
# 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.
|