amplicode/spring-skills/kafka-configuration

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, list_application_properties_files); 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."

Kafka Configuration

Wires Spring Boot's Kafka starter through application.properties / application.yml and, optionally, a generated KafkaConfiguration class. Ensures the starter dependency is on the module classpath.

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.

CRITICAL: Read the conversation context BEFORE running Step 1. Half the questions in Steps 2–3 may already be answered.

Two paths (Step 3 picks)

• Path A — `serializerSource = properties` (default). All six spring.kafka.* keys go into the property source: bootstrap-servers, consumer.group-id, producer key/value serializer, consumer key/value deserializer. KafkaAutoConfiguration creates ProducerFactory, ConsumerFactory, KafkaTemplate (bean kafkaTemplate), and kafkaListenerContainerFactory from them.
• Path B — `serializerSource = @Configuration`. Only bootstrap-servers + consumer.group-id go into the property source. A KafkaConfiguration class is generated with four beans: {prefix}ProducerFactory, {prefix}KafkaTemplate, {prefix}ConsumerFactory, kafkaListenerContainerFactory. {prefix} is the lowercased simple name of producerValueType. The listener factory bean name is fixed — autoconfig backs off via @ConditionalOnMissingBean(name = "kafkaListenerContainerFactory"), any other name leaves the autoconfig factory in place and silently routes @KafkaListener to the wrong one.

Defaults

Smart defaults. If the user says "use defaults" / "all defaults" / "minimal configuration" → skip every Always ask = NO question. Only ask the mandatory ones (consumerGroup, serializerSource, and any type the user already mentioned non-default for).

Smart answer recognition. When the user provides a value directly ("for OrderEvent messages", "group orders"), accept it without asking again. Multiple answers in one message → accept all.

Batch questions. Group related questions into one AskUserQuestion call (up to 4 questions). Recommended option first, (Recommended) in its label.

Decision-making — context first, then ask

For every input: try to derive from get_project_summary, list_module_dependencies, list_application_properties_files, prior turns, the user's prompt. Only ask when context yields no clear default.

1. Context unambiguous → decide silently. language, bootVersion, mainPackage, bootstrapServers = localhost:9092, single-file propsFile.
2. Strong signal → one-line confirmation. State decision + alternatives; user can accept silently.
3. No clear default → `AskUserQuestion` with recommended option first.
4. Empty for a critical input → ask plainly. consumerGroup, serializerSource, custom type FQNs.

Step 0 — Conversation context (mental, no tool calls)

Re-read the user's prompt and prior turns; tick off everything already stated:

Tick → skip the corresponding question. Do not announce Step 0.

Step 1 — Gather context (parallel MCP calls + file reads)

After the calls, Read each path in propsFiles and parse any existing spring.kafka.* keys into existingProps.

Multi-module selection. If modules has more than one entry:

1. Run list_module_dependencies + list_application_properties_files for each module in parallel.
2. Score every module: +1 if its deps contain org.springframework.boot:spring-boot-starter-kafka; +1 if its property files contain any spring.kafka.* key.
3. Exactly one module with score ≥ 1 → select it silently as moduleName.
4. Two or more, or all-zero → ask the user which module. Then re-run the module-scoped tools for the chosen one.

Derived:

• bootBranch — boot3 (Boot 3.0/3.1), boot3.2 (3.2/3.3/3.4/3.5), boot4 (≥4.0). Used in Step 5 + Step 6.
• kafkaAlreadyPresent — presentDeps contains org.springframework.boot:spring-boot-starter-kafka. Skip Step 5b if true.
• singlePropsFile — len(propsFiles) == 1. Skip the props-file question in Step 3 if true.
• existingBootstrapServers — value of spring.kafka.bootstrap-servers from existingProps if present, else null. Used silently in Step 2.
• existingConsumerGroup — value of spring.kafka.consumer.group-id from existingProps if present, else null.
• existingKafkaConfig — entries in existingBeans belonging to @Configuration classes that declare any of KafkaTemplate, ProducerFactory, ConsumerFactory, *ListenerContainerFactory beans. Each entry carries the class FQN, source file path, and the bean names already declared. Used in Step 4.

Step 2 — All questions in ONE batch

Ask everything in a single AskUserQuestion call (up to 5 questions). Pre-fill defaults from context, skip already-answered:

1. Producer key type? — options: java.lang.String (Recommended), java.lang.Integer, java.lang.Long, java.util.UUID, java.lang.Void, Custom (specify FQN)
2. Producer value type? — same options
3. Consumer group id? — plain text, mandatory. If existingConsumerGroup is non-null → pre-fill silently.
4. Bootstrap servers? — default localhost:9092. Если existingBootstrapServers is non-null → pre-fill silently.
5. Where to describe serializers? — application.properties (Recommended) (Path A) / @Configuration class (Path B)

Consumer types default to producer types (symmetric). Only ask separately if user indicated asymmetric.

If the user says "use defaults" / "all defaults" — skip type questions, default all four to java.lang.String. Only ask consumerGroup, bootstrapServers, serializerSource.

Step 3 — Class target (Path B only)

If existingKafkaConfig is non-empty, apply Decision principle 2 (one-line confirmation), naming the existing class:

Project already has Kafka beans in {class.fqn}. Add new beans there? (Yes/No)

• Yes → classTarget = existing. Reuse the existing class's packageName, className, and source file path. Step 5 then uses Edit to append beans, not Write to create a new file. Inserted bean names that collide with existing ones get a numeric suffix per Step 5 rules.
• No (or existingKafkaConfig was empty) → classTarget = new:
• className — default KafkaConfiguration; on file collision in {packageName}/{className}.{java|kt} append numeric suffix.
• packageName — default mainPackage; ask only if multiple @Configuration packages exist with no clear winner.

Usually answered silently from context.

Step 4 — Write properties + add dependency

4a. Properties

Always write:

spring.kafka.bootstrap-servers={bootstrapServers}
spring.kafka.consumer.group-id={consumerGroup}

If serializerSource = properties, also append the four (de)serializer keys (FQNs from examples/serializer-mapping.md):

spring.kafka.producer.key-serializer={producerKeySerializer}
spring.kafka.producer.value-serializer={producerValueSerializer}
spring.kafka.consumer.key-deserializer={consumerKeyDeserializer}
spring.kafka.consumer.value-deserializer={consumerValueDeserializer}

If consumerKeyType OR consumerValueType is a POJO, also append:

spring.kafka.consumer.properties[spring.json.trusted.packages]={packages}

{packages} = comma-separated packages of the POJO types on the consumer side.

If consumerKeyType is a POJO, also append:

spring.kafka.consumer.properties[spring.json.key.default.type]={consumerKeyTypeFqn}

If consumerValueType is a POJO, also append:

spring.kafka.consumer.properties[spring.json.value.default.type]={consumerValueTypeFqn}

YAML equivalents are in examples/serializer-mapping.md. Overwrite existing keys; never delete unrelated ones.

4b. Dependency

If kafkaAlreadyPresent = true, skip. Otherwise add org.springframework.boot:spring-boot-starter-kafka to buildFile (same artifact id for Boot 3.x and 4.x), then call refresh_build_system_model.

Step 5 — Generate @Configuration (Path B only)