DEV Community: Markus

Build a Real-Time ISS Tracker with Quarkus, SSE, and Qute

Markus — Mon, 30 Mar 2026 06:08:44 +0000

Most developers look at a small real-time app like this and think it is mainly a frontend exercise. Poll an API, move an icon on a map, done. That works for a demo, but it breaks down fast when you turn it into an actual service. Browsers start polling too often, upstream calls pile up, your server does duplicate work for every tab, and one slow public API drags the whole thing down.

The better mental model is this: the browser is not the source of truth. Your Quarkus service is. It owns the upstream HTTP call, it decides how often data gets refreshed, it caches the latest good result, and it pushes updates to every connected client. That gives you one polling loop, one failure boundary, and one place to harden behavior when the upstream service is slow or unavailable.

This matters even in a small tutorial. Public APIs fail. Network calls stall. Frontends reconnect. SSE clients disappear without warning. If you do not put the right boundaries in place, a harmless little tracker turns into a noisy service that wastes threads, floods logs, and shows stale or broken data when you most need predictable behavior.

In this tutorial, we build the safer version. We use a typed REST client for the Open Notify ISS endpoint, a scheduler that polls every 10 seconds, an application-scoped cache that stores the latest fix, an SSE endpoint that broadcasts updates, and a Qute frontend that renders the marker on a world map.

The ISS has always had a special pull on us at home. The kids and I have been fascinated by NASA, rockets, astronauts, and all the space stuff for as long as I can remember, and the ISS makes that fascination feel real because it is not science fiction or a distant concept, it is up there right now, moving above our heads. It is also a nice reminder that space software lives under hard, real-world constraints where reliability, testability, and long-term maintainability matter more than hype. That is one reason the stable JVM ecosystem keeps showing up in serious environments: NASA’s own history includes Java-based work such as Java Pathfinder at Ames, and even Java Champion James Weaver has been featured in a NASA Goddard colloquium context.

Prerequisites

You need a recent Java and Maven setup, and you should already be comfortable with CDI, REST endpoints, and basic Quarkus project structure. This is not a beginner Java tutorial. It is aimed at Java developers who want a clean end-to-end example that they can understand, run, and extend.

Java 21 installed
Maven 3.9+
Quarkus CLI installed, or comfort with the Maven plugin
Basic understanding of CDI, JAX-RS, and JSON
A working internet connection because the service calls the Open Notify ISS endpoint

Project Setup

Create the project or start from my Github repository:

quarkus create app com.themainthread:iss-tracker \
  --extension='rest-jackson,rest-client-jackson,qute,rest-qute,scheduler,smallrye-health' \
  --no-code
cd iss-tracker

Each extension has a job:

rest-jackson - REST endpoints with Jackson JSON serialization
rest-client-jackson - typed REST client support for the upstream ISS API
qute - server-side templates
rest-qute - smooth integration between Qute and REST resources
scheduler - periodic polling of the ISS position
smallrye-health - /q/health endpoints and readiness checks

Add two extra test dependency are needed. For @InjectMock support in Quarkus tests and RestAssured:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-junit-mockito</artifactId>
    <scope>test</scope>
</dependency>
        <dependency>
            <groupId>io.rest-assured</groupId>
            <artifactId>rest-assured</artifactId>
            <scope>test</scope>
        </dependency>

Create the souce folder structure:

mkdir -p src/main/java/com/themainthread/iss/{client,health,resource,service,util}
mkdir -p src/main/resources/templates/IndexResource
mkdir -p src/test/java/com/themainthread/iss/{resource,service,util}

Implementation

Model the upstream API

The Open Notify ISS endpoint returns a very small JSON payload with latitude and longitude as strings, not doubles. Model that shape exactly first. Do not “improve” the upstream contract in your record. Parse when you need numbers. The API docs show that shape explicitly.

Create src/main/java/com/themainthread/iss/client/IssPosition.java:

package com.themainthread.iss.client;

import com.fasterxml.jackson.annotation.JsonProperty;

public record IssPosition(
        @JsonProperty("latitude") String latitude,
        @JsonProperty("longitude") String longitude) {
    public double latDouble() {
        return Double.parseDouble(latitude);
    }

    public double lonDouble() {
        return Double.parseDouble(longitude);
    }
}

Create src/main/java/com/themainthread/iss/client/IssNowResponse.java:

package com.themainthread.iss.client;

import com.fasterxml.jackson.annotation.JsonProperty;

public record IssNowResponse(
        String message,
        long timestamp,
        @JsonProperty("iss_position") IssPosition issPosition) {
}

Java records are the right fit here. The data is read-only, small, and short-lived. You get immutability and clean logging without boilerplate. The limit is obvious too: records do not replace domain logic. They are just a good boundary for a small external JSON contract.

Create the typed REST client

Now we create the client that talks to Open Notify. Quarkus supports this pattern directly with MicroProfile REST Client, and the Quarkus REST client guide still recommends rest-client-jackson when you want Jackson-based JSON mapping.

Create src/main/java/com/themainthread/iss/client/IssApiClient.java:

package com.themainthread.iss.client;

import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@RegisterRestClient(configKey = "iss-api")
@Path("/iss-now.json")
public interface IssApiClient {

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    IssNowResponse fetchPosition();
}

This client gives you one clear interface for the upstream dependency. That matters later when you test the poller. You can swap in a mock and drive the scheduler logic without touching the network.

The limit is that this interface does not solve resilience on its own. If the upstream hangs, this call hangs until your configured timeout hits. That is why we set tight timeouts in configuration and use SKIP on the scheduler. The interface is clean. The failure behavior still depends on the rest of the system.

Convert latitude and longitude to map pixels

We need server-side projection math so every client gets the same coordinates. That avoids duplicated math in every browser and keeps the frontend simple.

Create src/main/java/com/themainthread/iss/util/MercatorProjection.java:

package com.themainthread.iss.util;

public final class MercatorProjection {

    public static final int MAP_WIDTH = 1280;
    public static final int MAP_HEIGHT = 640;

    private static final double MAX_WEB_MERCATOR_LAT = 85.05112878;

    private MercatorProjection() {
    }

    public static int[] toPixel(double latDeg, double lonDeg) {
        double clampedLat = Math.max(-MAX_WEB_MERCATOR_LAT, Math.min(MAX_WEB_MERCATOR_LAT, latDeg));

        double x = (lonDeg + 180.0) / 360.0 * MAP_WIDTH;

        double latRad = Math.toRadians(clampedLat);
        double mercatorY = Math.log(Math.tan(Math.PI / 4.0 + latRad / 2.0));
        double y = (MAP_HEIGHT / 2.0) - (MAP_WIDTH / (2.0 * Math.PI)) * mercatorY;

        int pixelX = (int) Math.round(Math.max(0, Math.min(MAP_WIDTH - 1, x)));
        int pixelY = (int) Math.round(Math.max(0, Math.min(MAP_HEIGHT - 1, y)));

        return new int[] { pixelX, pixelY };
    }
}

This utility gives you one guarantee: the same (lat, lon) always maps to the same (x, y) on your chosen canvas. That consistency matters because the backend and frontend now agree on a fixed coordinate system.

What it does not guarantee is cartographic correctness for every map projection you might use later. This is tuned for a Mercator-style image and a fixed canvas size. Change the map projection or aspect ratio and you must revisit the math. That is normal. Projection code is always coupled to how you draw the world.

Build the application-scoped cache and stream source

The cache is the center of the service. The scheduler writes to it. The JSON endpoint reads from it. The SSE endpoint streams from it. This is where we stop the browser from becoming the source of truth.

Create src/main/java/com/themainthread/iss/service/IssPositionCache.java:

package com.themainthread.iss.service;

import java.time.Instant;
import java.util.concurrent.atomic.AtomicReference;

import com.themainthread.iss.client.IssNowResponse;
import com.themainthread.iss.util.MercatorProjection;

import io.smallrye.mutiny.Multi;
import io.smallrye.mutiny.operators.multi.processors.BroadcastProcessor;
import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class IssPositionCache {

    public record PositionFix(
            double latitude,
            double longitude,
            int pixelX,
            int pixelY,
            long timestamp,
            Instant updatedAt) {
    }

    private final AtomicReference<PositionFix> latest = new AtomicReference<>(null);
    private final BroadcastProcessor<PositionFix> processor = BroadcastProcessor.create();

    public PositionFix update(IssNowResponse response) {
        double lat = response.issPosition().latDouble();
        double lon = response.issPosition().lonDouble();
        int[] pixels = MercatorProjection.toPixel(lat, lon);

        PositionFix fix = new PositionFix(
                lat,
                lon,
                pixels[0],
                pixels[1],
                response.timestamp(),
                Instant.now());

        latest.set(fix);
        return fix;
    }

    public PositionFix latest() {
        return latest.get();
    }

    public boolean hasData() {
        return latest.get() != null;
    }

    public void broadcast(PositionFix fix) {
        processor.onNext(fix);
    }

    public Multi<PositionFix> stream() {
        return processor;
    }
}

AtomicReference is enough here because each update replaces the whole snapshot. Readers never see half-written state. They either see the old fix, the new fix, or null before the first successful poll. That is exactly what you want.

The BroadcastProcessor gives you hot-stream behavior. Connected clients get new events. Clients that connect later do not get a backlog. That is the right behavior for a live tracker. The limit is that this is not a durable event log. If you want history, you need storage. A processor is for fan-out, not persistence.

Add the scheduler that polls Open Notify

Now we connect the REST client to the cache.

Create src/main/java/com/themainthread/iss/service/IssPoller.java:

package com.themainthread.iss.service;

import org.eclipse.microprofile.rest.client.inject.RestClient;
import org.jboss.logging.Logger;

import com.themainthread.iss.client.IssApiClient;
import com.themainthread.iss.service.IssPositionCache.PositionFix;

import io.quarkus.scheduler.Scheduled;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;

@ApplicationScoped
public class IssPoller {

    private static final Logger LOG = Logger.getLogger(IssPoller.class);

    @Inject
    @RestClient
    IssApiClient client;

    @Inject
    IssPositionCache cache;

    @Scheduled(every = "10s", concurrentExecution = Scheduled.ConcurrentExecution.SKIP)
    void poll() {
        try {
            var response = client.fetchPosition();

            if (!"success".equalsIgnoreCase(response.message())) {
                LOG.warnf("Unexpected upstream response message: %s", response.message());
                return;
            }

            PositionFix fix = cache.update(response);
            cache.broadcast(fix);

            LOG.debugf("ISS fix updated - lat=%.4f lon=%.4f x=%d y=%d",
                    fix.latitude(), fix.longitude(), fix.pixelX(), fix.pixelY());

        } catch (Exception e) {
            LOG.errorf("Failed to fetch ISS position: %s", e.getMessage());
        }
    }
}

This method does one thing well. It fetches one fresh upstream value, updates one shared snapshot, and broadcasts one event. That simplicity matters in production. Scheduled code becomes fragile fast when it tries to do too much.

The critical setting here is concurrentExecution = SKIP. Without it, a slow upstream call can overlap with the next scheduled run. That is how tiny polling jobs slowly turn into thread waste. With SKIP, you lose one tick when the upstream is slow. That is fine for a public ISS feed updating every 10 seconds. Missing one poll is cheaper than building a queue of blocked work.

Expose the JSON and SSE endpoints

Quarkus REST supports SSE with @Produces(MediaType.SERVER_SENT_EVENTS) and @RestStreamElementType(MediaType.APPLICATION_JSON).

Create src/main/java/com/themainthread/iss/resource/IssResource.java:

package com.themainthread.iss.resource;

import org.jboss.resteasy.reactive.RestStreamElementType;

import com.themainthread.iss.service.IssPositionCache;
import com.themainthread.iss.service.IssPositionCache.PositionFix;

import io.smallrye.mutiny.Multi;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/api/iss")
public class IssResource {

    @Inject
    IssPositionCache cache;

    @GET
    @Path("/position")
    @Produces(MediaType.APPLICATION_JSON)
    public PositionFix position() {
        return cache.latest();
    }

    @GET
    @Path("/stream")
    @Produces(MediaType.SERVER_SENT_EVENTS)
    @RestStreamElementType(MediaType.APPLICATION_JSON)
    public Multi<PositionFix> stream() {
        return cache.stream();
    }
}

The JSON endpoint is useful for the initial page load. The SSE endpoint is useful after that. This split keeps the frontend responsive even if it opens before the first live event arrives.

One small but important point: returning null from position() maps cleanly to 204 No Content. That means you do not have to invent a fake placeholder payload before the first successful poll. The client can handle “no data yet” honestly.

Serve the Qute frontend

Qute’s @CheckedTemplate support gives you build-time verification that your template exists. That is exactly the kind of failure you want at build time, not after deployment. The Qute guide still documents this pattern. (quarkus.io)

Create src/main/java/com/themainthread/iss/resource/IndexResource.java:

package com.themainthread.iss.resource;

import io.quarkus.qute.CheckedTemplate;
import io.quarkus.qute.TemplateInstance;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/")
public class IndexResource {

    @CheckedTemplate
    public static class Templates {
        public static native TemplateInstance index();
    }

    @GET
    @Produces(MediaType.TEXT_HTML)
    public TemplateInstance index() {
        return Templates.index();
    }
}

Create src/main/resources/templates/IndexResource/index.html:

(I’ve omitted the styles here, go check out the Github repository!)

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>ISS Tracker</title>
    <style>

    </style>
</head>

<body>

    <h1>ISS Real-Time Tracker</h1>
    <div id="status">Connecting to live feed...</div>

    <div id="map-container">
        <img id="world-map"
            src="https://upload.wikimedia.org/wikipedia/commons/thumb/8/80/World_map_-_low_resolution.svg/1280px-World_map_-_low_resolution.svg.png"
            alt="World map">
        <div id="iss-marker"></div>
    </div>

    <div id="coords">
        Lat: <span id="lat">-</span>

        Lon: <span id="lon">-</span>

        Updated: <span id="updated">-</span>
    </div>

    <footer>
        Data from <a href="https://open-notify.org/" target="_blank">Open Notify</a>
    </footer>

    <script>
        const MAP_WIDTH = 1280;
        const MAP_HEIGHT = 640;

        const marker = document.getElementById("iss-marker");
        const status = document.getElementById("status");
        const latEl = document.getElementById("lat");
        const lonEl = document.getElementById("lon");
        const updatedEl = document.getElementById("updated");

        function placeMarker(pixelX, pixelY) {
            const leftPercent = (pixelX / MAP_WIDTH) * 100;
            const topPercent = (pixelY / MAP_HEIGHT) * 100;
            marker.style.left = leftPercent + "%";
            marker.style.top = topPercent + "%";
        }

        function renderFix(fix) {
            placeMarker(fix.pixelX, fix.pixelY);
            latEl.textContent = fix.latitude.toFixed(4) + "°";
            lonEl.textContent = fix.longitude.toFixed(4) + "°";
            updatedEl.textContent = new Date(fix.updatedAt).toLocaleTimeString();
        }

        fetch("/api/iss/position")
            .then(response => response.status === 204 ? null : response.json())
            .then(fix => {
                if (fix) {
                    renderFix(fix);
                }
            });

        const source = new EventSource("/api/iss/stream");

        source.onopen = () => {
            status.textContent = "Live - updates every 10 seconds";
            status.style.color = "#3fd6a5";
        };

        source.onmessage = (event) => {
            const fix = JSON.parse(event.data);
            renderFix(fix);
        };

        source.onerror = () => {
            status.textContent = "Connection lost - reconnecting...";
            status.style.color = "#ffb366";
        };
    </script>

</body>

</html>

This frontend stays small because the server already did the hard work. The browser only places a marker and updates a few text fields. That is the right split for a live app like this.

It also handles reconnects cleanly because EventSource reconnects automatically. That does not make SSE free. A large number of open clients still means a large number of open HTTP connections. For a small tracker that is fine. For public-scale fan-out, you would think harder about limits, proxies, and backpressure.

Add a readiness check

Health endpoints are only useful if they reflect real readiness. For this service, “ready” means we have fetched at least one good ISS position.

Create src/main/java/com/themainthread/iss/health/IssDataReadinessCheck.java:

package com.themainthread.iss.health;

import org.eclipse.microprofile.health.HealthCheck;
import org.eclipse.microprofile.health.HealthCheckResponse;
import org.eclipse.microprofile.health.Readiness;

import com.themainthread.iss.service.IssPositionCache;
import com.themainthread.iss.service.IssPositionCache.PositionFix;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;

@Readiness
@ApplicationScoped
public class IssDataReadinessCheck implements HealthCheck {

    @Inject
    IssPositionCache cache;

    @Override
    public HealthCheckResponse call() {
        if (!cache.hasData()) {
            return HealthCheckResponse.named("iss-data")
                    .down()
                    .withData("reason", "No successful poll yet")
                    .build();
        }

        PositionFix fix = cache.latest();

        return HealthCheckResponse.named("iss-data")
                .up()
                .withData("latitude", String.valueOf(fix.latitude()))
                .withData("longitude", String.valueOf(fix.longitude()))
                .withData("updatedAt", fix.updatedAt().toString())
                .build();
    }
}

This check gives you an honest signal for deployment platforms. A process that has started but never fetched data is alive, but it is not ready. That distinction matters once you put this behind a load balancer.

Configuration

Configure the application in src/main/resources/application.properties:

quarkus.application.name=iss-tracker
quarkus.http.port=8080

quarkus.rest-client.iss-api.url=http://api.open-notify.org
quarkus.rest-client.iss-api.connect-timeout=3000
quarkus.rest-client.iss-api.read-timeout=5000

quarkus.log.level=INFO
quarkus.log.category."com.themainthread.iss".level=DEBUG

%dev.quarkus.scheduler.start-mode=forced
%dev.quarkus.log.category."com.themainthread.iss".level=DEBUG

quarkus.rest-client.iss-api.url points the typed REST client at the public ISS endpoint documented by Open Notify. (open-notify.org)

connect-timeout=3000 prevents a dead TCP connection attempt from hanging too long. When the upstream is down, three seconds is enough to fail fast and keep your scheduler thread moving.

read-timeout=5000 prevents the actual response read from blocking forever. This is the difference between a recoverable slow upstream and a scheduler job that quietly stalls.

%dev.quarkus.scheduler.start-mode=forced makes development behavior obvious when you are iterating locally. You do not want to wonder whether the scheduler started after a hot reload.

Production Hardening

What happens when the upstream API is slow

The upstream service is free and public. Treat it like a dependency you do not control. That means timeouts are mandatory, and overlapping polls are a bug, not a feature.

With the current setup, one slow call blocks only one scheduled execution. The next tick gets skipped because of Scheduled.ConcurrentExecution.SKIP. That is intentional. You keep the last good fix, you avoid overlapping network calls, and your service stays stable.

Without SKIP, slow upstream calls stack up. That is how small scheduled jobs turn into thread leaks under bad network conditions. The tracker does not need every possible update. It needs predictable behavior.

SSE fan-out is cheap until it is not

SSE is simpler than WebSockets for one-way live updates. That is why it fits this tutorial well. The browser API is tiny, the server code is small, and reconnection behavior is built in.

But every client still holds a long-lived HTTP connection. A few browsers are nothing. Thousands of browsers change the operational picture. Reverse proxy timeouts, max connections, and memory overhead start to matter. For a public internet app, you would put this behind a proxy configured for long-lived streams and think about per-IP connection limits.

Stale data is better than broken data

When a poll fails, we keep the last successful position in memory. This is the correct failure mode for a tracker. Users keep seeing the last known good fix, not a blank map or a server error.

This does not mean the data is fresh. It means the service is honest about its last successful state. If freshness matters more than availability, expose an age field and let the frontend show “stale” after a threshold. For this tutorial, readiness tells you whether data exists at all, and the timestamps tell you how current it is.

No auth does not mean no abuse surface

This service has no login and no database. That does not make it safe by default. The abuse surface is the number of open SSE connections and the number of HTTP requests you let through.

If you publish this beyond your laptop, add rate limiting. Also think about response caching on /api/iss/position, and consider authentication if the stream is not meant to be public. Real-time endpoints are attractive to scrapers because they are cheap to consume and easy to reconnect.

Verification

Run the application

Start dev mode:

quarkus dev

Open the app http://localhost:8080

[

](https://substackcdn.com/image/fetch/$s_!YdS3!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F36651a16-d805-4702-b7d5-6c21d0f8374d_3024x1724.png)

You should see a world map, an ISS marker, and coordinates that update every 10 seconds. I have also added a small tracking feature to the Github repository. So make sure to check that out!

Verify the JSON endpoint

Call the snapshot endpoint:

curl -i http://localhost:8080/api/iss/position

Expected behavior after the first successful poll:

HTTP/1.1 200 OK
Content-Type: application/json

Expected payload shape:

{
  "latitude": 12.3456,
  "longitude": -78.9012,
  "pixelX": 360,
  "pixelY": 280,
  "timestamp": 1716835200,
  "updatedAt": "2026-03-14T10:15:30.123Z"
}

Before the first successful poll, you should get:

HTTP/1.1 204 No Content

That verifies the cache boundary is working correctly.

Verify the readiness endpoint

Call readiness:

curl http://localhost:8080/q/health/ready

Expected output after a successful poll:

{
    "status": "UP",
    "checks": [
        {
            "name": "iss-data",
            "status": "UP",
            "data": {
                "latitude": "-24.2744",
                "longitude": "-86.3863",
                "updatedAt": "2026-03-14T10:56:08.176814Z"
            }
        }
    ]
}

This proves the app is not just running. It has real upstream data.

Test the projection math

Create src/test/java/com/themainthread/iss/util/MercatorProjectionTest.java:

package com.themainthread.iss.util;

import static org.junit.jupiter.api.Assertions.assertTrue;

import org.junit.jupiter.api.Test;

class MercatorProjectionTest {

    @Test
    void nullIslandMapsNearCenter() {
        int[] pixels = MercatorProjection.toPixel(0.0, 0.0);

        assertTrue(Math.abs(pixels[0] - 640) <= 2);
        assertTrue(Math.abs(pixels[1] - 320) <= 2);
    }

    @Test
    void easternDatelineMapsNearRightEdge() {
        int[] pixels = MercatorProjection.toPixel(0.0, 179.9);
        assertTrue(pixels[0] > 1260);
    }

    @Test
    void westernDatelineMapsNearLeftEdge() {
        int[] pixels = MercatorProjection.toPixel(0.0, -179.9);
        assertTrue(pixels[0] < 20);
    }
}

This test proves the one piece of pure math in the service. If the projection is wrong, the frontend marker is wrong even when every other part works.

Test the REST resource

Create src/test/java/com/themainthread/iss/resource/IssResourceTest.java:

package com.themainthread.iss.resource;

import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.is;
import static org.mockito.Mockito.when;

import java.time.Instant;

import org.junit.jupiter.api.Test;

import com.themainthread.iss.service.IssPositionCache;
import com.themainthread.iss.service.IssPositionCache.PositionFix;

import io.quarkus.test.InjectMock;
import io.quarkus.test.junit.QuarkusTest;

@QuarkusTest
class IssResourceTest {

    @InjectMock
    IssPositionCache cache;

    @Test
    void returnsCurrentFix() {
        PositionFix fix = new PositionFix(
                51.5074,
                -0.1278,
                640,
                250,
                1716835200L,
                Instant.parse("2026-03-14T10:15:30Z"));

        when(cache.latest()).thenReturn(fix);

        given()
                .when().get("/api/iss/position")
                .then()
                .statusCode(200)
                .body("latitude", is(51.5074f))
                .body("longitude", is(-0.1278f))
                .body("pixelX", is(640))
                .body("pixelY", is(250));
    }

    @Test
    void returns204WhenNoFixExists() {
        when(cache.latest()).thenReturn(null);

        given()
                .when().get("/api/iss/position")
                .then()
                .statusCode(204);
    }
}

This test proves the HTTP contract. It does not care about the scheduler or the external API. That is good. Resource tests should stay focused.

Test the scheduler

Create src/test/java/com/themainthread/iss/service/IssPollerTest.java:

package com.themainthread.iss.service;

import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.mockito.Mockito.when;

import org.eclipse.microprofile.rest.client.inject.RestClient;
import org.junit.jupiter.api.Test;

import com.themainthread.iss.client.IssApiClient;
import com.themainthread.iss.client.IssNowResponse;
import com.themainthread.iss.client.IssPosition;

import io.quarkus.test.InjectMock;
import io.quarkus.test.junit.QuarkusTest;
import jakarta.inject.Inject;

@QuarkusTest
class IssPollerTest {

    @InjectMock
    @RestClient
    IssApiClient apiClient;

    @Inject
    IssPoller poller;

    @Inject
    IssPositionCache cache;

    @Test
    void pollPopulatesCacheOnSuccess() {
        IssNowResponse response = new IssNowResponse(
                "success",
                1716835200L,
                new IssPosition("51.5074", "-0.1278"));

        when(apiClient.fetchPosition()).thenReturn(response);

        poller.poll();

        assertTrue(cache.hasData());

        var fix = cache.latest();
        assertEquals(51.5074, fix.latitude());
        assertEquals(-0.1278, fix.longitude());
    }

    @Test
    void pollSwallowsNetworkErrors() {
        when(apiClient.fetchPosition()).thenThrow(new RuntimeException("timeout"));

        assertDoesNotThrow(() -> poller.poll());
    }
}

This test proves the behavior that matters most in production: one bad network call does not crash the polling loop.

Conclusion

We built a Quarkus service that treats real-time tracking as a backend responsibility, not a browser trick. The REST client isolates the upstream dependency, the scheduler controls polling, the application-scoped cache holds the last good state, the SSE endpoint fans out updates efficiently, and the Qute frontend stays simple because the server already did the hard work. More importantly, the service fails in the right way: it skips overlapping polls, keeps stale-but-valid data when the upstream breaks, and reports readiness only after it has something real to serve.

This is a small app, but the architecture is the same one you use when a toy demo has to survive the real world.

Subscribe now

Quarkus MCP Testing for Java Developers: McpAssured + IBM Bob

Markus — Sun, 29 Mar 2026 07:08:40 +0000

In the first part of this series, we built a real Quarkus MCP server and connected it to IBM Bob. The server exposed tools, resources, resource templates, and prompts over Streamable HTTP. We also added one smoke test that posted raw JSON-RPC to /mcp and checked that tools/list returned our tool names.

That test proved something important, but only one thing. It proved the server starts, accepts MCP traffic, and survives the initialization handshake. That is useful. It is not enough.

Most developers test agent-facing servers the same way they test REST endpoints. They verify the endpoint is reachable, maybe they assert a status code, and then they move on. That mental model breaks fast with MCP. Your caller is not a deterministic frontend or a handwritten CLI. Your caller is an agent that reads your tool descriptions, reasons from your JSON Schema, calls tools in runtime-generated sequences, and then keeps building on whatever came back.

This changes the failure mode. A REST bug usually fails close to the request that caused it. An MCP bug often fails one or two steps later. saveNote accepts a blank key, Bob thinks the note was saved, then a later resources/read returns “not found,” and now you are debugging the wrong part of the workflow. The original bug is gone from the surface.

So this tutorial is about contract testing, not just protocol smoke testing. We replace the hand-rolled JSON-RPC test with McpAssured, the Quarkiverse testing library built for MCP servers. The Quarkus MCP Server docs describe McpAssured as the integration testing utility for MCP servers, with fluent assertions, transport support for SSE, Streamable HTTP, and WebSocket, batch testing, and raw message inspection. The same docs also show the dedicated quarkus-mcp-server-test dependency and the newConnectedStreamableClient() entry point we’ll use here.

Prerequisites

This tutorial builds directly on the Dev Toolkit MCP server from Part 1. You need the existing project because we are testing the tools, resources, resource templates, and prompts we already built there.

Java 21
Maven 3.9+ (Gradle users can run the same tests with the equivalent test tasks; this tutorial shows Maven commands.)
The completed dev-toolkit-mcp project from Part 1. “Completed” means you have finished all Part 1 steps and have a running MCP server with the old smoke test in place. The complete Part 1 code is available at the GitHub repository; use the same Quarkus and quarkus-mcp-server versions as in that project so the test client and server protocols align.
Basic Quarkus testing knowledge

Use the same Java package as your Part 1 MCP server (e.g. com.example.mcp) for the test classes below, or adjust the package in the snippets to match your project. If your Part 1 server exposes a different number of tools or prompts, update the counts and names in the tests (e.g. the assertEquals(5, page.size()) for tools and assertEquals(2, page.size()) for prompts).

Project Setup

We are not creating a new application here. Copy the dev-toolkit-mcp project from Part 1 to a new dev-toolkit-mcp-test. You can find the new repository with the changed tests on my Github.

Add the MCP test dependency to your pom.xml. Make sure it aligns with the quarkus-mcp-server version:

        <dependency>
            <groupId>io.quarkiverse.mcp</groupId>
            <artifactId>quarkus-mcp-server-test</artifactId>
            <version>1.10.3</version>
            <scope>test</scope>
        </dependency>

McpAssured supports SSE, Streamable HTTP, and WebSocket clients, and for a Streamable HTTP server like the docs show McpAssured.newConnectedStreamableClient() as the right client to create.

That is all we need for setup. No extra port configuration, no manual handshake code, no raw HTTP session management.

Before we continue, delete or archive the raw JSON-RPC smoke test from Part 1 if you still have it. Remove the test class that posts raw JSON-RPC to /mcp (e.g. a class named like RawMcpSmokeTest or McpSmokeTest in src/test/java/...). Keep it in Git history if you want. Do not keep it as your main verification strategy. It is too low level and too shallow for a server that an agent will drive.

Implementation

Replace raw JSON-RPC plumbing with a real MCP test client

The old smoke test did everything by hand. It built JSON request bodies as strings. It posted them to /mcp. It extracted the Mcp-Session-Id header manually. It string-matched the response body to check whether our tools were there.

That works, but only in the same way that curl | grep works. It proves bytes crossed the wire. It does not prove the MCP contract is right. It also makes tests harder to read, harder to maintain, and harder to debug when they fail.

Here is the first replacement test. Create src/test/java/com/example/mcp/DevToolkitMcpTest.java:

package com.example.mcp;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNotNull;

import org.junit.jupiter.api.Test;

import io.quarkiverse.mcp.server.test.McpAssured;
import io.quarkus.test.junit.QuarkusTest;

@QuarkusTest
class DevToolkitMcpTest {

    @Test
    void allToolsShouldBeRegistered() {
        var client = McpAssured.newConnectedStreamableClient();
        try {
            client.when()
                    .toolsList(page -> {
                        assertEquals(5, page.size());
                        assertNotNull(page.findByName("toUpperSnakeCase"));
                        assertNotNull(page.findByName("countOccurrences"));
                        assertNotNull(page.findByName("base64Transform"));
                        assertNotNull(page.findByName("truncate"));
                        assertNotNull(page.findByName("saveNote"));
                    })
                    .thenAssertResults();
        } finally {
            client.disconnect();
        }
    }
}

This is a better test for a few reasons. First, it reads in MCP terms, not HTTP terms. We ask for toolsList, not for a POST request with a manually encoded JSON body. Second, failures are named. If saveNote disappears, the assertion fails at findByName("saveNote"). Third, this test is already running through an MCP-aware client that performs the session lifecycle correctly. The Quarkiverse docs explicitly call out that McpAssured speaks the transport-specific protocol and provides a fluent, typed assertion model for integration tests.

What this guarantees is simple: the tool registry is present and visible to a real MCP client. What it does not guarantee is that the schemas are correct or that the tools behave correctly. So we keep going.

Test the `toUpperSnakeCase` tool like Bob would use it

A tool that looks trivial is often where agent bugs start. The model sees the description, chooses the tool, and passes user content into it. That means weird whitespace, empty strings, and malformed input are normal. They are not edge cases in agent workflows. They are daily traffic.

Add this test to the same class:

 @Test
    void toUpperSnakeCaseShouldHandleNormalAndEdgeInput() {
        var client = McpAssured.newConnectedStreamableClient();
        try {
            client.when()
                    .toolsCall("toUpperSnakeCase",
                            java.util.Map.of("input", "my variable name"),
                            r -> {
                                assertFalse(r.isError());
                                assertEquals("MY_VARIABLE_NAME",
                                        r.content().get(0).asText().text());
                            })
                    .toolsCall("toUpperSnakeCase",
                            java.util.Map.of("input", " spaces everywhere "),
                            r -> {
                                assertFalse(r.isError());
                                assertEquals("SPACES_EVERYWHERE",
                                        r.content().get(0).asText().text());
                            })
                    .toolsCall("toUpperSnakeCase",
                            java.util.Map.of("input", ""),
                            r -> {
                                assertFalse(r.isError());
                                assertEquals("", r.content().get(0).asText().text());
                            })
                    .thenAssertResults();
        } finally {
            client.disconnect();
        }
    }

And update the imports:

import static org.junit.jupiter.api.Assertions.assertFalse;

This test is small, but it makes behavior explicit. Empty input is not a crash. It is not a null. It is not a tool error. It returns an empty string. That is a contract now.

This matters because Bob will reason from the returned text. If the tool suddenly returned null, or threw an exception that became a protocol error, the next step in the chain changes. The tool result is not just output. It is part of the model’s working context.

Test `base64Transform` on both the success path and error path

This is where MCP testing stops looking like REST testing.

In MCP, tool failures and protocol failures are not the same thing. The official MCP specification says tool execution errors belong inside the successful JSON-RPC result object with isError: true, while protocol errors are reserved for issues like malformed requests, unsupported operations, or unknown tools. The spec also explains why: clients can expose tool execution errors to the model so it can self-correct. Protocol errors are much less useful for recovery. (Model Context Protocol)

That is not a small detail. It is the difference between “the server is broken” and “the tool understood the call but rejected the input.”

Add this test:

 @Test
    void base64TransformShouldSucceedAndFailGracefully() {
        var client = McpAssured.newConnectedStreamableClient();
        try {
            client.when()
                    .toolsCall("base64Transform",
                            java.util.Map.of("input", "hello world", "operation", "encode"),
                            r -> {
                                assertFalse(r.isError());
                                assertTrue(r.content().get(0).asText().text()
                                        .contains("aGVsbG8gd29ybGQ="));
                            })
                    .toolsCall("base64Transform",
                            java.util.Map.of("input", "aGVsbG8gd29ybGQ=", "operation", "decode"),
                            r -> {
                                assertFalse(r.isError());
                                assertTrue(r.content().get(0).asText().text()
                                        .contains("hello world"));
                            })
                    .toolsCall("base64Transform",
                            java.util.Map.of("input", "hello", "operation", "explode"),
                            r -> {
                                assertTrue(r.isError());
                                assertTrue(r.content().get(0).asText().text()
                                        .contains("Unknown operation"));
                            })
                    .thenAssertResults();
        } finally {
            client.disconnect();
        }
    }

And add the missing import:

import static org.junit.jupiter.api.Assertions.assertTrue;

What this guarantees is that the tool can complete valid work and report invalid business input without breaking the session. What it does not guarantee is that your descriptions and schemas are good enough for the model to choose the tool correctly. We test that next.

Verify that the model-facing schema is actually useful

A tool that exists but has a vague description is not production-ready. A tool that has a missing or misleading schema is worse. The model decides whether a tool is relevant based on the published contract, not based on your Java implementation.

The Quarkus MCP Server docs make this explicit in a different way: tools are discovered and validated at build time, and JSON Schema generation plus parameter validation are automatic parts of the server model. That means the published tool definition is not incidental. It is the interface.

Add this test:

 @Test
    void toolSchemasShouldBeCompleteAndDescriptive() {
        var client = McpAssured.newConnectedStreamableClient();
        try {
            client.when()
                    .toolsList(page -> {
                        var truncateTool = page.findByName("truncate");
                        assertNotNull(truncateTool);
                        assertNotNull(truncateTool.description());
                        assertFalse(truncateTool.description().isBlank());
                        assertNotNull(truncateTool.inputSchema());

                        var countTool = page.findByName("countOccurrences");
                        assertNotNull(countTool);
                        assertNotNull(countTool.description());
                        assertFalse(countTool.description().isBlank());
                        assertNotNull(countTool.inputSchema());
                    })
                    .toolsCall("truncate",
                            java.util.Map.of("input", "a".repeat(200), "maxLength", 10),
                            r -> {
                                assertFalse(r.isError());
                                String result = r.content().get(0).asText().text();
                                assertTrue(result.length() <= 10);
                                assertTrue(result.endsWith("..."));
                            })
                    .toolsCall("countOccurrences",
                            java.util.Map.of("text", "banana", "substring", "an"),
                            r -> {
                                assertFalse(r.isError());
                                assertEquals("2", r.content().get(0).asText().text());
                            })
                    .thenAssertResults();
        } finally {
            client.disconnect();
        }
    }

This test does two different jobs. It checks behavior, and it checks discoverability. That combination matters. A correct implementation with a bad schema still produces bad agent behavior. Bob cannot choose the right tool consistently if the contract it sees is vague.

Test the `saveNote` stateful round-trip

This is the most important test in the suite.

A state-changing tool is where agent-driven systems stop being stateless request/response code and become workflows. Bob saves something under a key, then reads it back later using a resource template. If the write path and the read path are tested in isolation, you can still miss the real bug: the loop is broken.

Add this test:

  @Test
    void saveNoteThenReadItBackViaResourceTemplate() {
        var client = McpAssured.newConnectedStreamableClient();
        try {
            client.when()
                    .toolsCall("saveNote",
                            java.util.Map.of("key", "testkey", "content", "# Hello from the test"),
                            r -> {
                                assertFalse(r.isError());
                                assertTrue(r.content().get(0).asText().text()
                                        .contains("testkey"));
                                assertTrue(r.content().get(1).asText().text()
                                        .contains("dev-toolkit://notes/testkey"));
                            })
                    .resourcesRead("dev-toolkit://notes/testkey",
                            r -> {
                                var contents = r.contents().get(0).asText();
                                assertEquals("# Hello from the test", contents.text());
                                assertEquals("dev-toolkit://notes/testkey", contents.uri());
                            })
                    .thenAssertResults();
        } finally {
            client.disconnect();
        }
    }

This test is important because it matches the real agent path. The assertions lock in the current contract (e.g. URI shape and response text); if you change the server’s contract, update these tests deliberately. Bob calls the tool, gets back a URI, then reads that URI. If one side changes its format, or if the write succeeds but the resource template resolves incorrectly, the failure shows up here.

Now add the rejection case:

  @Test
    void saveNoteShouldRejectBlankKey() {
        var client = McpAssured.newConnectedStreamableClient();
        try {
            client.when()
                    .toolsCall("saveNote",
                            java.util.Map.of("key", "", "content", "this should not be saved"),
                            r -> {
                                assertTrue(r.isError());
                                assertTrue(r.content().get(0).asText().text()
                                        .contains("Key must not be blank"));
                            })
                    .thenAssertResults();
        } finally {
            client.disconnect();
        }
    }

This is the kind of bug that causes ghost failures later. If blank keys are accepted, the write side looks fine and the read side looks broken. In reality, the contract was broken at the first step.

Test resources and resource templates as first-class contracts

Resources are not just static documentation for Bob. They are part of the context supply chain. The model reads them to decide what is available and what to do next.

Test the server-info resource first:

  @Test
    void serverInfoShouldListAvailableNoteKeys() {
        var client = McpAssured.newConnectedStreamableClient();
        try {
            client.when()
                    .resourcesList(page -> {
                        assertNotNull(page.findByUri("dev-toolkit://server-info"));
                        assertNotNull(page.findByUri("dev-toolkit://java-string-cheatsheet"));
                    })
                    .resourcesRead("dev-toolkit://server-info",
                            r -> {
                                String content = r.contents().get(0).asText().text();
                                assertTrue(content.contains("Online"));
                                assertTrue(content.contains("conventions"));
                                assertTrue(content.contains("architecture"));
                            })
                    .thenAssertResults();
        } finally {
            client.disconnect();
        }
    }

Now test the missing-note case:

    @Test
    void readingMissingNoteShouldReturnHelpfulContent() {
        var client = McpAssured.newConnectedStreamableClient();
        try {
            client.when()
                    .resourcesRead("dev-toolkit://notes/doesnotexist",
                            r -> {
                                String content = r.contents().get(0).asText().text();
                                assertTrue(content.contains("Note Not Found"));
                                assertTrue(content.contains("doesnotexist"));
                            })
                    .thenAssertResults();
        } finally {
            client.disconnect();
        }
    }

And test the resource template itself:

    @Test
    void resourceTemplateShouldBeRegisteredAndAccessible() {
        var client = McpAssured.newConnectedStreamableClient();
        try {
            client.when()
                    .resourcesTemplatesList(page -> {
                        var template = page.findByUriTemplate("dev-toolkit://notes/{key}");
                        assertNotNull(template);
                        assertEquals("Project Note", template.name());
                    })
                    .resourcesRead("dev-toolkit://notes/conventions",
                            r -> assertTrue(r.contents().get(0).asText().text()
                                    .contains("camelCase")))
                    .thenAssertResults();
        } finally {
            client.disconnect();
        }
    }

The important part here is not just that the template exists. The important part is that the resource URI Bob receives from the tool is a URI Bob can actually follow later.

Test prompts like user-facing contracts

Prompts are easy to ignore because they are not “execution logic.” That is a mistake. Bob surfaces these prompts to users, asks for the declared arguments, and then sends the rendered content to the model. If the arguments are wrong or missing, the prompt is broken at the UX layer.

Add this test:

 @Test
    void promptsShouldBeRegisteredWithCorrectArguments() {
        var client = McpAssured.newConnectedStreamableClient();
        try {
            client.when()
                    .promptsList(page -> {
                        assertEquals(2, page.size());

                        var explainError = page.findByName("explain-error");
                        assertNotNull(explainError);
                        assertNotNull(explainError.description());
                        assertTrue(explainError.arguments().stream()
                                .anyMatch(a -> a.name().equals("error")));

                        var codeReview = page.findByName("code-review");
                        assertNotNull(codeReview);
                        assertNotNull(codeReview.description());
                        assertTrue(codeReview.arguments().stream()
                                .anyMatch(a -> a.name().equals("code")));
                    })
                    .promptsGet("explain-error",
                            java.util.Map.of("error", "NullPointerException at line 42"),
                            r -> {
                                assertEquals(1, r.messages().size());
                                String text = r.messages().get(0).content().asText().text();
                                assertTrue(text.contains("NullPointerException"));
                            })
                    .thenAssertResults();
        } finally {
            client.disconnect();
        }
    }

The Quarkiverse testing guide shows prompt list and prompt get testing as first-class McpAssured operations, just like tools and resources. That is the right mental model. Prompts are part of the contract too. (docs.quarkiverse.io)

Add one full regression test as your CI gate

Unit-like integration tests are good. A full smoke pass is still useful, but now it should smoke the whole contract, not just the transport.

Create a second test class: src/test/java/com/example/mcp/DevToolkitMcpRegressionTest.java

package com.example.mcp;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertTrue;

import java.util.Map;

import org.junit.jupiter.api.Test;

import io.quarkiverse.mcp.server.test.McpAssured;
import io.quarkus.test.junit.QuarkusTest;

@QuarkusTest
class DevToolkitMcpRegressionTest {

    @Test
    void fullContractSmokePass() {
        var client = McpAssured.newConnectedStreamableClient();
        try {
            client.when()
                    .toolsList(page -> {
                        assertEquals(5, page.size());
                        assertNotNull(page.findByName("toUpperSnakeCase"));
                        assertNotNull(page.findByName("saveNote"));
                    })
                    .resourcesList(page -> {
                        assertNotNull(page.findByUri("dev-toolkit://server-info"));
                    })
                    .resourcesTemplatesList(page -> {
                        assertNotNull(page.findByUriTemplate("dev-toolkit://notes/{key}"));
                    })
                    .promptsList(page -> {
                        assertEquals(2, page.size());
                        assertNotNull(page.findByName("code-review"));
                    })
                    .toolsCall("toUpperSnakeCase",
                            Map.of("input", "hello world"),
                            r -> assertEquals("HELLO_WORLD",
                                    r.content().get(0).asText().text()))
                    .toolsCall("countOccurrences",
                            Map.of("text", "abcabc", "substring", "abc"),
                            r -> assertEquals("2",
                                    r.content().get(0).asText().text()))
                    .toolsCall("saveNote",
                            Map.of("key", "smoketest", "content", "# Smoke"),
                            r -> assertFalse(r.isError()))
                    .thenAssertResults();
            client.when()
                    .resourcesRead("dev-toolkit://notes/smoketest",
                            r -> assertTrue(r.contents().get(0).asText().text()
                                    .contains("# Smoke")))
                    .thenAssertResults();
        } finally {
            client.disconnect();
        }
    }
}

The McpAssured docs describe this style explicitly as batch testing: chain multiple MCP operations, then validate them together with thenAssertResults().

This is the test that belongs in CI. If it fails, your agent-facing contract is not healthy enough to ship.

Capture raw MCP traffic when the bug only appears in an agent loop

This is the test you will care about at 2am.

One of the most useful McpAssured features is raw message inspection. The Quarkiverse testing guide documents snapshot() for capturing requests and responses after a test interaction. It also shows that you can inspect the raw JSON-RPC method names and result payloads directly. (docs.quarkiverse.io)

Add this test method to DevToolkitMcpTest:

    @Test
    void inspectRawJsonRpcTraffic() {
        var client = McpAssured.newConnectedStreamableClient();
        try {
            client.when()
                    .toolsCall("base64Transform",
                            java.util.Map.of("input", "debug me", "operation", "encode"),
                            r -> {
                            })
                    .thenAssertResults();

            var snapshot = client.snapshot();
            if (!snapshot.requests().isEmpty() && !snapshot.responses().isEmpty()) {
                System.out.println("→ Request:");
                System.out.println(snapshot.requests().get(0).encodePrettily());
                System.out.println("← Response:");
                System.out.println(snapshot.responses().get(0).encodePrettily());
            }
        } finally {
            client.disconnect();
        }
    }

This is not a business assertion test. This is a debugging test. You can exclude it from CI (e.g. with @Tag("debug") and a profile that skips that tag) if you want to avoid console output in automated runs. When Bob behaves strangely and you cannot tell whether the problem is your Java code, your schema, or the model’s follow-up reasoning, snapshot output gives you the exact MCP exchange your server produced during the test run.

That is much better than guessing from logs.

Configuration

For this tutorial, the nice part is that we do not need special McpAssured configuration. The default setup with @QuarkusTest and newConnectedStreamableClient() is enough for the existing Streamable HTTP transport.

If you want extra visibility during development, enable traffic logging in your Quarkus application while running the server manually. The Quarkus MCP Server development tools guide documents traffic logging and Dev UI support for HTTP-based MCP servers. That is useful when you want to compare what Dev UI shows, what the server logs, and what your tests capture through snapshots. (docs.quarkiverse.io)

Look at src/test/resources/application.properties and uncomment the below line:

quarkus.log.category."io.quarkiverse.mcp".level=DEBUG

This setting is optional. It helps when a test fails and you want to correlate server-side activity with the client-side snapshot.

The important part is not fancy test config. The important part is that your tests stay close to the published MCP contract.

Production Hardening

What happens under agent-driven load

A REST API often gets tested one request at a time. An MCP server rarely gets used that way in real life. An agent lists tools, reads resources, calls a write tool, reads a resource template, maybe triggers a prompt, and then repeats the cycle. Your contract is stateful even if each transport request is stateless.

That means you need to test chains, not just calls. The saveNote round-trip is a simple example, but the pattern scales. If one MCP feature produces identifiers, URIs, or content that another feature consumes, write at least one regression test that traverses the whole path.

Concurrency and correctness are still your problem

McpAssured handles session lifecycle, message exchange, and typed assertions. It does not make your server safe under concurrent writes. If two agent sessions save the same note key at the same time, your correctness guarantee depends on your implementation, not on the test library.

Right now, your ConcurrentHashMap note store is fine for a tutorial server. It is not a persistence model. It gives thread-safe map operations, but it does not give you auditing, quotas, ownership, TTL cleanup, or rollback. This is exactly why Part 3 should add authentication, per-user write limits, and stronger validation before you let autonomous tools write state.

Tool errors must be designed, not improvised

The MCP spec is clear here. Tool execution problems belong in tool results with isError: true, while protocol errors are for invalid requests, unknown tools, and server-level failures. (Model Context Protocol)

In practice, this means you should decide deliberately which failures the model can recover from. Invalid operation names, blank keys, or business-rule violations are usually tool errors. Missing methods, malformed JSON-RPC messages, or unsupported protocol features are protocol errors. If you blur that line, the agent loses its ability to self-correct.

Tests lock in the contract

Your tests encode the current server contract: error message text (e.g. “Key must not be blank”), URI shapes, and response structure. If you change the server’s behavior or wording, update the tests deliberately so they remain an accurate specification. Where you call r.content().get(0) or r.contents().get(0), the examples assume at least one element; if a tool or resource can return empty content, assert non-empty (e.g. assertFalse(r.content().isEmpty())) before get(0) so failures stay clear.

Schema quality is part of production quality

This is easy to forget because schemas are generated for you. But generated does not mean automatically good. The model still depends on your descriptions, argument names, and semantic clarity.

A tool called truncate with a useless description like “does string stuff” will technically work. It will still be a bad production tool because the agent has weak guidance about when to use it and what maxLength really means. Test presence, then inspect descriptions, then fix wording when the contract is vague.

Raw snapshots are your replay mechanism

When a Bob session goes wrong, reproduction is usually the hard part. The raw snapshot gives you a path back to determinism. The Quarkiverse testing docs explicitly support request and response inspection through snapshot(), and that turns “the agent did something weird” into a concrete JSON-RPC exchange you can replay in a test.

That is the kind of tool that saves real time when production behavior gets confusing.

Verification

If tests fail with connection or startup errors, ensure the Quarkus application starts and the MCP endpoint is available (e.g. no port conflicts, and the test runs with @QuarkusTest as shown).

Start by running the full test suite:

mvn test

Expected result:

[INFO] Tests run: 12, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESS

Your exact number of tests can differ if you add more methods, but the build should be green.

Now run only the regression test:

mvn -Dtest=DevToolkitMcpRegressionTest test

Expected result:

[INFO] Running com.example.mcp.DevToolkitMcpRegressionTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

This verifies your CI gate. It checks that the MCP server exposes the expected tools, resources, templates, and prompts, and that a stateful write/read loop still works.

Finally, connect the running server to Bob exactly like you did in Part 1 and try these manual scenarios (optional; requires IBM Bob and the same connection setup as in Part 1—URL, etc.):

- Ask Bob to save a note under key "release-plan"
- Ask Bob to read the same note back
- Ask Bob to explain a NullPointerException through the explain-error prompt
- Ask Bob to base64 encode "hello bob"

What you are verifying here is not just that the server responds. You are verifying that Bob can traverse the same contracts your tests now cover: discover tools, call tools, follow resource URIs, and render prompts.

Conclusion

We replaced a raw JSON-RPC smoke test with contract-focused MCP integration tests that match how IBM Bob actually uses your Quarkus server. The new suite verifies registration, schemas, tool behavior, stateful write/read flows, prompts, and raw request/response traffic. That closes the gap between “the server starts” and “the agent can safely build on the result.” The Quarkus MCP Server docs and McpAssured guide make this testing model first-class, and that is exactly the right direction for production MCP work.

The complete code for the server series is available in the GitHub repository.

Subscribe now

Mock External APIs in Quarkus with WireMock: A Hands-On Guide

Markus — Sat, 28 Mar 2026 07:08:29 +0000

Most developers think mocking an external HTTP API is just a testing convenience. They want to avoid calling a real sandbox, so they plug in a fake response and move on. That works for the first demo, but it fails the moment your integration starts depending on behavior, not just shape.

Real carrier APIs do not fail in clean ways. They time out. They drift from their own documentation. They return half-useful payloads. They give you state transitions that happen over time, not one static JSON blob. When your service depends on an API you do not control, the real problem is not “how do I fake one response?” The real problem is “how do I keep development, testing, and failure handling stable when the downstream system is unstable?”

This is where WireMock becomes much more than a stub server. It gives you a real HTTP boundary that your Quarkus application calls through the same REST client it will use in production. That matters because mocks inside your JVM do not test serialization, status handling, retries, request paths, headers, or timeouts. They test a method call. Production breaks at the HTTP boundary.

In this tutorial we build a small shipment tracking feature end to end. Our Quarkus endpoint calls a fictional carrier API through a MicroProfile REST Client. WireMock stands in for that carrier in both dev mode and tests. We start with static JSON stubs, then move to programmatic stubs, stateful scenarios, response templating, fault injection, and request verification.

The result is a setup you can trust when the real carrier is down, when access is delayed, or when you need to test production failure paths on your own machine. That is the part that matters at 2am. Your code still behaves predictably even when the dependency does not.

Prerequisites

You need a current Quarkus setup, basic REST knowledge, and a few minutes to build the example.

Java 21 installed
Maven or the Quarkus CLI
Basic understanding of REST endpoints and JSON
Basic understanding of Quarkus REST Client

Project Setup

Create the project or start directly from my Github repository:

quarkus create app dev.mainthread:quarkus-wiremock-demo \
  --extension='rest,rest-jackson,rest-client-jackson' \
  --no-code
cd quarkus-wiremock-demo

We keep the project small on purpose. The only thing we need is a REST endpoint, Jackson for JSON, and a REST client to call the external carrier API.

The extensions do the following:

rest - exposes our shipment endpoint
rest-jackson - serializes and deserializes JSON
rest-client-jackson - creates the HTTP client that talks to the carrier API

Make sure to add the Quarkus-WireMock extensions and rest-assured to your pom.xml:

<dependency>
    <groupId>io.quarkiverse.wiremock</groupId>
    <artifactId>quarkus-wiremock</artifactId>
    <version>1.5.3</version>
    <scope>provided</scope>
</dependency>

    <dependency>
        <groupId>io.quarkiverse.wiremock</groupId>
        <artifactId>quarkus-wiremock-test</artifactId>
        <version>1.5.3</version>
        <scope>test</scope>
    </dependency>

   <dependency>
            <groupId>io.rest-assured</groupId>
            <artifactId>rest-assured</artifactId>
            <scope>test</scope>
        </dependency>

Now configure the application in src/main/resources/application.properties:

quarkus.rest-client.carrier-api.url=http://localhost:${quarkus.wiremock.devservices.port}
quarkus.wiremock.devservices.global-response-templating=true

Here is what each setting does:

quarkus.rest-client.carrier-api.url - points the REST client at the WireMock server started by the Dev Service
quarkus.wiremock.devservices.global-response-templating=true - enables helpers like {{now}} in all stub responses

The first property removes hardcoded ports from your project. That prevents a common local-dev failure where the mock server and your REST client drift out of sync.

The second property keeps time-based tests from turning stale. Hardcoded timestamps look harmless until six months pass and a test that once checked a future delivery date is now checking a date in the past. Response templating fixes that by generating values at request time.

Implementation

We are building a simple flow:

[

](https://substackcdn.com/image/fetch/$s_!qDZG!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2Fc2c8810a-128e-456e-84a4-ff99b3fde63e_1240x2730.png)

Create the domain model

We need a small internal model first. This is the shape our own API returns. It is important to keep this separate from the carrier DTOs. External APIs change for their own reasons. Your internal model should not leak every naming choice and odd field shape from a vendor payload.

Create src/main/java/dev/mainthread/ShipmentStatusCode.java:

package dev.mainthread;

public enum ShipmentStatusCode {
    LABEL_CREATED,
    IN_TRANSIT,
    OUT_FOR_DELIVERY,
    DELIVERED,
    EXCEPTION
}

Create src/main/java/dev/mainthread/ShipmentStatus.java:

package dev.mainthread;

import java.time.Instant;

public record ShipmentStatus(
        String trackingNumber,
        ShipmentStatusCode status,
        String lastLocation,
        Instant estimatedDelivery,
        String message) {
}

This gives us one important guarantee: every consumer of our REST endpoint sees a stable domain response. It does not guarantee correctness of the downstream payload. If the carrier sends garbage, our service still needs to map or reject it safely. The type alone does not save you.

Create the carrier DTOs

Now we mirror the payload that the fictional carrier returns. These classes represent the integration boundary, not your business model.

Create src/main/java/dev/mainthread/dto/CarrierEvent.java:

package dev.mainthread.dto;

import com.fasterxml.jackson.annotation.JsonProperty;

public record CarrierEvent(
        String timestamp,
        String location,
        @JsonProperty("event_code") String eventCode,
        String description) {
}

Create src/main/java/dev/mainthread/dto/CarrierTrackingResponse.java:

package dev.mainthread.dto;

import java.util.List;

import com.fasterxml.jackson.annotation.JsonProperty;

public record CarrierTrackingResponse(
        @JsonProperty("tracking_number") String trackingNumber,
        @JsonProperty("status_code") String statusCode,
        @JsonProperty("status_message") String statusMessage,
        @JsonProperty("events") List<CarrierEvent> events,
        @JsonProperty("estimated_delivery") String estimatedDelivery) {
}

This separation looks boring. It is also the part that keeps external drift from spreading through your codebase. If the carrier renames status_code or starts sending an extra field, you fix one boundary. You do not rewrite your whole application.

Create the REST client

We need the actual HTTP client that talks to the carrier. This is the component that WireMock will exercise in dev mode and tests.

Create src/main/java/dev/mainthread/CarrierClient.java:

package dev.mainthread;

import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;

import dev.mainthread.dto.CarrierTrackingResponse;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@RegisterRestClient(configKey = "carrier-api")
@Path("/v1/track")
public interface CarrierClient {

    @GET
    @Path("/{trackingNumber}")
    @Produces(MediaType.APPLICATION_JSON)
    CarrierTrackingResponse track(@PathParam("trackingNumber") String trackingNumber);
}

The important part is configKey = "carrier-api". That binds the client to quarkus.rest-client.carrier-api.url.

At first glance this is just a normal REST client. The difference is how we test it. We are not going to mock this interface in unit tests. We are going to let it make real HTTP calls to WireMock. That means path mapping, payload parsing, status handling, and request verification all stay visible.

Create the service layer

Now we need a service that maps the carrier response to our own domain model.

Create src/main/java/dev/mainthread/ShipmentService.java:

package dev.mainthread;

import java.time.Instant;

import org.eclipse.microprofile.rest.client.inject.RestClient;

import dev.mainthread.dto.CarrierTrackingResponse;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import jakarta.ws.rs.WebApplicationException;

@ApplicationScoped
public class ShipmentService {

    @Inject
    @RestClient
    CarrierClient carrierClient;

    public ShipmentStatus getStatus(String trackingNumber) {
        CarrierTrackingResponse response;
        try {
            response = carrierClient.track(trackingNumber);
        } catch (WebApplicationException e) {
            if (e.getResponse() != null && e.getResponse().getStatus() == 503) {
                return unavailable(trackingNumber);
            }
            throw e;
        }

        return new ShipmentStatus(
                response.trackingNumber(),
                mapStatusCode(response.statusCode()),
                extractLastLocation(response),
                parseDeliveryEstimate(response.estimatedDelivery()),
                response.statusMessage());
    }

    private ShipmentStatus unavailable(String trackingNumber) {
        return new ShipmentStatus(
                trackingNumber,
                ShipmentStatusCode.EXCEPTION,
                "unknown",
                null,
                "Carrier tracking temporarily unavailable");
    }

    private ShipmentStatusCode mapStatusCode(String carrierCode) {
        return switch (carrierCode) {
            case "LC" -> ShipmentStatusCode.LABEL_CREATED;
            case "IT" -> ShipmentStatusCode.IN_TRANSIT;
            case "OD" -> ShipmentStatusCode.OUT_FOR_DELIVERY;
            case "DL" -> ShipmentStatusCode.DELIVERED;
            default -> ShipmentStatusCode.EXCEPTION;
        };
    }

    private String extractLastLocation(CarrierTrackingResponse response) {
        if (response.events() == null || response.events().isEmpty()) {
            return "unknown";
        }
        return response.events().get(0).location();
    }

    private Instant parseDeliveryEstimate(String raw) {
        if (raw == null || raw.isBlank()) {
            return null;
        }
        try {
            return Instant.parse(raw);
        } catch (Exception e) {
            return null;
        }
    }
}

This is where the real value sits. The service gives you a stable internal contract and a fallback for a known external failure. It does not protect you from every network problem. A 503 becomes a graceful degraded response. A connection reset still blows up. That is intentional for now. Good tutorials should leave visible edges where production hardening belongs.

Notice one design choice here: we translate carrier status codes immediately. We do not pass "IT" or "DL" through the rest of our application. That keeps vendor-specific semantics contained. It also means that when the carrier invents a new code, your system will degrade to EXCEPTION until you handle it explicitly. That is safer than pretending unknown values are valid.

Create the REST endpoint

Now expose the shipment status through your own API.

Create src/main/java/dev/mainthread/ShipmentResource.java:

package dev.mainthread;

import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/shipments")
@Produces(MediaType.APPLICATION_JSON)
public class ShipmentResource {

    @Inject
    ShipmentService shipmentService;

    @GET
    @Path("/{trackingNumber}")
    public ShipmentStatus track(@PathParam("trackingNumber") String trackingNumber) {
        return shipmentService.getStatus(trackingNumber);
    }
}

This endpoint is thin on purpose. The resource handles HTTP. The service handles mapping and fallback logic. That separation matters because the tests we write later are really protecting the service behavior through the full HTTP stack.

Static JSON Stubs

Before we write any test code, let’s make the application work in dev mode against a mocked carrier API. This is the fastest feedback loop.

Create src/test/resources/mappings/track-in-transit.json:

{
    "request": {
        "method": "GET",
        "urlPathPattern": "/v1/track/SWIFT[0-9]+"
    },
    "response": {
        "status": 200,
        "bodyFileName": "track-in-transit-body.json",
        "headers": {
            "Content-Type": "application/json"
        }
    }
}

Create src/test/resources/__files/track-in-transit-body.json:

{
    "tracking_number": "SWIFT12345678",
    "status_code": "IT",
    "status_message": "Package is in transit",
    "estimated_delivery": "2026-03-20T18:00:00Z",
    "events": [
        {
            "timestamp": "2026-03-18T14:22:00Z",
            "location": "Memphis, TN",
            "event_code": "ARR",
            "description": "Arrived at sorting facility"
        },
        {
            "timestamp": "2026-03-17T09:10:00Z",
            "location": "Atlanta, GA",
            "event_code": "DEP",
            "description": "Departed origin facility"
        }
    ]
}

The official Quarkus WireMock docs state that JSON stub files in mappings and __files are loaded from the root configured by quarkus.wiremock.devservices.files-mapping, which defaults to src/test/resources.

Start the application:

./mvnw quarkus:dev

Now call your own API:

curl http://localhost:8080/shipments/SWIFT12345678 | jq

Expected output:

{
  "trackingNumber": "SWIFT12345678",
  "status": "IN_TRANSIT",
  "lastLocation": "Memphis, TN",
  "estimatedDelivery": "2026-03-20T18:00:00Z",
  "message": "Package is in transit"
}

This is already useful. Your Quarkus application is running against a mock server over real HTTP. No external credentials. No flaky sandbox. No hidden mock inside the JVM.

Programmatic Stubs with `@ConnectWireMock`

Static stubs are good for common development flows. Tests often need tighter control. That is where programmatic registration helps.

Create src/test/java/dev/mainthread/ShipmentResourceTest.java:

package dev.mainthread;

import static com.github.tomakehurst.wiremock.client.WireMock.aResponse;
import static com.github.tomakehurst.wiremock.client.WireMock.equalTo;
import static com.github.tomakehurst.wiremock.client.WireMock.get;
import static com.github.tomakehurst.wiremock.client.WireMock.urlPathEqualTo;
import static io.restassured.RestAssured.given;

import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;

import com.github.tomakehurst.wiremock.client.WireMock;

import io.quarkiverse.wiremock.devservice.ConnectWireMock;
import io.quarkus.test.junit.QuarkusTest;

@QuarkusTest
@ConnectWireMock
class ShipmentResourceTest {

    WireMock wiremock;

    @BeforeEach
    void resetStubs() {
        wiremock.resetMappings();
    }

    @Test
    void returnsInTransitStatus() {
        wiremock.register(
                get(urlPathEqualTo("/v1/track/SWIFT99887766"))
                        .willReturn(aResponse()
                                .withStatus(200)
                                .withHeader("Content-Type", "application/json")
                                .withBody("""
                                            {
                                              "tracking_number": "SWIFT99887766",
                                              "status_code": "IT",
                                              "status_message": "Package is in transit",
                                              "estimated_delivery": "2026-03-20T18:00:00Z",
                                              "events": [
                                                {
                                                  "timestamp": "2026-03-18T14:22:00Z",
                                                  "location": "Memphis, TN",
                                                  "event_code": "ARR",
                                                  "description": "Arrived at sorting facility"
                                                }
                                              ]
                                            }
                                        """)));

        given()
                .when().get("/shipments/SWIFT99887766")
                .then()
                .statusCode(200)
                .body("status", equalTo("IN_TRANSIT"))
                .body("lastLocation", equalTo("Memphis, TN"))
                .body("message", equalTo("Package is in transit"));
    }
}

@ConnectWireMock injects a WireMock client directly into the test class.

The important thing here is the reset in @BeforeEach. Without that, stubs leak between tests. That kind of pollution gives you the worst test failures: random ones. One test passes alone and fails in a suite. Always reset mappings or requests between tests unless you have a very good reason not to.

Also notice what we are testing. We are not asserting on the REST client directly. We call /shipments/... and let the whole stack run. That proves routing, outbound HTTP, JSON mapping, and our internal status mapping in one shot.

WireMock Scenarios - Simulating State Changes

This is where WireMock becomes much more useful than a plain mock object. Real APIs are not always stateless from your point of view. Shipment tracking is a good example. You call the same endpoint several times and the result changes over time.

Add this test to ShipmentResourceTest:

@Test
    void shipmentProgressesThroughLifecycle() {
        final String trackingNumber = "SWIFT55443322";
        final String path = "/v1/track/" + trackingNumber;
        final String scenario = "shipment-lifecycle";

        wiremock.register(
                get(urlPathEqualTo(path))
                        .inScenario(scenario)
                        .whenScenarioStateIs("Started")
                        .willReturn(aResponse()
                                .withStatus(200)
                                .withHeader("Content-Type", "application/json")
                                .withBody(carrierResponse(
                                        trackingNumber,
                                        "LC",
                                        "Label created, awaiting pickup",
                                        "unknown")))
                        .willSetStateTo("IN_TRANSIT"));

        wiremock.register(
                get(urlPathEqualTo(path))
                        .inScenario(scenario)
                        .whenScenarioStateIs("IN_TRANSIT")
                        .willReturn(aResponse()
                                .withStatus(200)
                                .withHeader("Content-Type", "application/json")
                                .withBody(carrierResponse(
                                        trackingNumber,
                                        "IT",
                                        "Package is in transit",
                                        "Chicago, IL")))
                        .willSetStateTo("OUT_FOR_DELIVERY"));

        wiremock.register(
                get(urlPathEqualTo(path))
                        .inScenario(scenario)
                        .whenScenarioStateIs("OUT_FOR_DELIVERY")
                        .willReturn(aResponse()
                                .withStatus(200)
                                .withHeader("Content-Type", "application/json")
                                .withBody(carrierResponse(
                                        trackingNumber,
                                        "OD",
                                        "Out for delivery",
                                        "Chicago, IL")))
                        .willSetStateTo("DELIVERED"));

        wiremock.register(
                get(urlPathEqualTo(path))
                        .inScenario(scenario)
                        .whenScenarioStateIs("DELIVERED")
                        .willReturn(aResponse()
                                .withStatus(200)
                                .withHeader("Content-Type", "application/json")
                                .withBody(carrierResponse(
                                        trackingNumber,
                                        "DL",
                                        "Package delivered",
                                        "Chicago, IL"))));

        given()
                .when().get("/shipments/" + trackingNumber)
                .then()
                .statusCode(200)
                .body("status", equalTo("LABEL_CREATED"));

        given()
                .when().get("/shipments/" + trackingNumber)
                .then()
                .statusCode(200)
                .body("status", equalTo("IN_TRANSIT"))
                .body("lastLocation", equalTo("Chicago, IL"));

        given()
                .when().get("/shipments/" + trackingNumber)
                .then()
                .statusCode(200)
                .body("status", equalTo("OUT_FOR_DELIVERY"));

        given()
                .when().get("/shipments/" + trackingNumber)
                .then()
                .statusCode(200)
                .body("status", equalTo("DELIVERED"));
    }

    private String carrierResponse(String trackingNumber, String code, String message, String location) {
        return """
                {
                  "tracking_number": "%s",
                  "status_code": "%s",
                  "status_message": "%s",
                  "estimated_delivery": "2026-03-20T18:00:00Z",
                  "events": [
                    {
                      "timestamp": "2026-03-18T14:22:00Z",
                      "location": "%s",
                      "event_code": "EVT",
                      "description": "%s"
                    }
                  ]
                }
                """.formatted(trackingNumber, code, message, location, message);
    }

This test proves something important that a single happy-path stub cannot prove. It shows that your service maps status codes correctly across a full business lifecycle. It also shows the limit of this approach: scenario state lives inside WireMock, not your application. That means it is excellent for integration behavior, but it is not a substitute for real event ordering or persistence logic in your own code.

Response Templating

Hardcoded timestamps age badly. A good mock should stay useful next month, not just today.

Because we enabled global response templating in application.properties, we can generate time-based values dynamically.

Add this test:

 @Test
    void estimatedDeliveryIsInTheFuture() {
        wiremock.register(
                get(urlPathEqualTo("/v1/track/SWIFT11223344"))
                        .willReturn(aResponse()
                                .withStatus(200)
                                .withHeader("Content-Type", "application/json")
                                .withBody(
                                        """
                                                    {
                                                      "tracking_number": "SWIFT11223344",
                                                      "status_code": "IT",
                                                      "status_message": "In transit",
                                                      "estimated_delivery": "{{now offset='3 days' format='yyyy-MM-dd\\'T\\'HH:mm:ss\\'Z\\''}}",
                                                      "events": []
                                                    }
                                                """)));

        given()
                .when().get("/shipments/SWIFT11223344")
                .then()
                .statusCode(200)
                .body("estimatedDelivery", equalTo(org.hamcrest.Matchers.notNullValue().toString()));
    }

That assertion is not great. Let’s fix it so it actually checks the field exists without becoming brittle:

    @Test
    void estimatedDeliveryIsPresent() {
        wiremock.register(
                get(urlPathEqualTo("/v1/track/SWIFT11223344"))
                        .willReturn(aResponse()
                                .withStatus(200)
                                .withHeader("Content-Type", "application/json")
                                .withBody(
                                        """
                                                    {
                                                      "tracking_number": "SWIFT11223344",
                                                      "status_code": "IT",
                                                      "status_message": "In transit",
                                                      "estimated_delivery": "{{now offset='3 days' format='yyyy-MM-dd\\'T\\'HH:mm:ss\\'Z\\''}}",
                                                      "events": []
                                                    }
                                                """)));

        given()
                .when().get("/shipments/SWIFT11223344")
                .then()
                .statusCode(200)
                .body("estimatedDelivery", org.hamcrest.Matchers.notNullValue());
    }

This is much better. The test proves the date is generated and parsed. It does not overfit on a specific timestamp string.

Response templating is useful for more than time. You can also echo parts of the incoming request into the response. That is a simple way to make one stub handle many tracking numbers without copy-pasting dozens of files.

For example:

{
  "tracking_number": "{{request.pathSegments.[2]}}",
  "status_code": "IT",
  "status_message": "In transit",
  "estimated_delivery": "{{now offset='2 days' format='yyyy-MM-dd\\'T\\'HH:mm:ss\\'Z\\''}}",
  "events": []
}

The value of response templating is not that it looks clever. The value is that it keeps your stubs alive as the calendar moves and your test data grows.

Fault Injection

This is the section most teams skip. It is also where the real operational value starts.

A service that only handles success is not production-ready. You need to know what happens when the carrier is down, when it responds slowly, or when the TCP connection breaks halfway through the call.

Handle `503 Service Unavailable`

Add this test:

    @Test
    void returnsExceptionStatusWhenCarrierIsDown() {
        wiremock.register(
                get(urlPathEqualTo("/v1/track/SWIFT00000001"))
                        .willReturn(aResponse()
                                .withStatus(503)
                                .withHeader("Content-Type", "application/json")
                                .withBody("""
                                            {"error":"Service temporarily unavailable"}
                                        """)));

        given()
                .when().get("/shipments/SWIFT00000001")
                .then()
                .statusCode(200)
                .body("status", equalTo("EXCEPTION"))
                .body("message", equalTo("Carrier tracking temporarily unavailable"));
    }

This test proves that your service degrades gracefully for one known downstream condition. That is good. It is not complete resilience. A graceful fallback for 503 does not help with timeouts or connection resets. Those are different failure modes and they need their own strategy.

Simulate a broken connection

Now add a network fault:

  @Test
    void handlesConnectionReset() {
        wiremock.register(
                get(urlPathEqualTo("/v1/track/SWIFT00000002"))
                        .willReturn(aResponse()
                                .withFault(com.github.tomakehurst.wiremock.http.Fault.CONNECTION_RESET_BY_PEER)));

        given()
                .when().get("/shipments/SWIFT00000002")
                .then()
                .statusCode(500);
    }

This test documents a real gap. Right now the service knows how to map an HTTP 503, but it does not know how to recover from a low-level network failure. That is not a problem with WireMock. That is exactly the behavior your code has today. The value of the test is that the gap is now visible and repeatable.

WireMock can simulate several network-level failures, including:

CONNECTION_RESET_BY_PEER
EMPTY_RESPONSE
MALFORMED_RESPONSE_CHUNK
RANDOM_DATA_THEN_CLOSE

Those are the kinds of failures that are painful to trigger against a real third-party API and trivial to reproduce with a good stub server.

Simulate latency

You should also test slow downstream responses.

   @Test
    void slowCarrierResponseCanTriggerTimeouts() {
        wiremock.register(
                get(urlPathEqualTo("/v1/track/SWIFT00000003"))
                        .willReturn(aResponse()
                                .withStatus(200)
                                .withHeader("Content-Type", "application/json")
                                .withFixedDelay(2000)
                                .withBody("""
                                            {
                                              "tracking_number": "SWIFT00000003",
                                              "status_code": "IT",
                                              "status_message": "In transit",
                                              "estimated_delivery": "2026-03-20T18:00:00Z",
                                              "events": []
                                            }
                                        """)));

        given()
                .when().get("/shipments/SWIFT00000003")
                .then()
                .statusCode(200);
    }

Right now this still returns 200 because we have not configured a client timeout. That is fine. The test gives us a base line. Once you add a read timeout, this same setup becomes your timeout test.

Production Hardening

What happens under load

Mocking with WireMock does not remove pressure from your own service. Your REST client still allocates connections, parses JSON, and handles errors on request threads. If the carrier is slow and your timeout is too generous, your application ties up resources waiting on something it cannot control.

Fast failure is usually better than patient failure for external dependencies. If the carrier is down, you want a short timeout and a clear fallback. You do not want every request thread waiting 30 seconds because the remote side stopped responding.

Add this to src/main/resources/application.properties if you want a stricter production-style setup:

quarkus.rest-client.carrier-api.connect-timeout=1000
quarkus.rest-client.carrier-api.read-timeout=1000

Now a delayed mock becomes a deterministic timeout test instead of a slow success path.

Concurrency and ordering

WireMock scenarios are useful, but they are not a source of truth for concurrency guarantees. They simulate sequential state transitions in the mock server. They do not prove that your own application handles concurrent reads, repeated polls, or duplicate events correctly.

For example, two callers can still ask for the same tracking number at the same time. Your service will make two outbound calls unless you add caching or request collapsing. Mocking alone does not fix chatty client behavior.

That is why request verification matters. It tells you how many times your code actually hit the downstream API. Once you add caching later, your verification test should change with it.

Failure boundaries

Right now our service handles one failure cleanly and exposes another one as 500. That is honest. It is also the signal to add proper fault tolerance.

In a real production service, I would usually add the quarkus-smallrye-fault-tolerance extension and then apply retry, timeout, or circuit breaker behavior at the service boundary. The goal is not to “hide” all failures. The goal is to fail in a controlled way and stop a broken dependency from dragging your service down with it.

Security and abuse cases

Mock servers are easy to trust too much. A mock that always returns perfect JSON trains your code to expect polite input. Real external systems do not behave that way forever.

At minimum, think about these cases:

invalid or unexpected status codes
missing events
malformed timestamps
very large payloads
repeated requests for the same tracking number

Our ShipmentService already degrades unknown status codes to EXCEPTION and treats bad timestamps as null. That is a good start. It is not enough for every abuse case, but it prevents obvious parsing failures from crashing the whole mapping layer.

Request Verification

One of the best things about WireMock is that it records what your client actually sent. That lets you verify behavior, not just response content.

Add this test:

   @Test
    void callsCarrierApiExactlyTwiceWithoutCaching() {
        wiremock.register(
                get(urlPathEqualTo("/v1/track/SWIFT77665544"))
                        .willReturn(aResponse()
                                .withStatus(200)
                                .withHeader("Content-Type", "application/json")
                                .withBody(carrierResponse(
                                        "SWIFT77665544",
                                        "DL",
                                        "Delivered",
                                        "Austin, TX"))));

        given().when().get("/shipments/SWIFT77665544").then().statusCode(200);
        given().when().get("/shipments/SWIFT77665544").then().statusCode(200);

        wiremock.verifyThat(
                exactly(2),
                getRequestedFor(urlPathEqualTo("/v1/track/SWIFT77665544")));
    }

This proves that there is no caching in place yet. That is useful. It tells you the current operational cost of the endpoint.

Later, if you add a cache in ShipmentService, this test should change to exactly(1). That is a good example of a test that evolves with design, not against it.

You can also assert that a request never happened:

wiremock.verifyThat(
    never(),
    getRequestedFor(urlPathEqualTo("/v1/track/SWIFT99999999"))
);

That becomes useful once you add circuit breakers or short-circuit logic.

Verification

Run the tests

Run the full test suite:

./mvnw test

Expected result:

[INFO] Tests run: 7, Failures: 0, Errors: 0, Skipped: 0

This verifies that your Quarkus endpoint, service layer, REST client, and WireMock stubs work together in test mode.

Inspect the WireMock admin endpoint

The WireMock admin API is useful when you want to see registered stubs and recorded requests.

You can go to the Quarkus Dev UI to find the wiremock mappings. If you click on the tile mappings url you can see them directly:

http://localhost:<wiremock-port>/__admin/mappings

This is useful for debugging stub registration problems, path mismatches, or unexpected requests from your client.

Subscribe now

Conclusion

We built a Quarkus shipment tracking feature that talks to a mocked carrier API over real HTTP, not a fake in-memory method call. Static stubs gave us fast local development. Programmatic stubs let us target exact cases. Scenarios simulated shipment lifecycle changes, response templating removed stale test dates, fault injection exposed resilience gaps, and request verification proved how the client actually behaved. The main point is simple: WireMock is not just for fake responses. It is a controlled failure boundary for integrations you do not own.

CLI Tools vs MCP: The Hidden Architecture Behind AI Agents

Markus — Wed, 18 Mar 2026 07:24:23 +0000

The enterprise AI discussion in 2026 has clearly moved past “add a chatbot to the side of the app.” What architects are dealing with now is something else: systems where the model is not a feature, but part of the execution fabric. I was at Devnexus last week and that shift is visible everywhere.

Most teams start with one agent. One agent reads prompts, calls tools, searches data, writes output, and maybe even tries to validate its own work. For a small prototype, this feels productive. In a real enterprise workflow, it breaks down. The same agent is suddenly expected to research, reason, execute, validate, and stay within security and compliance boundaries. That is too much cognitive load in one place. The context window fills up, tool selection gets noisy, and reliability drops.

So the architecture naturally moves toward multi-agent systems. One agent investigates. Another transforms data. Another validates. Another has permission to execute. This looks a lot more like enterprise software already looks: specialized roles, bounded responsibilities, and controlled handoffs. But once you make that move, one technical question becomes central: how do these agents talk to real systems?

Most architects still answer that question with the same mental model they use for microservices. If a capability matters, expose it as an API. Put it behind HTTP. Maybe use a specialized protocol such as MCP. That reasoning is understandable. It matches how we already structure distributed systems. Anthropic introduced the Model Context Protocol in late 2024 specifically as an open standard for connecting AI systems to tools and data sources through MCP clients and servers.

On paper, that sounds clean. In practice, many people building real agent systems are reaching for something simpler: the command line. Jannik Reinhard’s article makes that argument directly. His point is not that MCP is useless. His point is that for many agent workflows, CLI tools align much more naturally with how the model actually operates: reason, run a command, inspect output, decide the next step.

That is the important architectural shift for Java developers. For years, we treated the HTTP endpoint as the default service boundary. But agent-driven systems increasingly treat the terminal as the integration surface. If you want Java systems to participate in that world, the fastest path is often not another microservice. The fastest path is a well-designed CLI tool.

And in the Java ecosystem, the most practical way to build that tool is JBang. I’ve written about JBang and Pyhon scripts before, so go check this out too!

Why the API-Centric Model Starts to Hurt

The problem with an API-first agent architecture is not that APIs are bad. The problem is that the protocol overhead often becomes part of the model’s working memory.

MCP gives you structure. It also gives you schemas, parameter definitions, and tool metadata that often have to be loaded before the agent can do any real work. In Reinhard’s example, a GitHub MCP server with 93 tools costs roughly 55,000 tokens before the actual task starts. In his broader enterprise example, stacking multiple MCP servers pushes tool-definition overhead beyond 150,000 tokens. He contrasts that with CLI usage, where a familiar command like gh issue create ... consumes only the command and its output, not a giant schema payload.

That token math changes the architecture. Tokens are not just billing units. They are working memory. Every token spent on protocol plumbing is a token not spent on reasoning, validation, or problem solving. In Reinhard’s side-by-side Intune example, the MCP flow consumed about 145,000 tokens for a 50-device workflow, while the CLI flow used about 4,150. He presents that as roughly a 35x reduction. Even if your own numbers differ, the structural lesson is hard to ignore: agent systems become fragile when tool discovery and transport overhead start to dominate the context window.

There is another problem. MCP tends to move intermediate data through the model. If the tool returns a large log, a large transcript, or a wide JSON payload, the model has to carry that material through its reasoning loop. A shell does not have that limitation. The shell can filter before the model ever sees the result.

This is why the terminal works so well for agents. The shell already gives you progressive disclosure. The tool can return exactly what the model needs right now, not the entire universe of data that happens to be available.

Why Models Behave Like Terminal Users

Reinhard makes another useful point: models are already fluent in terminal patterns. They have seen massive amounts of documentation, tutorials, Stack Overflow posts, shell snippets, GitHub READMEs, and operational examples involving tools such as git, docker, kubectl, gh, and az. So when an agent sees a command like git log --oneline -10, it is working with a familiar pattern. When it sees a new MCP schema at runtime, it first has to learn the abstraction before it can solve the task.

This is also where Skills become important. A model may already recognize command-line patterns, but Skills make those patterns executable in a more disciplined way. They provide a reusable operating method around the CLI: which command to run, how to structure arguments, what output format to expect, how to detect failure, and how to recover safely. In that sense, Skills play a role similar to shell scripts, operational runbooks, or internal platform conventions. They do not replace CLI tools. They make CLI tools easier for agents to use correctly and consistently.

That is why CLI composability matters. The shell gives agents a native environment for chaining operations. One command produces JSON, another filters it, another extracts the field, another writes the final file. The reasoning loop becomes smaller and more focused. The model spends less effort learning the tool surface and more effort deciding what to do next.

This is also why the terminal fits multi-agent systems so well. One agent can call a diagnostic command. Another can consume the filtered output. A third can validate the result. The terminal becomes the shared execution layer, while the Skills define safe and repeatable usage patterns around that layer.

This addition fits your argument well because it shows that CLI success is not just about the shell being familiar. It is also about giving the model a reusable procedure for working inside that environment.

The Java Terminal Renaissance

If this were 2016, the argument would mostly stop here because Java would still be the wrong tool for this environment. Too much ceremony. Too much packaging. Too much runtime overhead.

That is not really true anymore.

JBang changed the ergonomics. The simplest script is a single .java file with a normal main method, and JBang supports dependency and execution metadata through script directives embedded in the file itself. It also supports remote execution, which means a script can be executed directly from a URL.

That is a big deal for agents. It means your Java CLI tool no longer needs a Maven project, a shaded jar, and a release process just to become usable. You can publish a single file and run it. You can host it in version control and let the agent fetch it directly. You can update the capability by changing one source file instead of pushing a whole service deployment.

Then there is GraalVM. You can use Native Image as a way to produce ahead-of-time compiled executables with reduced startup time and lower memory overhead that start instantly and require no warmup to run at peak performance.

For agent workloads, that matters a lot. Agents do not call tools once. They call them repeatedly. They probe. They test. They retry. They branch. If every invocation pays full JVM startup cost, that latency compounds quickly. JBang reduces friction for distribution and local execution. GraalVM removes the remaining startup penalty when the tool becomes performance-critical.

That combination: JBang for zero-ceremony distribution and GraalVM for low-latency execution, gives Java a very credible CLI story in 2026.

What an Agent-Native Java CLI Tool Should Look Like

A human-friendly CLI and an agent-friendly CLI are not the same thing.

If the consumer is an autonomous agent, your tool needs three things. It needs unambiguous arguments. It needs machine-readable output. And it needs reliable exit codes.

That is why Picocli is such a good fit. It gives you strict parameter handling and a predictable command surface. If the model generates a bad parameter, the command fails early and clearly. That is exactly what you want. The CLI becomes a hard boundary around the model’s probabilistic behavior.

The second requirement is structured output. JSON should be the default. Humans can still get a text mode for debugging, but the agent should not have to parse decorative console output. A JSON response on standard output is a much stronger contract than “some lines that probably contain the information.”

The third requirement is deterministic exit behavior. A return code of 0 means success. Non-zero means failure. That sounds basic, but it is the entire control channel for an orchestrator deciding whether to continue, retry, escalate, or stop.

Here is a small example that fits that model:

///usr/bin/env jbang "$0" "$@" ; exit $?

//DEPS info.picocli:picocli:4.7.6
//MAIN ai_tool
//DEPS com.fasterxml.jackson.core:jackson-databind:2.17.0

import picocli.CommandLine;
import picocli.CommandLine.Command;
import picocli.CommandLine.Option;

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;

import java.lang.management.ManagementFactory;
import java.time.Instant;
import java.util.concurrent.Callable;

@Command(name = "ai-tool", mixinStandardHelpOptions = true, description = "Provides structured system information for AI agents")
public class ai_tool implements Callable<Integer> {

    @Option(names = "--format", description = "Output format: json or text", defaultValue = "json")
    String format;

    public static void main(String[] args) {
        int exitCode = new CommandLine(new ai_tool()).execute(args);
        System.exit(exitCode);
    }

    @Override
    public Integer call() throws Exception {
        long uptime = ManagementFactory.getRuntimeMXBean().getUptime();
        int processors = Runtime.getRuntime().availableProcessors();
        long memory = Runtime.getRuntime().maxMemory();

        if ("text".equalsIgnoreCase(format)) {
            System.out.println("uptime=" + uptime);
            System.out.println("processors=" + processors);
            System.out.println("maxMemory=" + memory);
        } else {
            ObjectMapper mapper = new ObjectMapper();
            ObjectNode node = mapper.createObjectNode();

            node.put("timestamp", Instant.now().toString());
            node.put("uptime", uptime);
            node.put("processors", processors);
            node.put("maxMemory", memory);

            System.out.println(
                    mapper.writerWithDefaultPrettyPrinter().writeValueAsString(node));
        }

        return 0;
    }
}

This is small, but it already expresses the right contract. The command accepts a controlled argument, returns structured output by default, and finishes with a deterministic status code.

Tool Discovery Without MCP Bloat

A fair objection to CLI-first architecture is tool discovery. MCP has a built-in mechanism for advertising tool definitions. If you remove MCP, how does the agent know what exists?

In the Java world, JBang gives you a very practical answer: catalogs. JBang supports app installation and organization around scripts, and a catalog can serve as a lightweight registry of available tools. Instead of injecting giant JSON schemas into the model context, your orchestrator can maintain a compact manifest of aliases and descriptions.

That manifest can be tiny. A short Markdown list like this is often enough:

## Available Tools

- `jbang sys-info` - Returns uptime, CPU count, and max memory as JSON
- `jbang repo-check` - Scans a Git repository and reports branch, remotes, and dirty state
- `jbang log-filter` - Extracts matching lines from local application logs

This gives the model the discovery layer it needs without paying the token cost of full protocol schemas. It also keeps the descriptions human-editable. Architects can curate the tool surface instead of dumping everything into the model and hoping for the best.

Configuration and State

CLI tools for agents should stay as stateless as possible.

That is why environment variables are a good default for configuration. They work well with shells, containers, and ephemeral sandboxes. They avoid file mutation. They reduce race conditions. They fit how orchestration systems already inject secrets and environment-specific values.

A pattern like this is simple and effective:

export AI_TOOL_MODE=production

And in Java:

String mode = System.getenv("AI_TOOL_MODE");

This keeps the tool portable and easy to run under different agent roles.

Production Hardening

This is the part many demos skip. A CLI tool that works once on your laptop is not yet an enterprise integration surface.

First, you need to assume parallel execution. Agents will run tools concurrently. That means no hardcoded temp files, no global mutable state, and no fixed ports unless you really mean it. Each invocation should behave as if it is the only thing that matters, even when 20 copies are running at once.

Second, you need to treat the shell boundary as a security boundary. Do not pass raw model text into a shell and hope for good behavior. Anthropic’s transparency reporting shows that command-line and external-tool scenarios remain a serious safety domain, which is exactly why the execution layer must be controlled.

The pattern that scales is mediation. The model does not get shell access directly. An orchestrator validates intent, maps it to an allowed command, executes it in a sandbox, captures output, redacts sensitive data if needed, and only then passes the result back into the model. That is where frameworks such as Spring AI or LangChain4j fit nicely in a Java architecture: not as the executor, but as the policy and orchestration layer.

Third, you should think in terms of privilege tiers. A read-only research tool is not the same as an execution tool. A diagnostic agent should not be able to mutate infrastructure just because it can compose convincing commands. In multi-agent systems, that distinction becomes one of the main safety mechanisms.

Where MCP Still Makes Sense

The right conclusion here is not “MCP is dead.” Even Reinhard’s article does not make that claim. He argues that CLI should be the default in many workflows, not the only pattern forever.

MCP still makes sense when you need strict schema-driven contracts, complex SaaS integrations, explicit capability negotiation, or a tool surface that has no natural command-line equivalent. Anthropic still positions MCP as an open standard for connecting agents to external tools and data, and there are good reasons that idea keeps gaining support.

The more realistic enterprise answer is hybrid.

Use MCP at the perimeter where the complexity of third-party systems, OAuth flows, multi-tenant permissioning, and formal discovery justify the extra protocol. Use CLI tools at the core where the agent needs fast, local, composable, token-efficient operations on files, logs, repositories, scripts, or internal utilities.

That hybrid view is much more useful for Java architects than a protocol war.

[

](https://substackcdn.com/image/fetch/$s_!-gT0!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F9380ee34-18a0-48f9-9554-3d37bf7fad98_4239x8192.png)

Verification

You can run the JBang script directly:

jbang ai-tool.java

JBang officially supports this single-file execution model, so there is no Maven project required for the first iteration. (jbang.dev)

Expected output:

{
  "timestamp" : "2026-03-07T15:25:56.110634Z",
  "uptime" : 70,
  "processors" : 16,
  "maxMemory" : 17179869184
}

Now run the text mode:

jbang ai-tool.java --format text

Expected output:

uptime=69
processors=16
maxMemory=17179869184

The important part is not the exact values. The important part is the contract. The command accepts a stable argument, returns a stable structure, and signals completion with a stable exit code.

That is what makes it usable by an agent.

Conclusion

The industry started by assuming agents would integrate like API clients. That assumption is starting to crack. Protocols such as MCP give structure, but they also introduce schema overhead, token pressure, and a less natural execution model for many real workflows. CLI tools fit the agent loop much better: reason, run, inspect, refine. Reinhard’s examples and benchmarks make that case clearly, even if every team will end up with its own numbers.

For Java architects, this opens an opportunity. JBang turns Java into a zero-ceremony scripting environment. GraalVM Native Image gives Java an execution profile that fits high-frequency agent loops. Picocli gives you strong command boundaries. Put together, they give Java a serious role in the terminal-native AI stack.

The future is probably not MCP or CLI. It is MCP and CLI, used deliberately. But when you need the fastest, simplest, most agent-native path into an existing Java estate, the terminal is often the right integration surface.

Subscribe now

Building a Terminal Substack Reader with TamboUI

Markus — Sun, 15 Mar 2026 07:53:23 +0000

I spend a lot of time in the terminal. Not because I have to. Because that’s where my focus is. Git, Maven, Podman, logs, tests. Everything important runs there. When I switch to a browser just to read one article, I feel the context break immediately.

This is exactly why I’m such a big fan of JBang.

JBang removed something that bothered me for years: the ceremony around small Java tools. Before JBang, writing a “quick” CLI in Java meant creating a project, writing a pom.xml, managing classpaths, packaging jars. It was friction. Now you write one file, add a few //DEPS, and run it. Done.

And honestly, Max Rydahl Andersen deserves serious credit here. Max is not just “the JBang guy”. He’s a Distinguished Engineer at Red Hat and part of the Quarkus team. You can see the same mindset in both places: remove friction, shorten feedback loops, make Java feel modern again. JBang makes Java viable for scripting. Quarkus makes Java viable for cloud-native workloads. Same philosophy, different layer.

But JBang alone is not enough.

For a long time, if you wanted to build a proper terminal UI in Java, you had two options:

Write raw ANSI escape codes and suffer
Pull in a heavy abstraction that felt like 2008

That’s where TamboUI comes in.

TamboUI was born out of the idea that Java deserves a modern TUI framework. Something lightweight. Something composable. Something that doesn’t fight you. It gives you layouts, widgets, state handling, and a rendering loop that actually behaves correctly inside a real TTY. And the design feels influenced by modern TUI systems like Rust’s Ratatui, but done in a way that feels natural in Java.

So let’s build something practical: a terminal reader for The Main Thread. We’ll fetch recent posts from Substack’s JSON endpoint, list them in a scrollable left panel, and render the selected article on the right.

I am not using JBang in this tutorial, because I want to use this little example application in a different context in a follow-up part. So bare with me.

Prerequisites

You need a basic Java development setup. We assume you can run Maven projects and read Java code comfortably.

Java 21 installed
Maven 3.6 or newer
Basic understanding of Java classes and records
Basic familiarity with HTTP and JSON

We are not installing Java here. We focus on the application itself.

Project Setup

Create a new directory:

mkdir substack-reader
cd substack-reader

Add the following pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>substack-reader</groupId>
    <artifactId>substack-reader</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <properties>
        <maven.compiler.release>21</maven.compiler.release>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <repositories>
        <repository>
            <id>central-portal-snapshots</id>
            <url>https://central.sonatype.com/repository/maven-snapshots/</url>
        </repository>
    </repositories>

    <dependencies>
        <!-- We add dependencies in the following steps -->
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.13.0</version>
                <configuration><release>21</release></configuration>
            </plugin>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>3.1.1</version>
                <configuration>
                    <mainClass>substack.reader.SubstackReader</mainClass>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

Create the package directories

mkdir -p src/main/java/substack/reader

and a minimal main class so we can confirm the project runs:


package substack.reader;

public class SubstackReader {
    public static void main(String[] args) {
        System.out.println("Substack Reader — coming soon");
    }
}

Run the app from the project root:

mvn compile exec:java -q

You should see the single line of output. The -q flag keeps Maven output quiet so we can focus on the application. We use the exec plugin so we can iterate quickly without building a fat JAR; for distribution you would later add a JAR packaging step.

Define the Data Model and Fetch Posts from the Substack API

Substack publications expose an (undocumented) public API that returns recent posts as JSON. We need a simple data type to hold each post and code to perform the HTTP request and parse the response.

Why a record for the post model?

We use a Java record for the post type. Records give us an immutable data carrier with a constructor, accessors, and equals/hashCode/toString for free. We do not need setters or mutable state. Each post is loaded once and only read, so a record keeps the model clear and avoids boilerplate.

Add the Gson dependency to pom.xml under <dependencies>:

        <dependency>
            <groupId>com.google.code.gson</groupId>
            <artifactId>gson</artifactId>
            <version>2.11.0</version>
        </dependency>

Define the post model and a method to fetch posts. We store title, subtitle, date, URL, raw HTML body (we will convert it to text later), and a flag indicating whether the post is free to read (so we can show a lock icon for paid content):

    record Post(String title, String subtitle, String date, String url, String bodyHtml, boolean free) {
    }

Why the built-in HttpClient?

We use java.net.http.HttpClient instead of a third-party HTTP library. It is part of the JDK, so we avoid an extra dependency, and it supports async and sync usage. For this app we only need a single synchronous GET request at startup, so the API stays simple.

Implement the fetch method. We set a User-Agent header because some servers expect it; we use a descriptive value so the request is identifiable:

 static List<Post> fetchPosts(String baseUrl, int limit) throws Exception {
        var client = HttpClient.newHttpClient();
        var request = HttpRequest.newBuilder()
                .uri(URI.create(baseUrl + "/api/v1/posts?limit=" + limit + "&offset=0&sort=new"))
                .header("User-Agent", "Mozilla/5.0 TamboUI-Demo/1.0")
                .GET().build();

        var resp = client.send(request, HttpResponse.BodyHandlers.ofString());
        if (resp.statusCode() != 200)
            throw new RuntimeException("HTTP " + resp.statusCode() + " from Substack API");

        return parsePostsJson(resp.body(), baseUrl);
    }

Why Gson and manual parsing?

We use Gson because it is lightweight and well known, and we only need to read JSON (no serialization to JSON). We parse into a generic JsonElement first because the Substack API is not consistent: sometimes the response is a bare array of posts, and sometimes it is an object with a posts array. Handling both shapes in one method keeps the rest of the app independent of that detail.

Add the parser and a small helper to safely read string fields:

 static List<Post> parsePostsJson(String json, String baseUrl) {
        var posts = new ArrayList<Post>();
        var root = new Gson().fromJson(json, JsonElement.class);
        if (root == null) return posts;
        JsonArray arr;
        if (root.isJsonArray()) {
            arr = root.getAsJsonArray();
        } else {
            var postsEl = root.getAsJsonObject().get("posts");
            if (postsEl == null || !postsEl.isJsonArray()) return posts;
            arr = postsEl.getAsJsonArray();
        }
        for (JsonElement el : arr) {
            JsonObject obj = el.getAsJsonObject();
            var title = getStr(obj, "title");
            if (title == null || title.isBlank()) continue;
            var subtitle = getStr(obj, "subtitle");
            var date = getStr(obj, "post_date");
            var slug = getStr(obj, "slug");
            var body = getStr(obj, "body_html");
            var audience = getStr(obj, "audience");
            var d = date != null && date.length() >= 10 ? date.substring(0, 10) : "";
            posts.add(new Post(
                    title,
                    subtitle != null ? subtitle : "",
                    d,
                    baseUrl + "/p/" + (slug != null ? slug : ""),
                    body != null ? body : "",
                    "everyone".equals(audience)));
        }
        return posts;
    }

    static String getStr(JsonObject obj, String key) {
        if (!obj.has(key)) return null;
        var el = obj.get(key);
        return el.isJsonNull() ? null : el.getAsString();
    }

Add the required imports: java.net.URI, java.net.http.*, java.util.*, and com.google.gson.*.

Wire the fetch into main so we can verify that we get data:

public static void main(String[] args) throws Exception {
    System.out.println("Fetching articles...");
    var posts = fetchPosts("https://www.the-main-thread.com", 25);
    System.out.println("Found " + posts.size() + " posts");
    posts.stream().limit(3).forEach(p -> System.out.println(" " + p.date() + " " + p.title()));
}

Run mvn compile exec:java -q again. You should see a count and the first few post titles. This confirms that the HTTP call and JSON parsing work before we add the UI.

Convert HTML to Plain Text with Jsoup

The API returns article bodies as HTML. The terminal cannot render HTML; we need plain text with line breaks so that paragraphs and headings are readable. We use Jsoup to parse the HTML and walk the document tree, emitting text and newlines for block-level elements.

Why Jsoup instead of regex?

Parsing HTML with regular expressions is brittle (nested tags, missing closing tags, and so on). Jsoup parses HTML into a document object model (DOM) and lets us traverse it. We only need to visit each node once and append text or newlines, so a simple visitor is enough and we avoid pulling in a full browser engine.

Add the Jsoup dependency:

        <dependency>
            <groupId>org.jsoup</groupId>
            <artifactId>jsoup</artifactId>
            <version>1.18.1</version>
        </dependency>

Implement a converter that walks the body of the parsed document. We use Jsoup’s NodeVisitor: in head we handle the node when we first enter it, and in tail when we leave it. For text nodes we append the text; for elements we add newlines before or after block elements (headings, paragraphs, list items, line breaks, and code blocks). At the end we collapse long runs of blank lines into at most two newlines. If the body is null or blank (for example, paywalled content), we return a short message so the user knows to open the URL in a browser.

static String htmlToText(String html) {
        if (html == null || html.isBlank())
            return "(No content — this article may be paywalled)\n\nVisit the article URL above to read it in your browser.";
        var out = new StringBuilder();
        var body = Jsoup.parse(html).body();
        if (body == null) return "";
        body.traverse(new NodeVisitor() {
            @Override
            public void head(Node node, int depth) {
                if (node instanceof TextNode tn) {
                    out.append(tn.getWholeText());
                    return;
                }
                if (node instanceof Element el) {
                    var name = el.normalName();
                    switch (name) {
                        case "h1", "h2", "h3", "h4", "h5", "h6" -> out.append("\n\n## ");
                        case "p", "div", "li" -> out.append("\n");
                        case "br" -> out.append("\n");
                        case "pre" -> out.append("\n```

\n");
                        default -> { }
                    }
                }
            }
            @Override
            public void tail(Node node, int depth) {
                if (node instanceof Element el) {
                    var name = el.normalName();
                    switch (name) {
                        case "h1", "h2", "h3", "h4", "h5", "h6" -> out.append("\n");
                        case "pre" -> out.append("\n

```\n");
                        default -> { }
                    }
                }
            }
        });
        return out.toString().replaceAll("(\n\\s*){3,}", "\n\n").trim();
    }

Add imports: org.jsoup.*, org.jsoup.nodes.*, and org.jsoup.select.NodeVisitor. You can temporarily print htmlToText(posts.get(0).bodyHtml()) from main to confirm the output looks right before moving on to the TUI.

Add the Terminal UI with TamboUI

With data and text conversion in place, we add the terminal UI. We use TamboUI, a Java TUI toolkit inspired by Rust’s ratatui, so we can draw lists, blocks, and paragraphs and react to key events without handling raw terminal escape codes ourselves.

Why TamboUI?

TamboUI gives us widgets (blocks with borders, lists, paragraphs), layout helpers, and key event handling. We could use JLine or the Java Console API directly, but we would spend more code on layout and redraw logic. TamboUI fits our needs: a list screen and an article screen with scrollable text.

Add the TamboUI dependencies (the Sonatype snapshot repository in Step 1 is where these are published):

  <dependency>
            <groupId>dev.tamboui</groupId>
            <artifactId>tamboui-toolkit</artifactId>
            <version>0.2.0-SNAPSHOT</version>
        </dependency>
        <dependency>
            <groupId>dev.tamboui</groupId>
            <artifactId>tamboui-jline3-backend</artifactId>
            <version>0.2.0-SNAPSHOT</version>
</dependency>

How the TUI loop works

TamboUI’s TuiRunner runs an event loop. You pass two callbacks: one that handles input (keys) and returns whether the event was consumed, and one that draws the current frame. Both run in the same thread, so we need shared state that both can read and update. We use a single-element array for the current screen and for the article scroll offset so that our lambdas can mutate them (local variables used in lambdas must be effectively final, but the array reference is final; only its content changes).

Define an enum for the two screens and, in main, after fetching posts, build the list of display strings and the state objects:

    enum Screen {
        LIST, ARTICLE
    }

In main, after you have the list of posts:

        var listItems = posts.stream()
                .map(p -> (p.free() ? " " : "🔒 ") + "[" + p.date() + "] " + p.title())
                .toArray(String[]::new);

        var listState = new ListState();
        listState.select(0);

        var screen = new Screen[] { Screen.LIST };
        var scrollOff = new int[] { 0 };

Start the TUI and pass placeholder callbacks; we fill in the key handler and the render logic in the next two steps:

try (var tui = TuiRunner.create()) {
  tui.run(
            (event, runner) -> { /* key handler */ },
            frame -> { /* render */ });
}

You will need imports from dev.tamboui.tui, dev.tamboui.terminal, dev.tamboui.layout, and dev.tamboui.widgets.list; we add the rest as we introduce each widget.

Handle Keyboard Input

The TUI must react to keys: quit on the list screen, go back from the article screen, move the selection up and down, open the selected article, and scroll the article body. TamboUI turns key presses into KeyEvent objects. We use Java 21 pattern matching in a switch so we can match on the event type and conditions in one place and keep the handler readable.

Return true from the handler when you have handled the event so the runner does not treat it as something else (for example, passing it to the terminal). On the list screen, quit (q) exits the app; on the article screen, cancel (Escape) or quit goes back to the list and resets the scroll. Up and down either move the list selection or change the article scroll offset depending on the current screen. Enter on the list opens the selected article.

(event, runner) -> switch (event) {
    case KeyEvent k when k.isQuit() && screen[0] == Screen.LIST -> {
        runner.quit();
        yield true;
    }
    case KeyEvent k when (k.isCancel() || k.isQuit()) && screen[0] == Screen.ARTICLE -> {
        screen[0] = Screen.LIST;
        scrollOff[0] = 0;
        yield true;
    }
    case KeyEvent k when k.isDown() && screen[0] == Screen.LIST -> {
        listState.selectNext(listItems.length);
        yield true;
    }
    case KeyEvent k when k.isUp() && screen[0] == Screen.LIST -> {
        listState.selectPrevious();
        yield true;
    }
    case KeyEvent k when k.isSelect() && screen[0] == Screen.LIST -> {
        screen[0] = Screen.ARTICLE;
        scrollOff[0] = 0;
        yield true;
    }
    case KeyEvent k when k.isDown() && screen[0] == Screen.ARTICLE -> {
        scrollOff[0]++;
        yield true;
    }
    case KeyEvent k when k.isUp() && screen[0] == Screen.ARTICLE -> {
        scrollOff[0] = Math.max(0, scrollOff[0] - 1);
        yield true;
    }
    default -> false;
}

Add the import for dev.tamboui.tui.event.KeyEvent. In TamboUI, isQuit() corresponds to q, isCancel() to Escape, and isSelect() to Enter.

Render the List Screen

When the user is on the list screen, we draw a bordered block with a title, the list of posts (with the current selection highlighted), and a status bar at the bottom. TamboUI’s Block widget draws the border and optional title; we call inner(area) to get the rectangle inside the border so the list is drawn in the right place. We use ListWidget for the items and renderStatefulWidget so the list’s selected index is kept in listState.

    static void renderList(Frame frame, Rect area,
            String[] items, ListState state, List<Post> posts) {
        var outerBlock = Block.builder()
                .title(Title.from(" 📰 The Main Thread — Substack Reader "))
                .borders(Borders.ALL)
                .borderType(BorderType.ROUNDED)
                .build();
        var inner = outerBlock.inner(area);
        frame.renderWidget(outerBlock, area);

        var listWidget = ListWidget.builder()
                .items(items)
                .highlightStyle(Style.EMPTY.fg(Color.CYAN).addModifier(Modifier.BOLD))
                .highlightSymbol("▶ ")
                .build();
        frame.renderStatefulWidget(listWidget, inner, state);

        renderStatusBar(frame, area, "↑↓ navigate Enter read q quit");
    }

The status bar is a one-line area at the bottom of the frame. We reuse it on both screens with different hint text so the user always sees the current key bindings:

    static void renderStatusBar(Frame frame, Rect area, String hint) {
        var barArea = Rect.of(new Position(area.x(), area.y() + area.height() - 1), new Size(area.width(), 1));
        frame.renderWidget(
                Paragraph.builder()
                        .text(Text.from(" " + hint))
                        .style(Style.EMPTY.bg(Color.DARK_GRAY).fg(Color.WHITE))
                        .build(),
                barArea);
    }

Add imports for dev.tamboui.widgets.block.*, dev.tamboui.widgets.list.ListWidget, dev.tamboui.widgets.paragraph.Paragraph, dev.tamboui.text.*, dev.tamboui.style.*, and dev.tamboui.layout.Position and Size.

In the frame callback, delegate to renderList when the current screen is LIST, and to the article renderer (Step 7) when it is ARTICLE:

frame -> {
                        var area = frame.area();
                        if (screen[0] == Screen.LIST) {
                            renderList(frame, area, listItems, listState, posts);
                        } else {
                            int idx = Optional.ofNullable(listState.selected()).orElse(0);
                            renderArticle(frame, area, posts.get(idx), scrollOff[0]);
                        }
                    }

Render the Article Screen

On the article screen we show a fixed header (title, date, free/paid, subtitle, URL) and a scrollable body. We split the frame into two regions: a short strip for the header (5 rows) and the rest for the body. We do that split manually with Rect.of, Position, and Size instead of TamboUI’s constraint-based Layout: the layout solver can throw DuplicateConstraintException when switching to the article screen because of internal cache reuse, so a simple manual split avoids that and keeps the same visual result (5 rows for the header, remainder for the body).

We draw a block for the header and a paragraph inside it with styled lines. For the body we draw another block and a paragraph that uses scroll(scrollOffset) and Overflow.WRAP_WORD so long lines wrap and the user can scroll with the arrow keys.

    static void renderArticle(Frame frame, Rect area, Post post, int scrollOffset) {
        // Split manually to avoid Layout cache reusing solver (DuplicateConstraintException)
        var headerRect = Rect.of(new Position(area.x(), area.y()), new Size(area.width(), 5));
        var bodyRect = Rect.of(
                new Position(area.x(), area.y() + 5),
                new Size(area.width(), Math.max(0, area.height() - 5)));

        // Header
        var hBlock = Block.builder()
                .title(Title.from(" " + truncate(post.title(), 58) + " "))
                .borders(Borders.ALL)
                .borderType(BorderType.ROUNDED)
                .build();
        frame.renderWidget(hBlock, headerRect);
        var hInner = hBlock.inner(headerRect);
        frame.renderWidget(
                Paragraph.builder()
                        .text(Text.from(
                                Line.from(Span.styled(post.date() + (post.free() ? " free" : " paid"),
                                        Style.EMPTY.fg(Color.YELLOW))),
                                Line.from(Span.raw(post.subtitle())),
                                Line.from(Span.styled(post.url(), Style.EMPTY.fg(Color.BLUE).addModifier(Modifier.DIM)))))
                        .build(),
                hInner);

        // Body
        var bBlock = Block.builder()
                .borders(Borders.ALL)
                .borderType(BorderType.ROUNDED)
                .build();
        var bInner = bBlock.inner(bodyRect);
        frame.renderWidget(bBlock, bodyRect);
        frame.renderWidget(
                Paragraph.builder()
                        .text(Text.from(htmlToText(post.bodyHtml())))
                        .scroll(scrollOffset)
                        .overflow(Overflow.WRAP_WORD)
                        .build(),
                bInner);

        renderStatusBar(frame, area, "↑↓ scroll Esc / q back to list");
    }

Add a helper to truncate long titles so they fit in the header:

    static String truncate(String s, int max) {
        return s.length() <= max ? s : s.substring(0, max - 1) + "…";
    }

Import Overflow from the TamboUI style package and Position and Size from the layout package (used for the manual area split and the status bar).

Add Error Handling and Run the App

Before we start the TUI, we wrap the fetch in a try-catch so that network or API errors produce a short message instead of a long stack trace. If the fetch returns no posts, we exit with a clear message so the user does not see an empty list without context.

In main, replace the direct call to fetchPosts with:

        List<Post> posts;
        try {
            posts = fetchPosts("https://www.the-main-thread.com", 25);
        } catch (Exception e) {
            System.err.println("Failed to fetch posts: " + e.getMessage());
            return;
        }

        if (posts.isEmpty()) {
            System.err.println("No posts found.");
            return;
        }

Then run the application from the project root:

mvn compile exec:java -q

You should see the list of posts. Use the Up and Down arrow keys to move the selection, Enter to open an article, Up and Down to scroll the article body, and Escape or q to go back to the list or quit.

Conclusion

We built a focused terminal Substack reader in Java 21. It uses the JDK HTTP client for network calls, Gson for JSON parsing, Jsoup for HTML-to-text conversion, and TamboUI for the terminal UI. The design is simple, but each layer has a clear responsibility. HTTP fetch, parsing, transformation, and rendering are separated.

You now have a complete example of combining network I/O, text processing, and a terminal UI in modern Java.

Subscribe now

AI can generate code. But...

Markus — Tue, 10 Mar 2026 11:32:29 +0000

... building reliable software systems still requires structure, architecture, and discipline.

At IBM TechCon 2026, I’m running a short 3-talk series on AI-assisted development with Bob, Java, and Quarkus:

how to work effectively with AI in large Java codebases
how to structure AI-assisted development so it scales
how to turn AI speed into real enterprise value If you're building modern Java systems, this is for you.

Build a Real MCP Server in Java with Quarkus

Markus — Sat, 07 Mar 2026 07:08:08 +0000

Most IDE integrations die for a boring reason: every client needs a custom plugin for every service. You want your AI IDE to access ten systems (GitHub, Jira, a DB, internal docs, scripts). Without a standard, you build ten integrations per IDE. Then you repeat it for the next IDE.

MCP (Model Context Protocol) removes this “M×N integration” problem by putting the integration logic into a small server. Your IDE becomes the generic MCP client. Your server exposes tools (actions), resources (read-only context), resource templates (parameterized resources), and prompts (reusable prompt starters). MCP messages are JSON-RPC 2.0 over stdio or Streamable HTTP. (Model Context Protocol)

The production failure mode is also very predictable: if you implement “tool calling” ad-hoc, you end up with brittle glue code, unclear schemas, and no observability. When the LLM starts making wrong calls, you have no idea what happened, because the integration boundary is invisible.

In this tutorial we make this boundary explicit. We build a real Quarkus MCP server that you can connect to IBM Bob (or any MCP client that supports Streamable HTTP). We also add tests, and we log the JSON-RPC traffic so you can debug it at 2am.

Prerequisites

We’ll run the server and test it with an MCP client.

Java 21
Maven 3.9+
One MCP client for manual testing: MCP Inspector (Node.js 18+)
curl

Project Setup

We’ll build a “Dev Toolkit” MCP server. It exposes:

Tools for small developer utilities (string ops, note writing)
Resources for “project notes” you want the IDE to inject as context
Resource templates for dynamic URIs (dev-toolkit://notes/{key})
Prompts for common tasks (code review, explain error)

Create the project

Create the project or start from my Github repository:

mvn io.quarkus:quarkus-maven-plugin:create \
  -DprojectGroupId=com.example.mcp \
  -DprojectArtifactId=dev-toolkit-mcp \
  -DprojectVersion=1.0.0-SNAPSHOT \
  -Dextensions="io.quarkiverse.mcp:quarkus-mcp-server-http:1.10.0, rest-assured" \
  -DnoCode
cd dev-toolkit-mcp

Implementation

Tools are the “actions” the LLM can ask the client to call. Tools have side effects. This is where you need to be disciplined, because a tool is effectively a remote operation the model can trigger.

Create src/main/java/com/example/mcp/StringTools.java:

package com.example.mcp;

import java.nio.charset.StandardCharsets;
import java.util.Base64;
import java.util.List;

import io.quarkiverse.mcp.server.TextContent;
import io.quarkiverse.mcp.server.Tool;
import io.quarkiverse.mcp.server.ToolArg;
import io.quarkiverse.mcp.server.ToolResponse;

public class StringTools {

    @Tool(description = "Convert a string to UPPER_SNAKE_CASE, useful for generating constant names.")
    String toUpperSnakeCase(
            @ToolArg(description = "The input string, e.g. 'my variable name'") String input) {

        if (input == null) {
            return "";
        }

        return input.trim()
                .replaceAll("\\s+", "_")
                .replaceAll("[^a-zA-Z0-9_]", "")
                .toUpperCase();
    }

    @Tool(description = "Count occurrences of a substring within a larger string.")
    String countOccurrences(
            @ToolArg(description = "The text to search in") String text,
            @ToolArg(description = "The substring to count") String substring) {

        if (text == null || text.isEmpty() || substring == null || substring.isEmpty()) {
            return "0";
        }

        int count = 0;
        int idx = 0;
        while ((idx = text.indexOf(substring, idx)) != -1) {
            count++;
            idx += substring.length();
        }
        return String.valueOf(count);
    }

    @Tool(description = "Encode or decode a string using Base64. Returns both the result and metadata.")
    ToolResponse base64Transform(
            @ToolArg(description = "The string to process") String input,
            @ToolArg(description = "Operation: 'encode' or 'decode'") String operation) {

        if (input == null) {
            input = "";
        }
        if (operation == null) {
            operation = "";
        }

        try {
            String result;
            if ("encode".equalsIgnoreCase(operation)) {
                result = Base64.getEncoder().encodeToString(input.getBytes(StandardCharsets.UTF_8));
            } else if ("decode".equalsIgnoreCase(operation)) {
                result = new String(Base64.getDecoder().decode(input), StandardCharsets.UTF_8);
            } else {
                return ToolResponse.error("Unknown operation: '" + operation + "'. Use 'encode' or 'decode'.");
            }

            return ToolResponse.success(List.of(
                    new TextContent("Result: " + result),
                    new TextContent("Operation: " + operation + " | Input length: " + input.length())));
        } catch (Exception e) {
            return ToolResponse.error("Error: " + e.getMessage());
        }
    }

    @Tool(description = "Truncate a string to a maximum length, appending an ellipsis if truncated.")
    String truncate(
            @ToolArg(description = "The string to truncate") String input,
            @ToolArg(description = "Maximum character length (default: 100)") Integer maxLength) {

        if (input == null) {
            return "";
        }

        int limit = (maxLength != null && maxLength > 0) ? maxLength : 100;
        if (input.length() <= limit) {
            return input;
        }
        if (limit < 4) {
            return input.substring(0, limit);
        }
        return input.substring(0, limit - 3) + "...";
    }
}

What this gives you: Quarkus will generate a JSON Schema per tool method, based on the Java parameters and @ToolArg metadata. This schema is what MCP clients show to the model when it decides if a tool is relevant. This is a big deal: if the schema is vague, the model will call tools in weird ways.

Implementing a resource store

Resources are read-only context. The client decides when to read them, usually to enrich the prompt context. Resources should be stable and safe to inject.

Create src/main/java/com/example/mcp/ProjectResources.java:

package com.example.mcp;

import java.time.OffsetDateTime;
import java.time.format.DateTimeFormatter;
import java.util.Base64;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

import io.quarkiverse.mcp.server.BlobResourceContents;
import io.quarkiverse.mcp.server.RequestUri;
import io.quarkiverse.mcp.server.Resource;
import io.quarkiverse.mcp.server.TextResourceContents;
import jakarta.inject.Singleton;

@Singleton
public class ProjectResources {

    private final Map<String, String> notes = new ConcurrentHashMap<>();

    public ProjectResources() {
        notes.put("conventions",
                """
                        # Code Conventions

                        - Use camelCase for methods
                        - Use PascalCase for classes
                        - Max line length: 120 chars
                        - Prefer records over POJOs
                        """);

        notes.put("architecture",
                """
                        # Architecture Notes

                        - Hexagonal architecture
                        - Domain layer has zero dependencies
                        - Adapters live in `infrastructure` package
                        """);
    }

    @Resource(uri = "dev-toolkit://server-info", name = "Server Info", description = "Current server status and timestamp")
    TextResourceContents serverInfo(RequestUri uri) {
        String content = """
                # Dev Toolkit MCP Server

                Status: Online
                Time: %s

                ## Available Note Keys
                %s
                """.formatted(
                OffsetDateTime.now().format(DateTimeFormatter.ISO_OFFSET_DATE_TIME),
                String.join(", ", notes.keySet()));

        return new TextResourceContents(uri.value(), content, "text/markdown");
    }

    @Resource(uri = "dev-toolkit://java-string-cheatsheet", name = "Java String Cheat Sheet", description = "Quick reference for common Java String methods")
    TextResourceContents javaStringCheatsheet(RequestUri uri) {
        String content = """
                # Java String Cheat Sheet

                ## Basic Operations
                - `s.length()`
                - `s.isEmpty()`
                - `s.isBlank()`
                - `s.trim()` and `s.strip()`

                ## Searching
                - `s.contains(sub)`
                - `s.indexOf(sub)`
                - `s.startsWith(prefix)` and `s.endsWith(suffix)`

                ## Transforming
                - `s.toUpperCase()` and `s.toLowerCase()`
                - `s.replace(old, new)` and `s.replaceAll(regex, replacement)`
                - `s.substring(start, end)`
                - `String.join(delimiter, parts...)`
                """;
        return new TextResourceContents(uri.value(), content, "text/markdown");
    }

    @Resource(uri = "dev-toolkit://sample-icon", name = "Sample Icon", description = "A tiny sample binary resource (1x1 red pixel PNG)")
    BlobResourceContents sampleIcon(RequestUri uri) {
        byte[] tinyPng = new byte[] {
                (byte) 0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A,
                0x00, 0x00, 0x00, 0x0D, 0x49, 0x48, 0x44, 0x52,
                0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01,
                0x08, 0x02, 0x00, 0x00, 0x00, (byte) 0x90, 0x77, 0x53,
                (byte) 0xDE, 0x00, 0x00, 0x00, 0x0C, 0x49, 0x44, 0x41,
                0x54, 0x08, (byte) 0xD7, 0x63, (byte) 0xF8, (byte) 0xCF, (byte) 0xC0, 0x00, 0x00,
                0x00, 0x02, 0x00, 0x01, (byte) 0xE2, 0x21, (byte) 0xBC, 0x33,
                0x00, 0x00, 0x00, 0x00, 0x49, 0x45, 0x4E, 0x44,
                (byte) 0xAE, 0x42, 0x60, (byte) 0x82
        };

        return new BlobResourceContents(uri.value(), Base64.getEncoder().encodeToString(tinyPng), "image/png");
    }

    public Map<String, String> getNotes() {
        return notes;
    }

    public void putNote(String key, String content) {
        notes.put(key, content);
    }
}

The important part: a resource is a stable URI the client can fetch and paste into context. That means resources are part of your “prompt supply chain”. Don’t put secrets here.

Implementing resource templates

Templates are resources with path variables. This feels like REST path params, but it’s a URI scheme you control.

Create src/main/java/com/example/mcp/NoteTemplates.java:

package com.example.mcp;

import io.quarkiverse.mcp.server.RequestUri;
import io.quarkiverse.mcp.server.ResourceTemplate;
import io.quarkiverse.mcp.server.ResourceTemplateArg;
import io.quarkiverse.mcp.server.TextResourceContents;
import jakarta.inject.Inject;
import jakarta.inject.Singleton;

@Singleton
public class NoteTemplates {

    @Inject
    ProjectResources projectResources;

    @ResourceTemplate(uriTemplate = "dev-toolkit://notes/{key}", name = "Project Note", description = "Retrieve a project note by key")
    TextResourceContents getNote(
            @ResourceTemplateArg(name = "key") String key,
            RequestUri uri) {

        String note = projectResources.getNotes().get(key);
        if (note == null) {
            String content = """
                    # Note Not Found

                    No note exists with key: `%s`

                    Available keys: %s
                    """.formatted(key, String.join(", ", projectResources.getNotes().keySet()));

            return new TextResourceContents(uri.value(), content, "text/markdown");
        }

        return new TextResourceContents(uri.value(), note, "text/markdown");
    }
}

This is a good pattern: templates let the IDE fetch “the right note” without listing a huge static catalog.

Implementing a tool with side effects

Now we connect tools and resources: a tool writes a note, a resource template reads it. This is the smallest “real” MCP server loop.

Create src/main/java/com/example/mcp/NoteTools.java:

package com.example.mcp;

import java.util.List;

import io.quarkiverse.mcp.server.TextContent;
import io.quarkiverse.mcp.server.Tool;
import io.quarkiverse.mcp.server.ToolArg;
import io.quarkiverse.mcp.server.ToolResponse;
import jakarta.inject.Inject;

public class NoteTools {

    @Inject
    ProjectResources projectResources;

    @Tool(description = "Save or update a project note by key. This has side effects.")
    ToolResponse saveNote(
            @ToolArg(description = "Note key, e.g. 'conventions'") String key,
            @ToolArg(description = "Markdown content") String content) {

        if (key == null || key.isBlank()) {
            return ToolResponse.error("Key must not be blank.");
        }
        if (content == null) {
            content = "";
        }

        projectResources.putNote(key, content);

        return ToolResponse.success(List.of(
                new TextContent("Saved note: " + key),
                new TextContent("Read it via: dev-toolkit://notes/" + key)));
    }
}

This is where you need to think like an operator: tools can be abused. If your client lets the model call tools freely, this tool can fill memory. For this tutorial we keep it simple, but in production you usually add quotas, auth, and persistence.

Implementing prompts

Prompts are templates the user selects in the IDE (often via a prompt picker). The server returns pre-built messages. It does not “execute” anything.

Create src/main/java/com/example/mcp/DevPrompts.java:

package com.example.mcp;

import java.util.List;

import io.quarkiverse.mcp.server.Prompt;
import io.quarkiverse.mcp.server.PromptArg;
import io.quarkiverse.mcp.server.PromptMessage;
import io.quarkiverse.mcp.server.TextContent;
import jakarta.inject.Singleton;

@Singleton
public class DevPrompts {

    @Prompt(name = "explain-error", description = "Generate a prompt to explain a Java error or exception clearly")
    PromptMessage explainError(
            @PromptArg(description = "The full error message or stack trace") String error) {

        String text = """
                Please explain this Java error in simple terms:

                ```


                %s


                ```

                In your explanation:
                1. What caused this error
                2. Common root causes
                3. How to fix it
                4. How to prevent it next time
                """.formatted(error == null ? "" : error);

        return PromptMessage.withUserRole(new TextContent(text));
    }

    @Prompt(name = "code-review", description = "Generate a structured code review prompt following project conventions")
    List<PromptMessage> codeReview(
            @PromptArg(description = "The code to review") String code,
            @PromptArg(description = "Language (optional, default: Java)") String language,
            @PromptArg(description = "Focus area: security, performance, readability, or all (optional)") String focus) {

        String lang = (language != null && !language.isBlank()) ? language : "Java";
        String focusArea = (focus != null && !focus.isBlank()) ? focus : "all";

        String systemText = """
                You are a senior software engineer doing a code review.
                Apply these conventions: camelCase methods, PascalCase classes,
                max 120 char lines, prefer records over POJOs, hexagonal architecture.
                Be direct and specific.
                """;

        String userText = """
                Please review this %s code focusing on: %s

                ```

%s
                %s


                ```

                Structure your review as:
                - Summary
                - Issues Found (critical, major, minor)
                - Suggestions
                - Positives
                """.formatted(lang, focusArea, lang.toLowerCase(), code == null ? "" : code);

        return List.of(
                PromptMessage.withAssistantRole(new TextContent(systemText)),
                PromptMessage.withUserRole(new TextContent(userText)));
    }
}

Configuration

Configure the MCP server in src/main/resources/application.properties:

# HTTP
quarkus.http.port=8080

# Logging
quarkus.log.level=INFO
#quarkus.log.category."io.quarkiverse.mcp".level=DEBUG

Production Hardening

Tool abuse and resource exhaustion

Your tools are remote operations. If the client gives the model freedom, it can spam tools. The simplest hardening is to keep tools small, validate input, and return clean errors (like we did in saveNote and base64Transform). Next step is auth and per-user limits.

If you expose “write” tools, plan for quotas. In this tutorial saveNote writes into a ConcurrentHashMap. This is fine for learning, but in production it turns into memory growth. You either persist to a DB with retention, or you block “unbounded writes”.

Transport choice and deployment boundary

Use HTTP transport for IDE integrations and remote clients. Use stdio when the client launches the server as a subprocess (common on desktops). The MCP spec recommends supporting stdio whenever possible, but Streamable HTTP is the main transport for networked scenarios.

Start the server

mvn quarkus:dev

You should see the server start and bind to port 8080.

Manual test with MCP Inspector

Install and run MCP Inspector:

npx @modelcontextprotocol/inspector

Then in the UI:

Transport: Streamable HTTP
URL: http://localhost:8080/mcp

Now verify:

Tools list includes toUpperSnakeCase, countOccurrences, base64Transform, truncate, and saveNote
Resource list includes dev-toolkit://server-info and dev-toolkit://java-string-cheatsheet
Resource template list includes dev-toolkit://notes/{key}
Prompts list includes explain-error and code-review

[

](https://substackcdn.com/image/fetch/$s_!mJwr!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F1ea62123-ed22-48ff-ad76-1995b77d225e_3024x1750.png)

Automated test

Create src/test/java/com/example/mcp/McpSmokeTest.java:

package com.example.mcp;

import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.containsString;

import org.junit.jupiter.api.Test;

import io.quarkus.test.junit.QuarkusTest;
import io.restassured.response.Response;

@QuarkusTest
class McpSmokeTest {

    /**
     * MCP Streamable HTTP requires Accept to include both application/json and
     * text/event-stream.
     */
    private static final String MCP_ACCEPT = "application/json, text/event-stream";

    @Test
    void toolsListShouldIncludeOurTools() {
        String initialize = """
                {
                  "jsonrpc": "2.0",
                  "id": 1,
                  "method": "initialize",
                  "params": {
                    "protocolVersion": "2025-03-26",
                    "capabilities": {},
                    "clientInfo": { "name": "JUnit", "version": "1.0" }
                  }
                }
                """;

        Response initResponse = given()
                .accept(MCP_ACCEPT)
                .contentType("application/json")
                .body(initialize)
                .post("/mcp");
        initResponse.then()
                .statusCode(200)
                .body(containsString("serverInfo"))
                .body(containsString("dev-toolkit-mcp"));
        String sessionId = initResponse.getHeader("Mcp-Session-Id");

        String toolsList = """
                {
                  "jsonrpc": "2.0",
                  "id": 2,
                  "method": "tools/list"
                }
                """;

        given()
                .accept(MCP_ACCEPT)
                .contentType("application/json")
                .header("Mcp-Session-Id", sessionId)
                .body(toolsList)
                .post("/mcp")
                .then()
                .statusCode(200)
                .body(containsString("toUpperSnakeCase"))
                .body(containsString("saveNote"));
    }
}

Run tests:

mvn test

This test proves two things:

The server speaks MCP over Streamable HTTP at POST /mcp
Tool discovery works and includes your annotated methods

The protocolVersion value in the initialize call matches the MCP spec revision for Streamable HTTP.

Add the MCP Server to Bob

You can now simply add the mcp server to bob’s configuration. Open the project local mcp settings (.bob/mcp.json) and add the following:

{
  "mcpServers": {
    "local-quarkus-mcp": {
      "url": "http://localhost:8080/mcp/sse",
      "headers": {
        "Content-Type": "application/json"
      }
    }
  }
}

And you can see the tools and resources we just implemented:

[

](https://substackcdn.com/image/fetch/$s_!1Yqj!,f_auto,q_auto:good,fl_progressive:steep/https%3A%2F%2Fsubstack-post-media.s3.amazonaws.com%2Fpublic%2Fimages%2F9427f830-4537-479c-89fb-479dfd7c7c4b_1420x1522.png)

Conclusion

You now have a real Quarkus MCP server that exposes tools, resources, resource templates, and prompts over Streamable HTTP. You can connect it to an MCP client like IBM Bob, inspect the JSON-RPC traffic, and test tool discovery automatically. The biggest win is that your integration logic is no longer IDE-specific.

Next step: add authentication and limits before you expose “write” tools in a shared environment.

Subscribe now

Exposing MCP from Legacy Java: Architecture Patterns That Actually Scale

Markus — Sun, 01 Mar 2026 11:59:52 +0000

Large Language Models are no longer just consumers of public APIs. With the Model Context Protocol (MCP), they become first-class clients of enterprise systems. This creates a new architectural challenge for the enterprise:

How do we expose MCP servers from legacy Jakarta EE applications without breaking the systems we rely on today?

This isn't about greenfield projects. This is about WildFly, Payara, WebLogic, SOAP endpoints, EJBs, and shared databases.

The key insight: MCP is not “just another API.” It changes traffic patterns, trust boundaries, and scaling behavior. Treating it like standard REST leads to failure modes you already know too well.

MCP Changes the Shape of Integration

Traditional integrations assume human-driven request rates and predictable shapes. MCP breaks these assumptions. An AI client can:

Invoke many tools in rapid succession.
Call internal operations humans never touch.
Generate load patterns that look like accidental DDoS.

Pattern 1: The MCP Gateway

The safest starting point is a dedicated MCP gateway implemented with a modern runtime like Quarkus.

The gateway terminates the MCP protocol and translates tool calls into legacy-friendly interactions (REST, SOAP, or even JCA).

Why this works:

Buffer Zone: AI traffic is isolated from fragile legacy logic.
Independent Scaling: You can scale the gateway without touching the WebLogic cluster.
Security: Policies are enforced before requests hit the core.

Integration Styles Inside the Gateway

1. Direct Adapter

A thin MCP tool mapped directly to an existing API.

Warning: This exposes legacy design mistakes to the LLM, leading to "token waste" and expensive prompts.

2. Semantic Aggregation Layer

Reshape legacy data into AI-friendly structures.

One MCP call produces a single semantic object. This hides complexity and provides a clean place for caching.

Pattern 2: Event-Driven MCP for Writes

Reads and writes behave differently under AI load. Writes deserve an asynchronous safety net.

This decouples AI timing from legacy processing. The trade-off? AI systems must accept eventual consistency.

Pattern 3: The In-Process MCP Server

Can you expose MCP directly from Jakarta EE? Yes, using LangChain4j-CDI.

When to use it:

The app is relatively modern.
You need direct access to internal EJBs not exposed via REST.
Time-to-market outweighs long-term architectural flexibility.

Pattern 4: The MCP Sidecar

A pragmatic compromise. The sidecar hosts the MCP endpoints and calls the legacy app locally.

This keeps MCP dependencies out of your 10-year-old pom.xml while keeping latency low.

Choosing Your Pattern

Pattern	Best For	Trade-off
Gateway	Security & Scale	Architectural Duplication
In-Process	Speed & Simplicity	High Coupling
Sidecar	Pragmatic Evolution	Infrastructure Complexity
Event-Driven	Resilience	Eventual Consistency

Summary

MCP turns legacy systems into conversational backends. That is powerful, but unforgiving. Success won't come to those who wire endpoints the fastest; it will come to those who treat AI traffic as a new class of integration with its own scaling and security modes.

This post was originally published on The Main Thread.

Why Senior Java Developers Are Using AI Coding Tools Wrong

Markus — Sun, 01 Mar 2026 11:59:00 +0000

At NDC Manchester 2025, Aleksander Stensby gave one of the more honest talks I’ve seen about AI-assisted coding. It wasn't a hype-filled demo reel; it was a practical breakdown of why tools like Claude Code, Cursor, and GitHub Copilot often disappoint experienced developers—and how to fix it.

The core idea is simple, but uncomfortable:

If AI produces bad code for you, it’s often a workflow problem, not a model problem.

Stensby calls the fix Compounding Engineering. This isn't about "prompt engineering." It’s about teaching your tools over time, the same way you onboard a junior developer to make them better week by week.

1. Treat the AI Like a Junior Intern

This is the mindset shift everything else depends on.

If a junior developer submits messy code, you don’t fire them. You review it, explain why it’s wrong, and show what “good” looks like. Most people don’t do this with AI. They accept the output, complain about “AI slop,” and move on.

The shift: Stop being a passive user. If you want better results, you must actively guide, correct, and push back. Your value doesn't disappear just because the code compiles; your value is in the mentorship of the tool.

2. Context Management: Less is More

Large language models (LLMs) don't have infinite attention. The mistake many Java devs make is trusting long-running, cluttered chats where the model eventually loses focus.

The fix is boring but effective:

Clear chats aggressively.
Store state explicitly.
Use Markdown for "Memory": Keep architecture notes, constraints, and rejected approaches in .md files. When starting a new session, re-load only the context that matters.

3. Rule Files are Living Knowledge Bases

Files like CLAUDE.md or .cursorrules aren't just for styling. They are training manuals.

When you fix a subtle bug or define a specific pattern for your Spring Boot service, don’t just fix it once. Update the rule file. Over time, the AI aligns with your specific standards, and those productivity gains compound.

4. The "Plan Mode" Strategy

If you let an AI jump straight into implementation, it will make architectural decisions for you—and some will be terrible.

Always ask for a plan first. Ask the model to outline steps, list assumptions, and ask clarifying questions. Planning is cheap; refactoring bad AI-generated architecture is expensive.

5. Your Job is Taste and Judgment

AI can produce working code fast. It cannot reliably produce good code.

Your value lies in knowing when something "feels" wrong even if the tests pass. Don’t just issue commands; have a conversation. Challenge the design choices. This back-and-forth is where quality emerges.

6. Practical Tips for Scalability

Atomic Tasks: Keep features small. Use GitHub issues or markdown task files.
Model Selection: Use fast/cheap models for boilerplate; use high-reasoning models for architecture.
MCP (Model Context Protocol): Use tools that allow the AI to actually "see" your docs, logs, and environment rather than just guessing.
The Safety Net: AI will break your code. Use Git checkpoints religiously. If rolling back is painful, you won't experiment—and that kills the upside of AI.

The Real Takeaway

AI coding tools are no longer just advanced autocomplete; they are collaborators. But collaborators need onboarding, feedback, and boundaries.

If you invest in that relationship, your results compound. If you don’t, you just get faster mediocrity.

This post was originally published on The Main Thread.

Local Image Generation in Java (Yes, Really): FLUX.2 + Quarkus + FFM

Markus — Sun, 15 Feb 2026 07:08:13 +0000

I got into image generation the normal way: Midjourney → “wow” → “how does this work?”

And then you try to run something locally and reality gently taps you on the shoulder with a brick:

Python-first stacks
CUDA assumptions
dependency graphs shaped like spaghetti
“works on my machine” energy… on someone else’s machine

If you’re on Apple Silicon (or any ARM box), you get the bonus level: “second-class citizen mode.”

Now add Java to the mix and the typical solution becomes:

“Run a Python server next to the JVM and pretend that’s fine.”

I’ve done it. It works. It also feels like you’re building a tiny distributed system just to generate a PNG.

So I tried a different approach:

Load the model into the JVM process. Call native inference directly. Keep lifecycle and memory under Java’s control.

No REST sidecar. No subprocess. No “hope the port is free.”

Just Quarkus + FLUX.2-klein-4B + Java FFM (Project Panama).

This is the teaser. The full tutorial (with all the sharp edges and the “why does this crash when it can’t find a shader file?” moments) is linked at the end.

The pitch: native inference as a first-class Java citizen

Most local-gen setups treat the model like an external service.

That’s fine until you care about:

startup time (loading weights every request… nope)
memory ownership
concurrency limits
predictable failure behavior
“what happens when it segfaults?”

With FFM, the JVM can load a shared library and call C functions directly in-process.

That means the Java app owns:

model lifecycle (load once, reuse)
native memory boundaries (explicit arenas, explicit lifetimes)
concurrency policy (single context, pooled contexts, whatever you decide)

Basically: the JVM stops being a client and becomes the host.

The core trick: don’t bind the whole C project

If you point jextract at a large C codebase and hope for the best, it will do what all great tools do:

It will teach you humility.

So the tutorial uses a pattern that keeps you sane:

Compile FLUX into a shared library (.dylib / .so)
Define a tiny wrapper header that exposes only what Java needs
Generate bindings for that header

Your wrapper becomes the stable “native boundary”:

init(model_path)
generate(ctx, prompt, output_path, width, height, steps, guidance, seed)
free(ctx)

No giant structs crossing the boundary. No leaking internal headers into Java-land. No “FFM archaeology.”

The other trick: the model is… large

The model download is about 16 GB.

That’s not a typo. That’s Tuesday.

Which is why the tutorial is very explicit about:

loading once at startup
keeping weights resident
exposing a simple REST endpoint that queues work safely

Also: yes, CPU inference can be viable if you pick the right model and resolution. The point is not “make it instant.”

The point is “make it predictable.”

A tiny taste: what the Java side looks like

The Java binding layer is intentionally boring (which is the highest compliment in this area):

allocate prompt + paths in a confined Arena
call flux_wrapper_generate(...)
return a file path
keep the native context alive until shutdown

And before we touch native code, we validate everything on the Java side, because:

Native code doesn’t throw exceptions. It throws your JVM out the window.

So the record that validates request parameters is not “nice to have.” It’s protective gear.

Why this is fun (and useful)

This isn’t about building a Midjourney competitor.

It’s about proving a bigger point:

Java can host modern native AI workloads locally
FFM is practical for real integrations
Quarkus is a great “container” for native inference (startup/shutdown, config, REST)

And once you have a local image generator in Java, a lot of other ideas get… tempting.

The full tutorial (all commands + code)

The teaser ends here. The full build includes:

compiling FLUX into a shared library for FFM
creating a minimal flux_wrapper.h/.c
generating bindings with jextract
patching library loading for macOS quirks
Quarkus service lifecycle (load once, reuse)
REST API to generate + serve the image
logs, timings, and “it finally worked!” payoff

👉 https://www.the-main-thread.com/p/java-local-image-generation-quarkus-ffm-flux

Warning: you may end up explaining to your team why your “Java service” now makes art.

AI-Assisted Development for Java Developers: The Specification Problem Is Back

Markus — Tue, 10 Feb 2026 07:08:14 +0000

AI-assisted development feels new.

The speed is new.
The fluency is new.
The confidence with which code appears in your editor is new.

The problem it exposes is not.

For more than sixty years, software engineering has struggled with one core challenge:

Translating human intent into machine execution.

AI did not solve this problem.
It reopened it — at scale.

If you are using GitHub Copilot, Claude, ChatGPT, or tools like IBM Bob in large Java systems, this matters more than you think.

The Real Issue: It’s Not About Code

In 1968, the NATO Software Engineering Conference described the “software crisis.” Projects were late, expensive, and unreliable.

The diagnosis was not “bad programmers.”

It was unclear intent.

Since then, we tried:

Waterfall
The V-Model
IEEE 830 specifications
UML
Agile
DevOps

Each wave tried to reduce ambiguity.

Each wave traded one failure mode for another.

Now AI enters the picture. And we are surprised that it also struggles with ambiguity?

AI generates code fast.
But it does not understand intent unless you make it explicit.

And unlike a junior developer, it does not hesitate when something is unclear. It guesses. Confidently.

1. Start With Constraints, Not Code

When you prompt an AI assistant, you are doing requirements engineering.

Loose prompts reproduce the oldest failure in our industry: underspecified intent.

Bad prompt:

“Refactor this service.”

Better prompt:

“Refactor this service to remove field injection, keep public APIs stable, and preserve current transaction behavior.”

Constraints are architecture.

Without them, correctness is luck.

2. Use AI for Mechanical Work, Not Architectural Judgment

History already taught us something important:

Design is contextual.

AI is excellent at:

Mechanical refactoring
API migrations
Pattern completion
Repetitive transformations

AI is bad at:

Long-term trade-offs
Domain boundaries
Organizational constraints
“Why” decisions

Senior developers use AI as a power tool.
Not as a decision engine.

Experience matters more now, not less.

3. Narrow the Scope or Invite Hallucination

Large, unconstrained requests fail for the same reason large requirement documents failed.

They mix:

Intent
Mechanism
Policy

Break work into small, reviewable units.

This already works for humans:

Small pull requests
Clear user stories
Focused tests

It also works for AI.

If you cannot describe the task in a few sentences without saying “and then…”, it is too big.

If you cannot explain how to verify the result, it is not ready for delegation.

4. Treat AI Output as a Draft

AI-generated code looks finished.

That is dangerous.

The V-Model taught us a painful distinction:

Verification: does it match the spec?
Validation: is the spec even correct?

AI can satisfy an implied spec perfectly — and still be wrong for your system.

Treat AI output like a pull request:

Is it understandable?
Is it testable?
Does it introduce hidden complexity?
Does it change behavior silently?

If it would not pass review from a human, it should not pass review from AI.

5. Externalize Context or Lose It

Most teams already suffer from tribal knowledge.

AI makes this worse.

If context lives only in people’s heads, the assistant will guess.

Externalize:

Architecture Decision Records (ADRs)
Coding rules
Constraints
Sensitive areas
Things that must never change

This is not about writing more documentation.

It is about writing the right documentation.

Good context answers:

What must not change?
What should be preferred?
Where is this system fragile?

Noise is harmful.
Exhaustiveness is not clarity.

6. Large Migrations Still Fail (Nothing Changed)

“AI couldn’t fix our migration.”

That sentence sounds modern. It is not.

Big-bang rewrites have failed for decades.

Why?

Because they delete undocumented knowledge:

Edge cases
Performance assumptions
Integration quirks
Historical trade-offs

AI does not fix that. It accelerates it.

Better approach:

Use AI for bounded, mechanical transformations.
Keep human judgment for structural redesign.
Blend modernization and selective rewriting.

Large systems evolve. They do not restart.

7. Agent Rules Are the New Specification

Traditional specs described what software should do.

Agent rules describe how work is allowed to happen.

Examples:

Do not change public APIs without approval.
Prefer existing domain types.
Avoid performance optimizations without benchmarks.
Do not introduce new frameworks.

These rules rarely appear in UML diagrams.
But they shape every real codebase.

Without explicit rules, AI will act inside invisible boundaries.

And invisible boundaries are always violated.

8. Shift Effort From Writing Code to Verifying Intent

AI made code cheap.

Verification is now the bottleneck.

This changes the cost structure of software development.

In the past:
Writing code was slow.

Now:
Reviewing and validating code is slow.

If you cannot clearly explain how to verify the result, do not delegate it to AI.

Speed without verification is delayed failure.

9. Use AI to Explain Code You Already Trust

Here is a powerful pattern:

Ask AI to explain working, production code.

If the explanation is weak or unclear, the intent was never explicit.

That is not an AI problem.

That is a specification problem.

Used this way, AI becomes a diagnostic tool.
It exposes ambiguity before it causes damage.

10. Optimize for Cognitive Load, Not Velocity

AI increases output speed.

Human cognition does not scale the same way.

Fast generation + constant decision-making = mental overload.

Signs of trouble:

Accepting changes too quickly
Moving on before understanding
Growing gap between code and comprehension
Quiet architectural drift

Introduce pauses.

Separate generation from review.

Keep tasks small.

Protect attention.

Sustainable engineering beats high-speed chaos.

Where This Is Going: Intent-Based Programming

AI did not solve the hardest problem in software.

It solved syntax.

The deeper problem remains:

Expressing human intent precisely enough that machines can execute it safely.

We are moving toward a world where:

Intent is primary
Constraints are explicit
Code becomes implementation detail
Verification becomes central

Java developers are well positioned for this shift.

We have lived through:

Heavy specification eras
Agile corrections
Test-driven development
Contract-based systems

The discipline that kept large Java systems alive before AI is the same discipline that makes AI safe today.

The Long Version

This article is a condensed version of a deeper piece where I:

Connect AI development to the 1968 software crisis
Explore specification failures across decades
Break down agent rules in detail
Discuss cognitive load and burnout in depth
Analyze the shift from code-writing to intent-design

If you are working on large Java systems and want the full argument:

👉 Read the complete article on The Main Thread:
https://www.the-main-thread.com/p/ai-assisted-development-java-specification-intent

AI did not end the software crisis.

It made ambiguity faster.

And that means intent matters more than ever.

Subscribe now

The End of “Python for Scripts, Java for Systems” (Maybe)

Markus — Sat, 07 Feb 2026 07:08:12 +0000

We all know the joke.

Python: read a file in two lines.
Java: create a project, write a pom.xml, summon public static void main, and hope the universe is in a good mood.

For years, my rule was simple:

Java for the enterprise. Python for the weekend.

Then I tried something that made me a little uncomfortable.

I rewrote a handful of “Python-only” scripts in modern Java.

Not as Maven projects. Not as Gradle builds. As scripts.

And… Java didn’t just keep up. It looked way too good.

The twist: Java wasn’t the problem. Java ceremony was.

Most “Java vs Python” debates are really “workflow vs workflow.”

Python feels like magic because the workflow is perfect:

Open a file
Write code
Run python script.py

Java historically fought you on step 1.

That’s the whole story.

So what happens if you remove the ceremony?

That’s where JBang + Java 21 enters.

JBang lets you run a single .java file like a script.
You can declare dependencies inside the file (yes, inside the file).
Java 21 gives you a much cleaner single-file entry point (no “Main class” boilerplate).

The new workflow looks like this:

Create script.java
Add a dependency as a comment
Run jbang script.java

That’s it.

And once you try it, the “Python for scripts, Java for systems” rule starts to wobble.

A tiny example: a web server in one file

Python has Flask. Java has… a surprising answer.

Save this as Server.java and run it with jbang Server.java.

///usr/bin/env jbang "$0" "$@" ; exit $?
//DEPS io.vertx:vertx-web:4.5.1

import io.vertx.core.Vertx;
import io.vertx.ext.web.Router;
import io.vertx.ext.web.handler.StaticHandler;

void main() {
    var vertx = Vertx.vertx();
    var router = Router.router(vertx);

    router.route("/*").handler(StaticHandler.create("."));

    vertx.createHttpServer()
        .requestHandler(router)
        .listen(8080);

    System.out.println("Server running on http://localhost:8080");
}

The important part is not Vert.x.

It’s the experience:

No project setup
No build file
No dependency wrangling
Just run it

That is the “Python feeling.” In Java.

The bigger point (and why this matters)

When you remove the startup pain, Java becomes a very different tool:

You can prototype in the same language you ship.
You can keep JVM performance and tooling.
You get types, refactoring, and strong libraries without the “rewrite cliff.”

But that’s also where the real debate begins.

Because Java doesn’t just “match Python.”
It shifts where you pay the cost: early friction vs long-term maintenance.

And modern Java changes that trade-off in a way most people haven’t internalized yet.

Want the real proof?

In the full article, I go further:

More “Python-only” tasks rewritten in modern Java
A short but brutal “prototype to production” reality check
Why types are surprisingly nice for scripts
A visual curve that explains why this shift feels so big

If you have not tried JBang lately, this will probably change your mental model.

👉 Read the full piece on The Main Thread:
https://www.the-main-thread.com/p/java-is-the-new-python-jbang-java-21

DEV Community: Markus

Build a Real-Time ISS Tracker with Quarkus, SSE, and Qute

Prerequisites

Project Setup

Implementation

Model the upstream API

Create the typed REST client

Convert latitude and longitude to map pixels

Build the application-scoped cache and stream source

Add the scheduler that polls Open Notify

Expose the JSON and SSE endpoints

Serve the Qute frontend

Add a readiness check

Configuration

Production Hardening

What happens when the upstream API is slow

SSE fan-out is cheap until it is not

Stale data is better than broken data

No auth does not mean no abuse surface

Verification

Run the application

Verify the JSON endpoint

Verify the readiness endpoint

Test the projection math

Test the REST resource

Test the scheduler

Conclusion

Quarkus MCP Testing for Java Developers: McpAssured + IBM Bob

Prerequisites

Project Setup

Implementation

Replace raw JSON-RPC plumbing with a real MCP test client

Test the toUpperSnakeCase tool like Bob would use it

Test base64Transform on both the success path and error path

Verify that the model-facing schema is actually useful

Test the saveNote stateful round-trip

Test resources and resource templates as first-class contracts

Test prompts like user-facing contracts

Add one full regression test as your CI gate

Capture raw MCP traffic when the bug only appears in an agent loop

Configuration

Production Hardening

What happens under agent-driven load

Concurrency and correctness are still your problem

Tool errors must be designed, not improvised

Tests lock in the contract

Schema quality is part of production quality

Raw snapshots are your replay mechanism

Verification

Conclusion

Mock External APIs in Quarkus with WireMock: A Hands-On Guide

Prerequisites

Project Setup

Implementation

Create the domain model

Create the carrier DTOs

Create the REST client

Create the service layer

Create the REST endpoint

Static JSON Stubs

Programmatic Stubs with @ConnectWireMock

WireMock Scenarios - Simulating State Changes

Response Templating

Fault Injection

Handle 503 Service Unavailable

Simulate a broken connection

Simulate latency

Production Hardening

What happens under load

Concurrency and ordering

Failure boundaries

Security and abuse cases

Request Verification

Verification

Run the tests

Inspect the WireMock admin endpoint

Conclusion

CLI Tools vs MCP: The Hidden Architecture Behind AI Agents

Why the API-Centric Model Starts to Hurt

Why Models Behave Like Terminal Users

Test the `toUpperSnakeCase` tool like Bob would use it

Test `base64Transform` on both the success path and error path

Test the `saveNote` stateful round-trip

Programmatic Stubs with `@ConnectWireMock`

Handle `503 Service Unavailable`