Preflight: Spring MCP

This skill is part of the Spring Agent Toolkit and is designed to work with the Spring MCP server (provided by the Amplicode IntelliJ plugin). Before doing anything else, check your tool list for any Spring MCP tool — they are exposed under the

amplicode

MCP server (e.g.

get_project_summary

list_module_dependencies

get_entity_details

); harnesses that flatten MCP tools into the tool list use the

mcp__amplicode__

prefix on the same names.

If at least one Amplicode tool is available — MCP is connected. Proceed with the skill below.
If none are available — stop and invoke the amplicode-install
skill (bundled with the Spring Agent Toolkit). It installs the Amplicode plugin and walks the user through the «Настроить Spring Agent» welcome-screen button + MCP-client restart. After it completes, the MCP tools become available — resume this skill.
If
```
amplicode-install
```
is not registered in your skill list, tell the user (in their language): "This skill needs the Amplicode IntelliJ plugin and its MCP server. Install it from https://amplicode.ru/marketplace into IntelliJ IDEA Ultimate/Community or GigaIDE, open any project, click «Настроить Spring Agent» on the Amplicode welcome screen, then restart your MCP client."

CRUD REST Controller

Generates a

@RestController

class with standard CRUD endpoints for an entity, using a Spring Data repository, optional DTO mapping, pagination, filtering, and patch support.

CRITICAL: Code ONLY from examples/ files. If no matching example -- STOP and ask user. CRITICAL: For questions with a fixed set of choices, prefer
AskUserQuestion
> its analogue > plain text list. Plain numbered text lists are the last resort when no interactive tool is available. CRITICAL: Read the conversation context BEFORE running Step 1. Half the questions in Steps 2–4 may already be answered by the user's prompt and prior turns. Re-asking what was already said is the #1 reason this skill feels slow.

Defaults

The options below are grouped by topic.

language

and

bootVersion

are auto-detected; all other options are resolved via the Decision-making principle (derive from context → confirm → ask).

Block 1 — Entity & repository

Option	Default	Notes
entity	--	which entity to create controller for
repository	first existing for entity	which repository to use

Block 2 — DTO mode

Option	Default	Notes
DTO mode	DTO (recommended)	if no existing DTO for entity, delegate to `dto-creator` ; user can opt out to use entity directly

Block 3 — Controller naming & paths

Option	Default	Notes
controllerName	`{EntityName}Controller`	suggest based on project naming convention
controllerPackage	same as existing controllers or mainPackage	auto-detected from project
basePath	`/rest`	persistent base path
resourcePath	`/{pluralizedEntityName}`	auto from entity name

Block 4 — Pagination & filtering

Option	Default	Notes
pagination	true	enable pagination for GET_LIST
paginationType	PAGE	PAGE or WINDOW (WINDOW requires filter to be selected; avoids count query overhead)
filter	None	JPA Specification filter for GET_LIST

Auto-detected (no questions)

Option	Source
patchStrategy	ObjectMapper
language	`get_project_summary`
bootVersion	`get_project_summary`

Smart defaults: If user says "use defaults", "all defaults", "default settings", or similar -- skip ALL questions where "Always ask?" = NO. Only ask mandatory questions.

Smart answer recognition: When user provides a value instead of choosing from a numbered list, accept it directly. Examples:

Question "Which entity?" --> user answers "Product" --> this IS the entity, don't re-ask
Question "Repository?" --> user answers "ProductRepository" --> this IS the choice
If user provides multiple answers in one message --> accept all, skip answered questions
NEVER ask a question that the user already answered (even implicitly)

Batch questions: When multiple questions must be asked (i.e. cannot be resolved by principles 1–2 of the Decision-making principle), group them into a single

AskUserQuestion

call (up to 4 questions per call) when they:

Belong to the same logical section
Don't depend on each other's answers

Rules:

Maximum 3-4 questions per
```
AskUserQuestion
```
call
Mark the recommended option with
```
(Recommended)
```
and place it first
Never batch questions from DIFFERENT decision branches
The primary branching question (entity selection) is always asked ALONE
Prefer
```
AskUserQuestion
```
for choices; fall back to plain text lists only if the tool is unavailable

Decision-making principle — context first, then ask

Before asking the user any question, attempt to derive the answer from the context already gathered: project summary, module dependencies, entity details, existing files in the package, prior turns of this conversation, and the user's original prompt. Only ask when the context yields no clear default or when the choice is genuinely user-specific (e.g. which entity, which repository).

Hierarchy of decisions:

Context is unambiguous → decide silently, do NOT ask. Examples: language and JDK from
```
get_project_summary
```
; repository when there is exactly one for the entity; controller package from existing controllers; basePath from existing endpoints; Jackson version from
```
list_module_dependencies
```
; pagination type when project already uses one consistently.
Context gives a strong signal → state the decision + alternatives in one line, let the user override or stay silent. Format:
```
Will create `ProductController` at `/rest/products` with Page pagination, no DTO.
Alternatives: use DTO, Window pagination, custom paths. OK?
```
The user can answer "ok" / "yes" / silence → accept; or name an alternative → switch. This is not the same as the numbered question format — it is a single confirmation line.
Context yields no clear default → ask with
AskUserQuestion
(preferred) or its analogue, with the recommended option first. When
```
AskUserQuestion
```
is available, use it with the recommended option marked
```
(Recommended)
```
and placed first. If no interactive choice tool is available, fall back to a plain text list. Never ask iteratively ("which entity?" → user picks → "repository?" → …) when one batched call would do.
Context is fully empty for a critical input → ask plainly. This applies to: which entity (when not mentioned), the user's intent itself.

How to ask — prefer

AskUserQuestion

When a question must be asked, prefer the AskUserQuestion
tool (or its analogue) over writing a numbered list in the response body. Fall back to plain text only if no interactive choice tool is available.

Rules for

AskUserQuestion

calls in this skill:

Each call may contain up to 4 questions that are independent of each other (the tool will render them together). Use this to batch related decisions in one round-trip.
Each question has 2–4 options. The tool auto-adds an "Other" choice for free-form input — never include it manually.
Mark the recommended option by putting it first with
```
(Recommended)
```
appended to the label.
```
header
```
is a 12-char chip label (e.g. "Entity", "DTO mode", "Paths").
Each option has a
```
description
```
explaining what the choice means.

When

AskUserQuestion

is not the right tool:

Free-form input where there is no enumerable set of options (e.g. arbitrary class name, arbitrary path) — ask in plain text.
The "single confirmation line" form from principle 2 — that is a plain question with an obvious yes/no, not an enumerated choice.

The screen-driven question lists in Steps 2–4 below are a fallback for case 4. They are NOT a script to execute top-to-bottom. If a question's answer is already determined by principles 1–3, skip the question.

Step 0 -- Conversation context first (REQUIRED, no tool calls)

Before any MCP call, before any question, re-read the user's prompt and the prior turns of this conversation and extract whatever is already stated. This step costs nothing and prevents the most common failure mode of this skill — asking the user something they already said.

Build a mental checklist of inputs and tick off everything the user has already provided, explicitly or implicitly:

Input	Look for in the prompt / context
entity	a class name ( `Product` , `Order` , `Vet` ); "for X"; an open file in the IDE; a file path; a recently discussed entity in this conversation
repository	"use `ProductRepository` ", "with `OrderRepo` "; or implied — if only one repository exists for the entity
DTO mode	"with DTO", "without DTO", "use entity directly", "map to `ProductDto` "
controller name	"name it `ProductResource` ", "class `FooController` "
paths	"at `/api/products` ", "base path `/rest` ", "resource path `/items` "
pagination	"with pagination", "no pagination", "use Window", "use Page"
filter	"with filter", "no filter", "use JPA Specification"
methods	"all CRUD", "only read", "read-only", "without delete", "GET + CREATE", "full CRUD"
smart defaults	"use defaults", "all defaults", "default settings", "as usual"
prior project facts	language, JDK, dependencies — already known if discussed earlier in this conversation; do not re-fetch

For every input that is explicitly or strongly implicitly answered: mark it as decided and skip the corresponding question in Steps 2–4. Do NOT ask "which entity?" if the user wrote "create CRUD controller for Product" —

Product

is the answer. Do NOT ask "which repository?" if there is exactly one repository for the entity.

For every input that is not answered: defer to the Decision-making principle above — try to derive it from project context first (Step 1), and only then ask.

Step 0 is mental, not a tool call. Do not announce it to the user. Do not write "Step 0 done". Just internalize what the user already said before proceeding to Step 1.

Step 1 -- Gather minimal project context (automatic, no questions)

Call only the MCP tools whose result is actually consumed by a later step. Do not pre-fetch "in case we need it" — every variable here must have a concrete downstream user.

Tool	Variable	Used for
`get_project_summary`	`language` , `bootMajor` , `moduleName` , `buildFile` , `mainPackage`	language → reference file selection (java vs kotlin); bootMajor → jakarta vs javax, Jackson version; moduleName → multi-module disambiguation; buildFile → Step 6 dependency injection; mainPackage → controller package fallback
`list_module_dependencies(moduleName)`	`presentDeps`	derived flags below — SpringDoc/Validation/Jackson feature gates, Step 6 dependency check
`list_project_endpoints`	`endpoints`	Step 4 path conflict detection, existing basePath/naming convention detection

That is the entire Step 1. Do NOT fetch:

```
list_all_domain_entities
```
— needed only if the user did not name an entity in their prompt. Defer to Step 2 as a lazy fallback.
```
list_entity_repositories
```
— depends on knowing the entity, which happens in Step 2. Defer to Step 3 as a lazy fallback.
```
get_entity_details
```
— depends on knowing the entity. Defer to Step 2.
```
list_entity_dtos
```
/
```
list_entity_mappers
```
— depend on knowing the entity AND the DTO decision. Defer to Step 4.

After calling

get_project_summary

, determine:

```
language
```
: Java or Kotlin
```
bootMajor
```
: 2, 3 or 4 (for jakarta vs javax, Jackson version)

Check if

org.springdoc:springdoc-openapi

is in

presentDeps

-->

hasSpringDoc

Check if

org.hibernate.validator:hibernate-validator

org.springframework.boot:spring-boot-starter-validation

is in

presentDeps

-->

hasValidation

Jackson version detection: Check

presentDeps

for

tools.jackson:jackson-databind

tools.jackson:jackson-core

-->

jacksonMajor = 3

. Otherwise if

com.fasterxml.jackson:jackson-databind

-->

jacksonMajor = 2

. Spring Boot 4.x uses Jackson 3.x (

tools.jackson

package), Spring Boot 2.x/3.x use Jackson 2.x (

com.fasterxml.jackson

package).

jacksonMajor = 3

JsonNodeFqn

tools.jackson.databind.JsonNode

ObjectMapperFqn

tools.jackson.databind.ObjectMapper

jacksonMajor = 2

JsonNodeFqn

com.fasterxml.jackson.databind.JsonNode

ObjectMapperFqn

com.fasterxml.jackson.databind.ObjectMapper

PagedModel detection:
```
PagedModel
```
(
```
org.springframework.data.web.PagedModel
```
) is available in Spring Data 3.2+. If
```
bootMajor >= 3
```
(Spring Boot 3.2+) or
```
bootMajor = 4
```
, use
```
PagedModel
```
wrapper for GET_LIST with Page pagination. Otherwise return
```
Page<Entity>
```
directly.

If multi-module project (multiple modules in

get_project_summary

): Ask which module to use. Then re-call module-specific MCP tools with that module.

Step 2 -- Select entity

By Step 0 you should already know the entity if the user mentioned it. Most common case: the user wrote "create CRUD controller for Product" → entity is

Product

, skip the question, go straight to the fetch below.

Lazy fallback — only when entity is unknown: call

list_all_domain_entities(moduleName)

→

entities

, then ask via

AskUserQuestion

(options = entity names from the list, max 4; if more than 4 entities, use the 4 most likely candidates based on context and add a note that the user can type a different name via "Other").

This is the only place

list_all_domain_entities

should be called. If the user named the entity in their prompt, do NOT call it.

After the entity FQN is known, call

get_entity_details(entityFqn)

to get:

```
IdType
```
-- entity ID field type (e.g.
```
java.lang.Long
```
,
```
java.util.UUID
```
)
```
entityVar
```
-- decapitalized entity name (e.g.
```
product
```
)
```
entityVarPlural
```
-- pluralized decapitalized name (e.g.
```
products
```
)
```
EntityName
```
-- simple class name (e.g.
```
Product
```
)
```
EntityNamePlural
```
-- pluralized simple name (e.g.
```
Products
```
)
Whether entity has validation annotations -->
```
entityHasValidation
```

Step 3 -- Select repository

By Step 0 you may already know the repository if the user mentioned it.

Call

list_entity_repositories(entityFqn)

→

repos

. Then apply the Decision-making principle:

If exactly one repository exists → select it silently (principle 1).
If the user named a specific repository → use it directly, skip the question.
If multiple repositories exist → ask via
```
AskUserQuestion
```
with the options from
```
repos
```
.
If no repository exists → inform the user and suggest creating one manually or using a separate skill.

After selection:

```
repoFieldName
```
-- decapitalized repository class name (e.g.
```
productRepository
```
)
```
RepoFqn
```
-- FQN of repository class

Step 4 -- DTO and customization questions

By Step 0 you may already know the DTO mode if the user mentioned it (e.g. "with DTO", "without DTO", "use entity directly", "map to ProductDto"). If so, skip the question and proceed.

If unknown, ask via

AskUserQuestion

Question	Header	Options (first = recommended)
Use DTO for mapping?	DTO mode	Yes, use DTO (Recommended): select existing or create new via `dto-creator` / No, use entity directly

If DTO selected:

Call

list_entity_dtos(entityFqn)

and

list_entity_mappers(entityFqn)

If existing DTO + mapper found: ask user to select them. Extract:

```
DtoFqn
```
-- DTO class FQN
```
dtoVar
```
-- decapitalized DTO name
```
mapperFieldName
```
-- decapitalized mapper class name
```
toDtoMethodName
```
-- mapper method entity-->DTO (e.g.
```
toDto
```
)
```
toEntityMethodName
```
-- mapper method DTO-->entity (e.g.
```
toEntity
```
)
```
updateMethodName
```
-- mapper method for update (e.g.
```
updateWithNullValues
```
)

Warn: CREATE and PATCH operations require the mapper to have

toEntity

and

updateWithNull

methods.

If no DTO exists for the entity: delegate to

dto-creator

to create one. The

dto-creator

skill will handle DTO generation and will automatically delegate to

mapper-creator

for the mapper (since the DTO is for a REST controller — conversion is inevitable). After both are created, return here and continue with Step 4 path settings.

If DTO exists but no mapper: delegate to

mapper-creator

to create one. After the mapper is created, return here and continue.

Path, pagination & filter settings

Apply the Decision-making principle. These settings almost always have good defaults derivable from context — use principle 2 (one-line confirmation) unless the user explicitly asked for customization:

Will create `{EntityName}Controller` in `{controllerPackage}` at `{basePath}/{entityVarPlural}`, Page pagination, no filter. OK?

The user can answer "ok" / "yes" / silence → accept all defaults; or override specific values → apply only those overrides.

Only fall back to individual questions when the user explicitly asked for fine-grained control ("custom paths", "configure pagination") or when context yields no clear defaults.

If the user selects a filter: ask to select existing filter class. Extract

FilterFqn

and

toSpecificationMethodName

. If the repository does not extend

JpaSpecificationExecutor

, add it (WA-repo-enhance).

Method selection

By Step 0 you may already know which methods the user wants (e.g. "read-only", "only GET and CREATE", "full CRUD"). If so, skip the question.

If unknown, ask via

AskUserQuestion

Question	Header	Options (first = recommended)
Which CRUD methods to generate?	Methods	Full CRUD (Recommended): GET_LIST, GET_ONE, GET_MANY, CREATE, PATCH, PATCH_MANY, DELETE, DELETE_MANY / Standard CRUD: GET_LIST, GET_ONE, CREATE, PATCH, DELETE / Read-only: GET_LIST, GET_ONE / Custom: select individual methods

Store the selected method set as

selectedMethods

. Step 5.3 generates only these methods, skipping the rest.

Step 5 -- Generate code

5.1 Create controller class (WA1)

Read

examples/_skeletons/java.md

examples/_skeletons/kotlin.md

based on

language

Apply variable substitutions:

```
{packageName}
```
--> controllerPackage
```
{className}
```
--> controllerName
```
{requestPath}
```
--> basePath + resourcePath

Use Write tool to create

src/main/{java,kotlin}/{package-path}/{controllerName}.{java,kt}

5.2 Add bean injection (WA2)

Read

examples/_beans/injection/java.md

kotlin.md

Add constructor parameter for repository. If DTO with mapper: also inject mapper bean. Inject

${ObjectMapperFqn}

field (resolved in Step 1:

tools.jackson.databind.ObjectMapper

for Jackson 3.x,

com.fasterxml.jackson.databind.ObjectMapper

for Jackson 2.x).

Use Edit tool to modify the controller class.

5.3 Add CRUD methods (WA3-WA11)

For each method in

selectedMethods

(from Step 4 method selection):

Determine the example file path:

examples/_methods/{method-name}/{language}.md

Read the example file
Select the correct code variant based on:
- DTO mode (no DTO vs with DTO)
- For GET_LIST: pagination (PAGE / WINDOW / none) and filter (with/without)
- For PATCH/PATCH_MANY: ObjectMapper vs ObjectPatcher, and DTO vs no-DTO (4 combinations)
- For CREATE: with/without @Valid
Apply variable substitutions (ONLY variables declared in the Variables section)
FQN handling (CRITICAL): examples contain FQNs (e.g.
```
org.springframework.web.bind.annotation.GetMapping
```
,
```
org.springframework.data.domain.Pageable
```
, entity/DTO/repository FQNs). When writing the final file, you MUST:
1. Replace every FQN in the body with its short name
2. Collect every FQN you shortened and emit a corresponding
```
import
```
  line right after the
```
package
```
  statement, sorted, no duplicates
3. Classes from the same package as the controller must NOT be imported
4. Types from
```
java.lang
```
  must NOT be imported
5. Kotlin: same rules — shorten in the body and add
```
import
```
  lines at the top
Use Edit tool to insert the method into the controller class body

5.4 Add JpaSpecificationExecutor if needed (WA-repo-enhance)

If filter is selected and repository does not already extend

JpaSpecificationExecutor

Read

examples/_beans/repo-enhance/java.md

kotlin.md

. Use Edit tool to add

org.springframework.data.jpa.repository.JpaSpecificationExecutor<{EntityFqn}>

to the repository's extends list.

Step 6 -- Dependencies & properties (automatic)

Read
```
examples/_dependencies/dependencies.md
```
For each artifact NOT in
```
presentDeps
```
:
- Use
```
buildFile
```
  from Step 1
- Edit the build file to add the dependency
Call
```
refresh_build_system_model
```
No properties are written for this skill (controller has no application.properties entries)
Report: "Created controller {controllerName} with CRUD endpoints for {EntityName}. Added dependencies: [list]."

Anti-hallucination checklist

Before writing ANY code, verify:

The code comes from an examples/ file (cite which one)
Only declared variables were substituted
No framework API calls were added "from knowledge"
Import list covers all FQNs shortened in the body (no missing imports, no extras)
Method signatures match the example exactly
No comments or convenience methods were added
FQNs from examples are shortened in the body AND corresponding
```
import
```
lines were added after
```
package
```
(IDE will NOT do this for you)
```
@ParameterObject
```
annotation is only added when
```
hasSpringDoc = true
```
```
@Valid
```
annotation is only added when
```
hasValidation = true
```
AND entity has validation annotations
PATCH and PATCH_MANY methods use ObjectMapper (fallback) or ObjectPatcher depending on project dependencies
getId() in PATCH_MANY matches entity's actual ID accessor
Jackson FQNs use
```
tools.jackson.databind.*
```
for Jackson 3.x (Spring Boot 4.x) and
```
com.fasterxml.jackson.databind.*
```
for Jackson 2.x (Spring Boot 2.x/3.x). NEVER hardcode one or the other — always resolve
```
${JsonNodeFqn}
```
and
```
${ObjectMapperFqn}
```
from Step 1.
GET_LIST with Page pagination uses
```
PagedModel<Entity>
```
wrapper (Spring Data 3.2+ / Boot 3.2+/4.x) or returns
```
Page<Entity>
```
directly (older versions). Select the correct example variant.

crud-rest-controller

NPX Install

Tags

SKILL.md Content

Preflight: Spring MCP

CRUD REST Controller

Defaults

Block 1 — Entity & repository

Block 2 — DTO mode

Block 3 — Controller naming & paths

Block 4 — Pagination & filtering

Auto-detected (no questions)

Decision-making principle — context first, then ask

How to ask — prefer
`AskUserQuestion`

Step 0 -- Conversation context first (REQUIRED, no tool calls)

Step 1 -- Gather minimal project context (automatic, no questions)

Step 2 -- Select entity

Step 3 -- Select repository

Step 4 -- DTO and customization questions

If DTO selected:

Path, pagination & filter settings

Method selection

Step 5 -- Generate code

5.1 Create controller class (WA1)

5.2 Add bean injection (WA2)

5.3 Add CRUD methods (WA3-WA11)

5.4 Add JpaSpecificationExecutor if needed (WA-repo-enhance)

Step 6 -- Dependencies & properties (automatic)

Anti-hallucination checklist