This is an automated email from the ASF dual-hosted git repository.
jamesbognar pushed a commit to branch docs
in repository https://gitbox.apache.org/repos/asf/juneau.git
The following commit(s) were added to refs/heads/docs by this push:
new 167f09f075 MCP docs: surface shared-core/per-revision adapter shape +
dependency-hygiene rationale
167f09f075 is described below
commit 167f09f0759f2fcedf6ec38163f09f53accc040a
Author: James Bognar <[email protected]>
AuthorDate: Wed Aug 12 10:10:05 2026 -0400
MCP docs: surface shared-core/per-revision adapter shape +
dependency-hygiene rationale
---
pages/topics/05.07.JuneauBeanMcp.md | 2 +-
pages/topics/11.00.JuneauMcp.md | 2 +-
pages/topics/11.02.JuneauMcpChoosingSetup.md | 24 ++++++++++++++++++++++++
pages/topics/11.04.JuneauRestServerMcp.md | 2 +-
pages/topics/11.05.JuneauRestClientMcp.md | 2 +-
src/pages/about.md | 20 ++++++++++----------
6 files changed, 38 insertions(+), 14 deletions(-)
diff --git a/pages/topics/05.07.JuneauBeanMcp.md
b/pages/topics/05.07.JuneauBeanMcp.md
index eb1cddd219..cc5e6f9802 100644
--- a/pages/topics/05.07.JuneauBeanMcp.md
+++ b/pages/topics/05.07.JuneauBeanMcp.md
@@ -4,7 +4,7 @@ slug: JuneauBeanMcp
---
-The `juneau-bean-mcp-v20250618` module provides Java beans modelling the
[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) `2025-06-18`
wire format. It's paired with a separate, revision-neutral module,
`juneau-bean-jsonrpc`, which carries the underlying JSON-RPC 2.0 envelope.
+The `juneau-bean-mcp-v20250618` module provides Java beans modelling the
[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) `2025-06-18`
wire format. It's paired with a separate, revision-neutral module,
`juneau-bean-jsonrpc`, which carries the underlying JSON-RPC 2.0 envelope, and
with a `2026-07-28` sibling, `juneau-bean-mcp-v20260728`. See [Choosing your
MCP
setup](/docs/topics/JuneauMcpChoosingSetup#module-shape-3-shared-cores-6-per-revision-adapters)
for why the two re [...]
## Overview
diff --git a/pages/topics/11.00.JuneauMcp.md b/pages/topics/11.00.JuneauMcp.md
index 711cefb34f..3d00ba5fa5 100644
--- a/pages/topics/11.00.JuneauMcp.md
+++ b/pages/topics/11.00.JuneauMcp.md
@@ -6,7 +6,7 @@ slug: JuneauMcp
Juneau provides both server-side and client-side support for the [Model
Context Protocol (MCP)](https://modelcontextprotocol.io/), a JSON-RPC 2.0
protocol that lets AI assistants and agents discover and invoke external
**tools**, **prompts**, and **resources**.
-Two protocol revisions are supported side-by-side as separate, revision-bound
Maven modules: `2025-06-18` and `2026-07-28` (the current revision). A
client/server pair picks one revision at compile time — see [Choosing your MCP
setup](/docs/topics/JuneauMcpChoosingSetup) for the full comparison.
+Two protocol revisions are supported side-by-side as separate, revision-bound
Maven modules: `2025-06-18` and `2026-07-28` (the current revision). A
client/server pair picks one revision at compile time — see [Choosing your MCP
setup](/docs/topics/JuneauMcpChoosingSetup) for the full comparison, why the
MCP ecosystem is 9 artifacts (3 shared cores + 6 per-revision adapters) rather
than 6 independent ones, and why the two revisions are maintained differently
going forward.
## Where to start
diff --git a/pages/topics/11.02.JuneauMcpChoosingSetup.md
b/pages/topics/11.02.JuneauMcpChoosingSetup.md
index 41ea7989ec..50b4d24ec7 100644
--- a/pages/topics/11.02.JuneauMcpChoosingSetup.md
+++ b/pages/topics/11.02.JuneauMcpChoosingSetup.md
@@ -5,6 +5,30 @@ slug: JuneauMcpChoosingSetup
Three independent decisions determine which classes you extend/implement and
which Maven artifacts you depend on. They can be mixed freely — e.g.
`2026-07-28` + mixin + Spring Boot is a perfectly normal combination.
+## Module shape: 3 shared cores, 6 per-revision adapters
+
+The MCP ecosystem is **9 Maven artifacts, not 6 independent ones**. Three of
them are revision-neutral **cores** — each has zero compile-time knowledge of
`2025-06-18` vs `2026-07-28` — and each core carries two thin **adapter**
modules on top, one per protocol revision:
+
+```
+juneau-bean-jsonrpc JSON-RPC 2.0 envelope (revision-neutral)
+├── juneau-bean-mcp-v20250618 2025-06-18 wire beans
+└── juneau-bean-mcp-v20260728 2026-07-28 wire beans
+
+juneau-rest-server-mcp server dispatch core (revision-neutral)
+├── juneau-rest-server-mcp-v20250618
+└── juneau-rest-server-mcp-v20260728
+
+juneau-rest-client-mcp client core (revision-neutral)
+├── juneau-rest-client-mcp-v20250618
+└── juneau-rest-client-mcp-v20260728
+```
+
+The three decisions below only concern which **adapter** coordinate you pick
per side — the neutral cores come along transitively; you don't depend on or
configure them directly.
+
+**Why a separate artifact per revision, instead of one artifact with a runtime
revision switch:** Maven/Gradle dependency resolution happens at build time, so
keeping a `2025-06-18`-only consumer off `2026-07-28`-only dependencies has to
be a compile-time artifact choice, not a runtime flag. The `2026-07-28` server
adapter alone pulls in `juneau-rest-server-reactive` (reactive-streams SSE, for
subscriptions), `juneau-rest-server-auth-oauth` (OAuth 2.1), and
`juneau-rest-server-auth-jwt` [...]
+
+**Why the two adapters keep diverging in size rather than converging:**
`2025-06-18` is maintained for bug fixes and spec-correctness only,
indefinitely. All new MCP capability work — Multi-Round-Trip Requests,
subscriptions, sampling, elicitation, OAuth 2.1 hardening, cache hints,
structured tool output, resource templates, `_meta`/trace-context propagation —
lands only in `2026-07-28`. The capability table below reflects that split as
of today; expect the gap to widen, not close.
+
## 1. Which protocol revision: `2025-06-18` vs `2026-07-28`
A client/server pair is revision-bound at compile time — pick one adapter
module per side. There is no automatic runtime revision switching.
diff --git a/pages/topics/11.04.JuneauRestServerMcp.md
b/pages/topics/11.04.JuneauRestServerMcp.md
index 33a6298df8..e58c9ccc12 100644
--- a/pages/topics/11.04.JuneauRestServerMcp.md
+++ b/pages/topics/11.04.JuneauRestServerMcp.md
@@ -10,7 +10,7 @@ New to MCP in Juneau? Start with the [MCP
Quickstart](/docs/topics/JuneauMcpQuic
[`juneau-examples-mcp`](https://github.com/apache/juneau/tree/master/juneau-examples/juneau-examples-mcp)
is a complete, copy-me Maven module exercising every major surface on this
page — tools, elicitation/MRTR, prompts + completion, resources + resource
templates, and subscriptions — against a tiny in-memory "notes" service,
targeting revision `2026-07-28`. It ships as a downloadable project zip in the
Apache release. See [MCP
Recipes](/docs/topics/JuneauMcpRecipes#full-example-juneau- [...]
:::
-`juneau-rest-server-mcp` is a **revision-neutral core** for exposing a [Model
Context Protocol (MCP)](https://modelcontextprotocol.io/) JSON-RPC endpoint on
`juneau-rest-server`. On its own it has zero compile-time knowledge of any MCP
protocol revision; a protocol revision is supplied by a separate adapter
module. Today that's **`juneau-rest-server-mcp-v20250618`**, which binds the
core to the `2025-06-18` wire beans in
[`juneau-bean-mcp-v20250618`](/docs/topics/JuneauBeanMcp). This pag [...]
+`juneau-rest-server-mcp` is a **revision-neutral core** for exposing a [Model
Context Protocol (MCP)](https://modelcontextprotocol.io/) JSON-RPC endpoint on
`juneau-rest-server`. On its own it has zero compile-time knowledge of any MCP
protocol revision; a protocol revision is supplied by a separate adapter module
— `juneau-rest-server-mcp-v20250618` or `juneau-rest-server-mcp-v20260728`.
This page covers all three modules. See [Choosing your MCP
setup](/docs/topics/JuneauMcpChoosingSetu [...]
## Overview
diff --git a/pages/topics/11.05.JuneauRestClientMcp.md
b/pages/topics/11.05.JuneauRestClientMcp.md
index f82476ee29..cc24aad9c9 100644
--- a/pages/topics/11.05.JuneauRestClientMcp.md
+++ b/pages/topics/11.05.JuneauRestClientMcp.md
@@ -10,7 +10,7 @@ New to MCP in Juneau? Start with the [MCP
Quickstart](/docs/topics/JuneauMcpQuic
[`juneau-examples-mcp`](https://github.com/apache/juneau/tree/master/juneau-examples/juneau-examples-mcp)
is a complete, copy-me Maven module pairing a `2026-07-28` MCP server with a
guided `McpClient` walkthrough (`ExampleClient`) that exercises every client
call covered by this reference — discovery, tool calls, resource/template
reads, completions, prompts, subscriptions, and an elicitation round-trip. It
ships as a downloadable project zip in the Apache release. See [MCP
Recipes](/do [...]
:::
-`juneau-rest-client-mcp` is the revision-neutral MCP client core built on
`juneau-rest-client`, with two dated adapters:
`juneau-rest-client-mcp-v20250618` and `juneau-rest-client-mcp-v20260728`.
+`juneau-rest-client-mcp` is the revision-neutral MCP client core built on
`juneau-rest-client`, with two dated adapters:
`juneau-rest-client-mcp-v20250618` and `juneau-rest-client-mcp-v20260728`. See
[Choosing your MCP
setup](/docs/topics/JuneauMcpChoosingSetup#module-shape-3-shared-cores-6-per-revision-adapters)
for why the two adapters are separate artifacts and why `v20260728` keeps
growing larger than `v20250618` rather than the two converging.
## Overview
diff --git a/src/pages/about.md b/src/pages/about.md
index 92b4c85b2e..80efa58082 100644
--- a/src/pages/about.md
+++ b/src/pages/about.md
@@ -26,7 +26,7 @@ Not sure if Juneau is right for your project? Check out our
detailed [Why Choose
## Ecosystem
-The Juneau ecosystem consists of the following parts:
+The Juneau ecosystem consists of the following parts. A few rows are **grouped
families** rather than fully independent modules — a shared, revision- or
spec-neutral core plus multiple thin sibling modules built on it (the
JSON-RPC/MCP core-plus-adapter rows below are one example, alongside the
pre-existing OpenAPI/Swagger spec-version pair); each row's description says
how it relates to its siblings, and [Choosing your MCP
setup](/docs/topics/JuneauMcpChoosingSetup#module-shape-3-shared [...]
| Component | Description |
|-----------|-------------|
@@ -43,10 +43,10 @@ The Juneau ecosystem consists of the following parts:
| [juneau-bean-html5](/docs/topics/JuneauBeanHtml5) | DTOs for HTML5 elements.
|
| [juneau-bean-jsonapi](/docs/topics/JuneauBeanJsonApi) | DTOs for the
JSON:API specification. |
| [juneau-bean-jsonpatch](/docs/topics/JuneauBeanJsonPatch) | DTOs for JSON
Patch (RFC 6902). |
-| [juneau-bean-jsonrpc](/docs/topics/JuneauBeanJsonRpc) | Revision-neutral
JSON-RPC 2.0 envelope DTOs
(`JsonRpcRequest`/`JsonRpcResponse`/`JsonRpcError`/`McpException`) shared by
the MCP bean/client/server modules. |
+| [juneau-bean-jsonrpc](/docs/topics/JuneauBeanJsonRpc) | Revision-neutral
JSON-RPC 2.0 envelope DTOs
(`JsonRpcRequest`/`JsonRpcResponse`/`JsonRpcError`/`McpException`) — the core
the two `juneau-bean-mcp-v2*` adapter rows below are built on. |
| [juneau-bean-jsonschema](/docs/topics/JuneauBeanJsonSchema) | DTOs for JSON
Schema. |
-| [juneau-bean-mcp-v20250618](/docs/topics/JuneauBeanMcp) | DTOs for the MCP
`2025-06-18` wire format — tool/prompt/resource descriptors, capability beans,
and polymorphic content types. |
-|
[juneau-bean-mcp-v20260728](/docs/topics/JuneauBeanMcp#mcp-2026-07-28-cache-hints-resource-templates)
| DTOs for the MCP `2026-07-28` wire format — adds cache hints and resource
templates on top of the 2025-06-18 baseline. |
+| [juneau-bean-mcp-v20250618](/docs/topics/JuneauBeanMcp) | Adapter on
`juneau-bean-jsonrpc` above: DTOs for the MCP `2025-06-18` wire format —
tool/prompt/resource descriptors, capability beans, and polymorphic content
types. |
+|
[juneau-bean-mcp-v20260728](/docs/topics/JuneauBeanMcp#mcp-2026-07-28-cache-hints-resource-templates)
| Adapter on `juneau-bean-jsonrpc` above: DTOs for the MCP `2026-07-28` wire
format — adds cache hints and resource templates on top of the 2025-06-18
baseline. |
| [juneau-bean-openapi-v3](/docs/topics/JuneauBeanOpenApi3) | DTOs for the
OpenAPI v3 specification. |
| [juneau-bean-rfc7807](/docs/topics/JuneauBeanRfc7807) | DTOs for RFC 7807
Problem Details. |
| [juneau-bean-swagger-v2](/docs/topics/JuneauBeanSwagger2) | DTOs for the
Swagger/OpenAPI v2 specification. |
@@ -55,9 +55,9 @@ The Juneau ecosystem consists of the following parts:
| [juneau-rest-common-classic](/docs/topics/JuneauRestCommon) | Apache
HttpClient 4.5–compatible HTTP type facades
(`org.apache.juneau.http.classic.*`) for the classic REST client/server stack. |
| [juneau-rest-server](/docs/topics/JuneauRestServer) | Annotation-driven REST
server with automatic OpenAPI/Swagger docs and content negotiation. |
| [juneau-rest-server-springboot](/docs/topics/JuneauRestServerSpringboot) |
Spring Boot auto-configuration for juneau-rest-server. |
-| [juneau-rest-server-mcp](/docs/topics/JuneauRestServerMcp) | Model Context
Protocol (MCP) server endpoint support. |
-|
[juneau-rest-server-mcp-v20250618](/docs/topics/JuneauRestServerMcp#getting-started)
| MCP `2025-06-18` protocol adapter for juneau-rest-server-mcp. |
-|
[juneau-rest-server-mcp-v20260728](/docs/topics/JuneauRestServerMcp#configuring-the-endpoint-mcpoptions-mcp-2026-07-28)
| MCP `2026-07-28` protocol adapter — adds OAuth 2.1 resource-server support,
cache hints, and multi-round-trip requests. |
+| [juneau-rest-server-mcp](/docs/topics/JuneauRestServerMcp) |
Revision-neutral Model Context Protocol (MCP) server dispatch core — the two
rows below are its per-revision adapters. |
+|
[juneau-rest-server-mcp-v20250618](/docs/topics/JuneauRestServerMcp#getting-started)
| MCP `2025-06-18` protocol adapter for juneau-rest-server-mcp above. |
+|
[juneau-rest-server-mcp-v20260728](/docs/topics/JuneauRestServerMcp#configuring-the-endpoint-mcpoptions-mcp-2026-07-28)
| MCP `2026-07-28` protocol adapter for juneau-rest-server-mcp above — adds
OAuth 2.1 resource-server support, cache hints, and multi-round-trip requests. |
| [juneau-rest-server-auth-jwt](/docs/topics/AuthFilterFramework) | JWT
authentication filter. |
| [juneau-rest-server-auth-saml](/docs/topics/SamlAuthSupport) | SAML 2.0
authentication filter. |
| [juneau-rest-server-auth-oauth](/docs/topics/OAuthAuthSupport) | OAuth 2.0 /
OIDC authentication and token introspection filter. |
@@ -79,9 +79,9 @@ The Juneau ecosystem consists of the following parts:
|
[juneau-rest-client-apache-httpclient-50](/docs/topics/RestClientApacheHttpClient50)
| Adapter for Apache HttpClient 5.x. |
| [juneau-rest-client-okhttp](/docs/topics/RestClientOkHttp) | Adapter for
OkHttp. |
| [juneau-rest-client-jetty](/docs/topics/RestClientJetty) | Adapter for Jetty
HTTP client. |
-| [juneau-rest-client-mcp](/docs/topics/JuneauRestClientMcp) | Model Context
Protocol (MCP) client support. |
-|
[juneau-rest-client-mcp-v20250618](/docs/topics/JuneauRestClientMcp#revision-binding)
| MCP `2025-06-18` protocol adapter for juneau-rest-client-mcp. |
-|
[juneau-rest-client-mcp-v20260728](/docs/topics/JuneauRestClientMcp#elicitation-mcp-2026-07-28-sep-2322)
| MCP `2026-07-28` protocol adapter — adds elicitation, OAuth 2.1 auth
support, and response caching. |
+| [juneau-rest-client-mcp](/docs/topics/JuneauRestClientMcp) |
Revision-neutral Model Context Protocol (MCP) client core — the two rows below
are its per-revision adapters. |
+|
[juneau-rest-client-mcp-v20250618](/docs/topics/JuneauRestClientMcp#revision-binding)
| MCP `2025-06-18` protocol adapter for juneau-rest-client-mcp above. |
+|
[juneau-rest-client-mcp-v20260728](/docs/topics/JuneauRestClientMcp#elicitation-mcp-2026-07-28-sep-2322)
| MCP `2026-07-28` protocol adapter for juneau-rest-client-mcp above — adds
elicitation, OAuth 2.1 auth support, and response caching. |
|
[juneau-rest-client-mcp-auth](/docs/topics/JuneauRestClientMcp#oauth-21-authorization-juneau-rest-client-mcp-auth)
| OAuth 2.1 client-side authorization support for juneau-rest-client-mcp (DCR,
PKCE, protected-resource metadata discovery). |
| [juneau-rest-mock](/docs/topics/JuneauRestMock) | Serverless REST mock
client for unit testing without a servlet container. |
| **juneau-microservice** | |
