spring-mcp-contracts

Spring MCP contracts

Change a public Spring MCP JSON contract without inventing framework resolution, source positions, model provenance, nullability, injection outcomes or pagination state.

Tool names, response fields and API names in this skill are examples from the codebase at the time of writing. Apply the rule, then verify the actual names, signatures and registrations in the current branch.

Inputs

• Target tool name, issue/reproducer, expected JSON fields and compatibility constraints.
• Affected IntelliJ Platform and Kotlin versions from this branch's build files.
• Current implementation and directly covering tests in the MCP module; follow coding-guard and test-driven-development before changing code.
• For bean-model work: the approved design/spec, application and context selection rules, source preference (static analysis versus a loaded runtime snapshot), response budget, and whether the change targets a lookup tool or an existing listing tool.

Critical constraints

• Prefer the IDE Spring model tools over text search when available, and report whether the model answered more precisely than source search.
• Keep model-relative claims distinct from runtime claims. An empty result means "not found in the selected model", never "the application cannot start". Never promise successful injection or live application-context behaviour from static or snapshot data.
• Select one runtime snapshot/context before union, deduplication or conversion into the plugin's bean objects. Never merge contexts to avoid an ambiguity error.
• Resolve declarations and types in the selected application module's classpath. Do not resolve through project-wide caches or scopes (for example a project-level library class cache or projectScope), which can return an equally named class from another application.
• Once a scoped candidate set exists, matching and selection must not re-query module- or project-wide bean sources (for example array or framework-bean fallbacks inside the existing resolver). Prepare supported candidates in the snapshot adapter instead.
• Exact name lookup filters the known names/aliases of the scoped set directly. Never route it through a type-less resolver, and never widen an empty result to all candidates.
• Type inventory does not apply primary/priority selection. Injection selection may apply it only when the scoped candidate set is complete enough to support the rule.
• Unknown type, identity or unsupported selection rule yields an explicit partial/indeterminate outcome, not a fabricated negative or confident match.
• Preserve declarations whose produced type has no project module (for example a factory method returning a JDK or library type); derive location from the declaring member or snapshot provenance, not from the produced class alone.
• Measure the final serialized envelope — metadata, revision, continuation and errors included — in UTF-16 code units against the tool's documented budget, and test it inside the client's content wrapper. Never slice scalar values and never skip an oversized record without an explicit overflow result.
• Do not add reverse usage searches to a lookup tool unless the approved design includes them. Do not extend this change into a neighbouring tool whose work is tracked separately.
• Keep a fix to a shared non-MCP helper (for example SpringWebUtil, an endpoint loader, EndpointPathPatterns once a non-MCP caller uses it) out of the MCP commit. Lines without MCP Server skip MCP commits whole during backports, so the helper fix would silently stay off them. Land it as its own PR from main and stack the MCP PR on it.
• Keep existing response shapes byte-identical for the common case: a new field that only some answers need is nullable and serialized NON_NULL, or is present in every answer with a documented null. Never rename or retype a field silently; a changed meaning of an existing field (for example a line number) is a breaking change named in CHANGELOG and the PR.
• Report a guess and a declared fact in different fields (for example assumedPrefix versus basePath). Never let a guess reuse a field whose value the configuration states.