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 c965094c06 MCP resource-template reads + completion/complete across
both revisions
c965094c06 is described below
commit c965094c065434c73aa0d832cb654788a1c2cae8
Author: James Bognar <[email protected]>
AuthorDate: Fri Jul 31 15:04:08 2026 -0400
MCP resource-template reads + completion/complete across both revisions
Cross-revision (v1 2025-06-18 + v2 2026-07-28) resource-template support:
template-backed resources/read dispatch and completion/complete, built on
C2's neutral McpResourceTemplateSpec scaffolding. Adds a hand-rolled,
revision-neutral RFC 6570 reverse-matcher (reversible subset of levels 2-4,
most-specific-wins/registration-order tiebreak) and a neutral completion
domain (per-argument prompt completers, per-variable template completers).
Backfills v1's resources/templates/list listing.
Relocates the bounded-JSON walker to juneau-commons as JsonValueSafety,
shared across revisions instead of duplicated per adapter.
Eclipse + SonarQube cleanup across the MCP modules, neutral core, commons,
and integration-tests.
Renames the four dated MCP bean/adapter modules to the
-v20250618/-v20260728 coordinate form.
TODO-312c4.
---
artifact-paths.json | 8 +-
pages/release-notes/10.0.0.md | 41 +++++++---
pages/topics/01.02.WhyJuneau.md | 2 +-
pages/topics/05.00.JuneauBean.md | 2 +-
pages/topics/05.07.JuneauBeanMcp.md | 56 +++++++++++--
pages/topics/05.12.JuneauBeanJsonRpc.md | 8 +-
pages/topics/11.JuneauRestServerMcp.md | 137 ++++++++++++++++++++++++++++++--
pages/topics/23.05.JuneauShadedAll.md | 4 +-
sidebars.ts | 2 +-
9 files changed, 220 insertions(+), 40 deletions(-)
diff --git a/artifact-paths.json b/artifact-paths.json
index a5be25db64..e7a3880159 100644
--- a/artifact-paths.json
+++ b/artifact-paths.json
@@ -9,8 +9,8 @@
"juneau-bean-jsonpatch": "juneau-bean/juneau-bean-jsonpatch",
"juneau-bean-jsonrpc": "juneau-bean/juneau-bean-jsonrpc",
"juneau-bean-jsonschema": "juneau-bean/juneau-bean-jsonschema",
- "juneau-bean-mcp-2025-06-18": "juneau-bean/juneau-bean-mcp-2025-06-18",
- "juneau-bean-mcp-2026-07-28": "juneau-bean/juneau-bean-mcp-2026-07-28",
+ "juneau-bean-mcp-v20250618": "juneau-bean/juneau-bean-mcp-v20250618",
+ "juneau-bean-mcp-v20260728": "juneau-bean/juneau-bean-mcp-v20260728",
"juneau-bean-openapi-v3": "juneau-bean/juneau-bean-openapi-v3",
"juneau-bean-rfc7807": "juneau-bean/juneau-bean-rfc7807",
"juneau-bean-swagger-v2": "juneau-bean/juneau-bean-swagger-v2",
@@ -55,8 +55,8 @@
"juneau-rest-server-auth-saml": "juneau-rest/juneau-rest-server-auth-saml",
"juneau-rest-server-management-logging":
"juneau-rest/juneau-rest-server-management-logging",
"juneau-rest-server-mcp": "juneau-rest/juneau-rest-server-mcp",
- "juneau-rest-server-mcp-2025-06-18":
"juneau-rest/juneau-rest-server-mcp-2025-06-18",
- "juneau-rest-server-mcp-2026-07-28":
"juneau-rest/juneau-rest-server-mcp-2026-07-28",
+ "juneau-rest-server-mcp-v20250618":
"juneau-rest/juneau-rest-server-mcp-v20250618",
+ "juneau-rest-server-mcp-v20260728":
"juneau-rest/juneau-rest-server-mcp-v20260728",
"juneau-rest-server-metrics-micrometer":
"juneau-rest/juneau-rest-server-metrics-micrometer",
"juneau-rest-server-rdf": "juneau-rest/juneau-rest-server-rdf",
"juneau-rest-server-reactive": "juneau-rest/juneau-rest-server-reactive",
diff --git a/pages/release-notes/10.0.0.md b/pages/release-notes/10.0.0.md
index 209255a3ff..633feb1fa5 100644
--- a/pages/release-notes/10.0.0.md
+++ b/pages/release-notes/10.0.0.md
@@ -693,12 +693,12 @@ Juneau's first [Model Context
Protocol](https://modelcontextprotocol.io/) suppor
- **`juneau-bean-jsonrpc`** — revision-neutral JSON-RPC 2.0 envelope beans.
- **`juneau-rest-server-mcp`** — revision-neutral REST-server core
(tool/prompt/resource registry, dispatch contract, pagination, the two HTTP
entry points), with zero compile-time knowledge of any MCP protocol revision.
-- **`juneau-bean-mcp-2025-06-18`** — MCP revision `2025-06-18` wire beans
(renamed from the withdrawn draft's `juneau-bean-mcp`).
-- **`juneau-rest-server-mcp-2025-06-18`** — the `2025-06-18` REST-server
adapter that binds the neutral core to those wire beans; this is the module
application code depends on to actually expose an MCP endpoint today.
+- **`juneau-bean-mcp-v20250618`** — MCP revision `2025-06-18` wire beans
(renamed from the withdrawn draft's `juneau-bean-mcp`).
+- **`juneau-rest-server-mcp-v20250618`** — the `2025-06-18` REST-server
adapter that binds the neutral core to those wire beans; this is the module
application code depends on to actually expose an MCP endpoint today.
### `juneau-bean-jsonrpc` (new module)
-A new bean module, `juneau-bean-jsonrpc`, models the revision-neutral JSON-RPC
2.0 envelope as Juneau `@Marshalled` POJOs. It carries no MCP-specific
knowledge — it depends on `juneau-marshall` only — and is the shared framing
layer beneath protocol-specific bean modules such as
`juneau-bean-mcp-2025-06-18`.
+A new bean module, `juneau-bean-jsonrpc`, models the revision-neutral JSON-RPC
2.0 envelope as Juneau `@Marshalled` POJOs. It carries no MCP-specific
knowledge — it depends on `juneau-marshall` only — and is the shared framing
layer beneath protocol-specific bean modules such as
`juneau-bean-mcp-v20250618`.
### Coverage
@@ -727,7 +727,7 @@ JsonRpcResponse err = JsonRpcResponse.errorResponse(1,
-32601, "Method not found
### `juneau-rest-server-mcp` (re-layered into a revision-neutral core)
-`juneau-rest-server-mcp` has been re-layered from a single-revision
implementation into a **revision-neutral core** with zero compile-time
knowledge of any MCP protocol revision — enforced by a `maven-enforcer`
banned-dependency rule that fails the build if this module ever depends on
`juneau-bean-mcp-*` or `juneau-rest-server-mcp-*`. A protocol revision is
supplied by an `McpRevision` implementation living in its own adapter module
(see `juneau-rest-server-mcp-2025-06-18` below); a cons [...]
+`juneau-rest-server-mcp` has been re-layered from a single-revision
implementation into a **revision-neutral core** with zero compile-time
knowledge of any MCP protocol revision — enforced by a `maven-enforcer`
banned-dependency rule that fails the build if this module ever depends on
`juneau-bean-mcp-*` or `juneau-rest-server-mcp-*`. A protocol revision is
supplied by an `McpRevision` implementation living in its own adapter module
(see `juneau-rest-server-mcp-v20250618` below); a consu [...]
### New Classes
@@ -746,9 +746,9 @@ JsonRpcResponse err = JsonRpcResponse.errorResponse(1,
-32601, "Method not found
See [juneau-rest-server-mcp](/docs/topics/JuneauRestServerMcp) for the full
topic.
-### `juneau-bean-mcp-2025-06-18` (renamed from `juneau-bean-mcp`)
+### `juneau-bean-mcp-v20250618` (renamed from `juneau-bean-mcp`)
-The bean module has been renamed from `juneau-bean-mcp` to
`juneau-bean-mcp-2025-06-18` (package `org.apache.juneau.bean.mcp.v20250618`)
as part of the re-layering above — the name change makes room for a future
sibling module under the same `org.apache.juneau.bean.mcp` namespace should a
later MCP protocol revision need one. The module still models the MCP
`2025-06-18` wire format as Juneau `@Marshalled` POJOs that round-trip cleanly
through any Juneau serializer/parser (JSON, JSON5, Me [...]
+The bean module has been renamed from `juneau-bean-mcp` to
`juneau-bean-mcp-v20250618` (package `org.apache.juneau.bean.mcp.v20250618`) as
part of the re-layering above — the name change makes room for a future sibling
module under the same `org.apache.juneau.bean.mcp` namespace should a later MCP
protocol revision need one. The module still models the MCP `2025-06-18` wire
format as Juneau `@Marshalled` POJOs that round-trip cleanly through any Juneau
serializer/parser (JSON, JSON5, Mes [...]
### Coverage
@@ -787,11 +787,11 @@ String wire = JsonSerializer.DEFAULT.serialize(req);
JsonRpcRequest back = JsonParser.DEFAULT.parse(wire, JsonRpcRequest.class);
```
-See [juneau-bean-mcp-2025-06-18](/docs/topics/JuneauBeanMcp) for the full
topic.
+See [juneau-bean-mcp-v20250618](/docs/topics/JuneauBeanMcp) for the full topic.
-### `juneau-rest-server-mcp-2025-06-18` (new module)
+### `juneau-rest-server-mcp-v20250618` (new module)
-A new adapter module, `juneau-rest-server-mcp-2025-06-18` (package
`org.apache.juneau.rest.server.mcp.v20250618`), binds the revision-neutral
`juneau-rest-server-mcp` core to the `2025-06-18` wire beans in
`juneau-bean-mcp-2025-06-18`.
+A new adapter module, `juneau-rest-server-mcp-v20250618` (package
`org.apache.juneau.rest.server.mcp.v20250618`), binds the revision-neutral
`juneau-rest-server-mcp` core to the `2025-06-18` wire beans in
`juneau-bean-mcp-v20250618`.
### New Classes
@@ -881,17 +881,32 @@ Returning `null` (the default) leaves capabilities
auto-derived from the registe
Requests without an `id` are treated as JSON-RPC notifications: handlers run,
exceptions are swallowed, and `dispatch()` returns `null`. The REST
servlet/mixin writes an empty body so transports can map this to `204 No
Content`.
-See [juneau-rest-server-mcp-2025-06-18](/docs/topics/JuneauRestServerMcp) for
the full topic.
+See [juneau-rest-server-mcp-v20250618](/docs/topics/JuneauRestServerMcp) for
the full topic.
### MCP `2026-07-28` — cache hints (SEP-2549) + `resources/templates/list`
-The `2026-07-28` bean and REST-server adapter modules
(`juneau-bean-mcp-2026-07-28`, `juneau-rest-server-mcp-2026-07-28`) add
[SEP-2549](https://modelcontextprotocol.io/) cache hints and a
resource-template listing endpoint. Both are `2026-07-28`-only — the neutral
`juneau-rest-server-mcp` core and the `2025-06-18` adapter are untouched.
+The `2026-07-28` bean and REST-server adapter modules
(`juneau-bean-mcp-v20260728`, `juneau-rest-server-mcp-v20260728`) add
[SEP-2549](https://modelcontextprotocol.io/) cache hints and a
resource-template listing endpoint. Both are `2026-07-28`-only — the neutral
`juneau-rest-server-mcp` core and the `2025-06-18` adapter are untouched.
- **Cache hints** — `tools/list`, `prompts/list`, `resources/list`,
`resources/templates/list`, and `resources/read` results can each carry a
nullable, top-level `ttlMs` (`Integer`) and `cacheScope` (`McpCacheScope`:
`public`/`private`) pair, via the new `CacheableResult<T>` CRTP base that
`ListToolsResult`, `ListPromptsResult`, `ListResourcesResult`,
`ListResourceTemplatesResult`, and `ReadResourceResult` all extend. Fields are
omitted from the wire when unset — there is no forced defau [...]
- **`resources/templates/list`** — a new v2-only endpoint
(`McpMethods.RESOURCES_TEMPLATES_LIST`) listing `ResourceTemplate` descriptors
(`uriTemplate`, `name`, `title`, `description`, `mimeType`) registered via the
neutral `McpServerConfig.addResourceTemplate(McpResourceTemplateSpec)`.
Registering at least one resource template auto-derives the `resources`
capability, same as resources. The pre-built neutral `McpResourceTemplateSpec`
descriptor and this endpoint are designed for reuse b [...]
- **Static, adapter-owned configuration only** — a server configures cache
hints once, at construction time, via the new `McpCacheConfig`/`McpCacheHint`
types (`createCacheConfig()` on `McpRestServlet`, `cacheConfig()` on
`McpEndpoint`). Precedence is atomic per list method (method-specific hint,
else a shared default, else no cache fields) and, for `resources/read`, adds an
exact-URI override map ahead of a `resourcesRead` default. Juneau does **not**
implement client-side caching, does [...]
-See
[juneau-rest-server-mcp](/docs/topics/JuneauRestServerMcp#cache-hints-mcp-2026-07-28-sep-2549)
and
[juneau-bean-mcp-2026-07-28](/docs/topics/JuneauBeanMcp#mcp-2026-07-28-cache-hints-resource-templates)
for the full topics.
+See
[juneau-rest-server-mcp](/docs/topics/JuneauRestServerMcp#cache-hints-mcp-2026-07-28-sep-2549)
and
[juneau-bean-mcp-v20260728](/docs/topics/JuneauBeanMcp#mcp-2026-07-28-cache-hints-resource-templates)
for the full topics.
+
+### MCP — cross-revision resource-template reads and completions
(`completion/complete`)
+
+Building on the `resources/templates/list` endpoint above, 10.0.0 makes
registered resource templates **executable** through ordinary `resources/read`,
and makes prompt arguments and resource-template variables **completable**
through the new `completion/complete` method — on both `2025-06-18` and
`2026-07-28`. This closes `2025-06-18`'s prior resource-template gap (it
previously had no `ResourceTemplate`/`ListResourceTemplatesResult` beans, no
`resources/templates/list`, and no way to s [...]
+
+- **`McpResourceTemplateHandler` (new, revision-neutral core)** — pairs the
existing `McpResourceTemplateSpec` descriptor with a variable-aware
`read(String uri, Map<String,String> variables, BeanStore ctx)` and an optional
per-variable `completer(String variableName)`. `McpServerConfig`'s primary
resource-template registration is now handler-based
(`getResourceTemplates()`/`setResourceTemplates(List<McpResourceTemplateHandler>)`/`addResourceTemplate(McpResourceTemplateHandler...)`);
the [...]
+- **A dependency-free RFC 6570 reverse matcher (new, `McpUriTemplateMatcher`,
revision-neutral core)** — reliably reverse-matches one narrow, invertible
subset of RFC 6570 (simple/reserved/fragment scalars, path/label segments,
ordered query expressions) and extracts decoded, immutable, insertion-ordered
variables. This does **not** cover every legal RFC 6570 form and Juneau does
**not** perform any URI-template expansion (client-side or otherwise):
exploded/prefix/matrix/multi-variable/ [...]
+- **Neutral completion domain and SPI (new)** — `McpCompleter`
(`@FunctionalInterface`), `McpCompletionRef`, `McpCompletionRequest`, and
`McpCompletionResult` model a `completion/complete` request/result independent
of either dated wire format. `McpPromptArgument` gains a nullable, non-wire
`completer` property (its existing `name`/`description`/`required` fields are
unchanged and remain the sole wire-mapped fields). Unknown/uncompletable
completion targets return a successful empty comp [...]
+- **`2025-06-18` backfill** — adds `ResourceTemplate` and
`ListResourceTemplatesResult` beans (the same five/two-field shape `2026-07-28`
already had, minus cache fields), `McpMethods.RESOURCES_TEMPLATES_LIST`, and
`resources/templates/list` dispatch, closing this revision's prior gap.
Missing-resource reads (exact or template) continue to report this revision's
existing known-wrong `-32601`.
+- **`2026-07-28`** — reuses its existing C2
`ResourceTemplate`/`ListResourceTemplatesResult`/mapping/pagination/cache-hint
machinery unchanged; template-backed reads apply the same cache-hint precedence
as exact-resource reads, keyed by the original concrete request URI.
Missing-resource reads report `RESOURCE_NOT_FOUND` (`-32602`).
+- **New completion wire beans (both revisions, independent copies)** —
`CompleteRequest`, `CompletionReference` (closed polymorphic base with
`PromptReference`/`ResourceTemplateReference`, discriminated
`ref/prompt`/`ref/resource`), `CompletionArgument`, `CompletionContext`,
`CompleteResult`, `Completion`, and an empty `CompletionCapability` marker
under a new nullable `ServerCapabilities.completions`, auto-derived only when
at least one completer is registered. `McpMethods.COMPLETION_CO [...]
+- **Included refactor: `McpJsonValueSafety` relocated to `juneau-commons`.**
The MCP core's bounded-depth/node/deadline JSON-value walker (used for
structured tool-output safety) moves to `juneau-commons` as
`org.apache.juneau.commons.utils.JsonValueSafety`, with an identical API and
behavior — a rename-only move (drops the `Mcp` prefix, since the class was
already protocol-neutral) bundled into this same change because it touches the
same neutral core and both dated adapters. `juneau-co [...]
+- **Scope fence, explicitly out of this change** — resource subscriptions
(`resources/subscribe`/`resources/unsubscribe` on `2025-06-18`, the newer
`subscriptions/listen` streaming request on `2026-07-28`) remain unimplemented
and are tracked separately (TODO-312 sub-project C8, gated on the future MCP
client sub-project); client-side RFC 6570 expansion and a general-purpose
URI-template API are out of scope; and Juneau does not rank, filter,
deduplicate, or paginate completion values be [...]
+
+See
[juneau-rest-server-mcp](/docs/topics/JuneauRestServerMcp#resource-templates-reads-and-completions)
and
[juneau-bean-mcp-v20250618](/docs/topics/JuneauBeanMcp#completions-completioncomplete-new-in-1000)
for the full topics.
### Bug Fixes
@@ -1006,7 +1021,7 @@ See
[juneau-rest-server-mcp](/docs/topics/JuneauRestServerMcp#cache-hints-mcp-20
- **Typed-`View` template names in the FreeMarker / Mustache / Thymeleaf view
bridges are now path-traversal-gated (behavioral change).** The
`juneau-rest-server-view-freemarker`, `-mustache`, and `-thymeleaf` bridges
previously applied `FileUtils.resolveVirtualPathSafely(...)` only on the raw
`/{engine}/*` mount, while a typed `View` return value
(`FreemarkerView.of(name)` / `MustacheView.of(name)` /
`ThymeleafView.of(name)`) passed its template name straight to the engine. As
of 10.0.0 [...]
- **`juneau-bean` DTO collection/array getters no longer expose live internal
state (behavioral change).** Getters on the DTO beans that previously returned
the bean's live internal collection or array now return a defensive, immutable
view so that caller-side mutation can no longer corrupt bean state:
- - **Collection / `Map` / `Set` getters** in `juneau-bean-jsonapi`
(`JsonApiResource`, `JsonApiDocument`, `JsonApiResourceIdentifier`,
`JsonApiLink`, `JsonApiVersion`, `JsonApiRelationship`, `JsonApiError`),
`juneau-bean-jsonschema` (`JsonSchema`), `juneau-bean-mcp-2025-06-18`
(`ListPromptsResult`, `ListToolsResult`, `ListResourcesResult`,
`ReadResourceResult`, `CallToolResult`, `GetPromptResult`, `Prompt`,
`CallToolRequest`, `GetPromptRequest`, `ServerCapabilities`,
`ClientCapabilities [...]
+ - **Collection / `Map` / `Set` getters** in `juneau-bean-jsonapi`
(`JsonApiResource`, `JsonApiDocument`, `JsonApiResourceIdentifier`,
`JsonApiLink`, `JsonApiVersion`, `JsonApiRelationship`, `JsonApiError`),
`juneau-bean-jsonschema` (`JsonSchema`), `juneau-bean-mcp-v20250618`
(`ListPromptsResult`, `ListToolsResult`, `ListResourcesResult`,
`ReadResourceResult`, `CallToolResult`, `GetPromptResult`, `Prompt`,
`CallToolRequest`, `GetPromptRequest`, `ServerCapabilities`,
`ClientCapabilities` [...]
- **Array getters** in `juneau-bean-atom` (`CommonEntry.getAuthors()` /
`getCategories()` / `getContributors()` / `getLinks()`, `Feed.getEntries()`)
and the mutable-`Calendar` getter `CommonEntry.getUpdated()` now return a
**defensive copy** (array `clone()` / `Calendar` clone) rather than the live
field, and the corresponding setters store a defensive copy of their argument.
Mutating a returned array/`Calendar` (or an array previously handed to a
setter) no longer affects the bean. Ge [...]
- **Migration:** callers that mutated a value returned from one of these
getters must instead go through the bean's setter/adder API. No source changes
are required for read-only usage.
diff --git a/pages/topics/01.02.WhyJuneau.md b/pages/topics/01.02.WhyJuneau.md
index 2d3587245e..f63436316e 100644
--- a/pages/topics/01.02.WhyJuneau.md
+++ b/pages/topics/01.02.WhyJuneau.md
@@ -216,7 +216,7 @@ try (TokenReader r = Json.DEFAULT.readTokens(inputStream)) {
- **Automatic Documentation:** Swagger UI generated automatically from your
code
- **Content Negotiation:** Support multiple formats with zero additional
configuration
- **Type Safety:** Compile-time checking for REST client interfaces
-- **MCP Support:** `juneau-rest-server-mcp` (revision-neutral core) plus the
`juneau-rest-server-mcp-2025-06-18` adapter expose any `@Rest` resource as a
Model Context Protocol (MCP) endpoint, enabling LLM tool-calling with no
additional framework
+- **MCP Support:** `juneau-rest-server-mcp` (revision-neutral core) plus the
`juneau-rest-server-mcp-v20250618` adapter expose any `@Rest` resource as a
Model Context Protocol (MCP) endpoint, enabling LLM tool-calling with no
additional framework
## When to Choose Juneau
diff --git a/pages/topics/05.00.JuneauBean.md b/pages/topics/05.00.JuneauBean.md
index f1da8ffeb9..641b6086bc 100644
--- a/pages/topics/05.00.JuneauBean.md
+++ b/pages/topics/05.00.JuneauBean.md
@@ -26,7 +26,7 @@ The `juneau-bean` group is split into one module per document
type. Every module
| [juneau-bean-openapi-v3](/docs/topics/JuneauBeanOpenApi3) | OpenAPI 3.0
document and UI beans. |
| [juneau-bean-common](/docs/topics/JuneauBeanCommon) | Shared general-purpose
DTOs (`LinkString`, `ResultSetList`). |
| [juneau-bean-swagger-v2](/docs/topics/JuneauBeanSwagger2) | Swagger 2.0
document and UI beans. |
-| [juneau-bean-mcp-2025-06-18](/docs/topics/JuneauBeanMcp) | Model Context
Protocol (MCP) `2025-06-18` wire beans (JSON-RPC envelope lives in
`juneau-bean-jsonrpc`). |
+| [juneau-bean-mcp-v20250618](/docs/topics/JuneauBeanMcp) | Model Context
Protocol (MCP) `2025-06-18` wire beans (JSON-RPC envelope lives in
`juneau-bean-jsonrpc`). |
| [juneau-bean-jsonrpc](/docs/topics/JuneauBeanJsonRpc) | Revision-neutral
JSON-RPC 2.0 envelope beans (`JsonRpcRequest`, `JsonRpcResponse`,
`JsonRpcError`, `McpException`). |
| [juneau-bean-rfc7807](/docs/topics/JuneauBeanRfc7807) | RFC 7807 Problem
Details (`application/problem+json`) beans. |
| [juneau-bean-hal](/docs/topics/JuneauBeanHal) | HAL hypermedia
(`application/hal+json`) beans. |
diff --git a/pages/topics/05.07.JuneauBeanMcp.md
b/pages/topics/05.07.JuneauBeanMcp.md
index 70a85b6fe4..799cb4cb2c 100644
--- a/pages/topics/05.07.JuneauBeanMcp.md
+++ b/pages/topics/05.07.JuneauBeanMcp.md
@@ -1,17 +1,17 @@
---
-title: "juneau-bean-mcp-2025-06-18"
+title: "juneau-bean-mcp-v20250618"
slug: JuneauBeanMcp
---
-The `juneau-bean-mcp-2025-06-18` 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.
## Overview
MCP is a JSON-RPC 2.0 protocol used by AI assistants and agents to interact
with external tools, prompts, and resources. Two bean modules cover the wire
format:
- **[juneau-bean-jsonrpc](/docs/topics/JuneauBeanJsonRpc)** (package
`org.apache.juneau.bean.jsonrpc`) — the revision-neutral JSON-RPC 2.0 envelope
(`JsonRpcRequest`, `JsonRpcResponse`, `JsonRpcError`, `McpException`). It
carries no MCP-specific knowledge and depends only on `juneau-marshall`. See
[juneau-bean-jsonrpc](/docs/topics/JuneauBeanJsonRpc) for full coverage.
-- **`juneau-bean-mcp-2025-06-18`** (package
`org.apache.juneau.bean.mcp.v20250618`) — the MCP `2025-06-18` wire beans
covered by this page: tool/prompt/resource descriptors, capability beans, and
the polymorphic content types. Renamed from the earlier `juneau-bean-mcp` /
`org.apache.juneau.bean.mcp` as part of a re-layering that split the JSON-RPC
envelope out into its own module — the name change leaves room for a future
sibling module under the same `org.apache.juneau.bean.mcp` namespa [...]
+- **`juneau-bean-mcp-v20250618`** (package
`org.apache.juneau.bean.mcp.v20250618`) — the MCP `2025-06-18` wire beans
covered by this page: tool/prompt/resource descriptors, capability beans, and
the polymorphic content types. Renamed from the earlier `juneau-bean-mcp` /
`org.apache.juneau.bean.mcp` as part of a re-layering that split the JSON-RPC
envelope out into its own module — the name change leaves room for a future
sibling module under the same `org.apache.juneau.bean.mcp` namespac [...]
Both modules ship Juneau `@Marshalled`-annotated POJOs, so you can build MCP
servers and clients using any Juneau serializer/parser (JSON, JSON5,
MessagePack, CBOR, YAML, and more).
@@ -22,7 +22,7 @@ Neither module ships transport or dispatch logic — no HTTP
plumbing. For a sta
- **Round-trip serialization** — Every bean parses back from its serialized
form into an identical object across JSON, JSON5, MessagePack, CBOR, YAML, and
other Juneau formats.
- **Polymorphic content blocks** — `Content` and `ResourceContents` use
`@Marshalled(typePropertyName="type", dictionary={...})` to discriminate
subtype on the wire.
- **Fluent setters** — Every bean uses `setX(...)` returning `this` for
ergonomic construction.
-- **No external dependencies** — Both modules depend only on `juneau-marshall`
(`juneau-bean-mcp-2025-06-18` additionally has a *test-scope* dependency on
`juneau-bean-jsonrpc`, to exercise the envelope types its own round-trip tests
still reference).
+- **No external dependencies** — Both modules depend only on `juneau-marshall`
(`juneau-bean-mcp-v20250618` additionally has a *test-scope* dependency on
`juneau-bean-jsonrpc`, to exercise the envelope types its own round-trip tests
still reference).
- **Zero protocol logic** — Pure DTOs; no validation, no state machines, no
dispatch.
## Coverage
@@ -69,6 +69,10 @@ The JSON-RPC 2.0 envelope beans (`JsonRpcRequest`,
`JsonRpcResponse`, `JsonRpcEr
| `ResourceContents` | Polymorphic interface for the body of a resource. |
| `TextResourceContents` (`type: "resourceText"`) | UTF-8 text body. |
| `BlobResourceContents` (`type: "resourceBlob"`) | Base64-encoded binary
body. |
+| `ResourceTemplate` | Resource-template descriptor: `uriTemplate`, `name`,
`title`, `description`, `mimeType`. Backfilled in 10.0.0 — see below. |
+| `ListResourceTemplatesResult` | Result of `resources/templates/list`:
`resourceTemplates`, `nextCursor`. Backfilled in 10.0.0 — see below. |
+
+**`resources/templates/list` backfill (10.0.0).** This revision originally
shipped with no resource-template beans or list method at all — `2026-07-28`
had them from the start (see the sibling module section below). 10.0.0 closes
that gap: `ResourceTemplate` and `ListResourceTemplatesResult` have the same
five/two-field shape as their `2026-07-28` counterparts, but
`ListResourceTemplatesResult` carries no cache fields (cache hints are a
`2026-07-28`-only concept). `McpMethods.RESOURCES_T [...]
### Polymorphic content blocks
@@ -80,9 +84,45 @@ The JSON-RPC 2.0 envelope beans (`JsonRpcRequest`,
`JsonRpcResponse`, `JsonRpcEr
| `ImageContent` | `type: "image"` |
| `EmbeddedResourceContent` | `type: "resource"` |
+### Completions (`completion/complete`, new in 10.0.0)
+
+Both dated bean modules — this one and `juneau-bean-mcp-v20260728` — gained an
equivalent, independently-typed completion wire-bean family in 10.0.0. There's
no shared completion module: each revision has its own copy of these nine
simple names, following the same duplication-over-abstraction convention as the
rest of this dated-bean pair.
+
+| Bean | Purpose |
+|---|---|
+| `CompleteRequest` | Parameters for `completion/complete`: `ref`, `argument`,
optional `context`. |
+| `CompletionReference` | Closed polymorphic interface for the completion
target. Exactly two subtypes — no fallback/`Map<String,Object>` carrier. |
+| `PromptReference` (`type: "ref/prompt"`) | Targets a declared prompt by
`name`. |
+| `ResourceTemplateReference` (`type: "ref/resource"`) | Targets a registered
resource template by its exact `uri` — the **registered template string** (e.g.
`file:///{name}`), not a concrete expanded URI. |
+| `CompletionArgument` | The argument/variable being completed: `name`,
`value` (the current partial value). |
+| `CompletionContext` | Optional already-resolved values: `arguments`
(`Map<String,String>`). |
+| `CompleteResult` | Result payload: `completion`. |
+| `Completion` | `values` (`List<String>`, at most 100), optional `total`,
optional `hasMore`. A lossless wire carrier — it does not itself enforce the
100-value cap; that's a `juneau-rest-server-mcp` dispatch responsibility. |
+| `CompletionCapability` | Empty marker bean advertised as
`ServerCapabilities.completions` when at least one completer is registered.
Serializes as `{}`. |
+
+`CompletionReference`'s two subtypes use the same
`@Marshalled(typePropertyName="type", dictionary={...})` discriminator pattern
as `Content`/`ResourceContents` above — enable `addBeanTypes` to serialize the
`type` field:
+
+```java
+import org.apache.juneau.bean.mcp.v20250618.*;
+import org.apache.juneau.marshall.json.*;
+
+JsonSerializer ser = JsonSerializer.create().addBeanTypes().build();
+
+CompleteRequest req = new CompleteRequest()
+ .setRef(new ResourceTemplateReference().setUri("file:///{name}"))
+ .setArgument(new CompletionArgument().setName("name").setValue("re"));
+
+String wire = ser.write(req);
+//
{"ref":{"type":"ref/resource","uri":"file:///{name}"},"argument":{"name":"name","value":"re"}}
+```
+
+A successful-but-empty completion (unknown/uncompletable target — not an
error) is `{"completion":{"values":[]}}`.
+
+`Prompt.arguments` and `PromptArgument` (`name`, `description`, `required` —
see Prompts above) are unchanged by this addition. A prompt argument may be
paired with a completer on the server side, but that association is server
behavior only and is never reflected as a new field on the wire
`PromptArgument` bean.
+
### Constants
-- `McpMethods` — JSON-RPC method names: `INITIALIZE`, `PING`, `TOOLS_LIST`,
`TOOLS_CALL`, `PROMPTS_LIST`, `PROMPTS_GET`, `RESOURCES_LIST`, `RESOURCES_READ`.
+- `McpMethods` — JSON-RPC method names: `INITIALIZE`, `PING`, `TOOLS_LIST`,
`TOOLS_CALL`, `PROMPTS_LIST`, `PROMPTS_GET`, `RESOURCES_LIST`,
`RESOURCES_READ`, `RESOURCES_TEMPLATES_LIST`, `COMPLETION_COMPLETE`.
- `McpProtocol` — Protocol literals: `JSON_RPC_2_0` (`"2.0"`) and
`VERSION_2025_06_18`.
## Polymorphic Serialization
@@ -227,7 +267,7 @@ Set `addBeanTypes` and the discriminator property names on
the corresponding bui
## MCP `2026-07-28` — Cache Hints & Resource Templates
-The sibling `juneau-bean-mcp-2026-07-28` module (package
`org.apache.juneau.bean.mcp.v20260728`) adds SEP-2549 cache hints and a
`resources/templates/list` result to its own revision of the wire beans covered
above. Both are opt-in, top-level, nullable fields/beans — omitted entirely
from the wire when unset.
+The sibling `juneau-bean-mcp-v20260728` module (package
`org.apache.juneau.bean.mcp.v20260728`) adds SEP-2549 cache hints and a
`resources/templates/list` result to its own revision of the wire beans covered
above. Both are opt-in, top-level, nullable fields/beans — omitted entirely
from the wire when unset.
| Bean | Purpose |
|---|---|
@@ -246,6 +286,10 @@ A compact example showing both features on the same result:
`McpMethods.RESOURCES_TEMPLATES_LIST` (`"resources/templates/list"`) is the
JSON-RPC method name for the new endpoint. See
[juneau-rest-server-mcp](/docs/topics/JuneauRestServerMcp#cache-hints-mcp-2026-07-28-sep-2549)
for how a server configures cache hints and registers resource templates.
+### `2026-07-28` completions (`completion/complete`, new in 10.0.0)
+
+`juneau-bean-mcp-v20260728` gained the same nine-bean completion family
described above for `2025-06-18` — `CompleteRequest`, `CompletionReference`
(with `PromptReference`/`ResourceTemplateReference` subtypes,
`ref/prompt`/`ref/resource` discriminators), `CompletionArgument`,
`CompletionContext`, `CompleteResult`, `Completion`, and `CompletionCapability`
— as an independent copy in `org.apache.juneau.bean.mcp.v20260728`, with
`McpMethods.COMPLETION_COMPLETE` (`"completion/complete"`). Fi [...]
+
## Related Modules
- **[juneau-bean-jsonrpc](/docs/topics/JuneauBeanJsonRpc)** — The
revision-neutral JSON-RPC 2.0 envelope beans that carry MCP traffic on the wire.
diff --git a/pages/topics/05.12.JuneauBeanJsonRpc.md
b/pages/topics/05.12.JuneauBeanJsonRpc.md
index a6af5ce8e7..5aeddc252a 100644
--- a/pages/topics/05.12.JuneauBeanJsonRpc.md
+++ b/pages/topics/05.12.JuneauBeanJsonRpc.md
@@ -4,11 +4,11 @@ slug: JuneauBeanJsonRpc
---
-The `juneau-bean-jsonrpc` module provides Java beans modelling the
revision-neutral [JSON-RPC 2.0](https://www.jsonrpc.org/specification)
envelope: request/response/error framing plus a runtime exception for
handler-side error propagation. It carries no protocol-specific knowledge and
depends only on `juneau-marshall`, making it the shared framing layer beneath
protocol-specific bean modules such as
[juneau-bean-mcp-2025-06-18](/docs/topics/JuneauBeanMcp).
+The `juneau-bean-jsonrpc` module provides Java beans modelling the
revision-neutral [JSON-RPC 2.0](https://www.jsonrpc.org/specification)
envelope: request/response/error framing plus a runtime exception for
handler-side error propagation. It carries no protocol-specific knowledge and
depends only on `juneau-marshall`, making it the shared framing layer beneath
protocol-specific bean modules such as
[juneau-bean-mcp-v20250618](/docs/topics/JuneauBeanMcp).
## Overview
-JSON-RPC 2.0 is a stateless, lightweight remote procedure call protocol
encoded as JSON. This module ships the envelope shapes needed to read and write
JSON-RPC requests and responses, without any knowledge of what methods exist or
what their parameters mean — that's left to higher-level modules like
[juneau-bean-mcp-2025-06-18](/docs/topics/JuneauBeanMcp).
+JSON-RPC 2.0 is a stateless, lightweight remote procedure call protocol
encoded as JSON. This module ships the envelope shapes needed to read and write
JSON-RPC requests and responses, without any knowledge of what methods exist or
what their parameters mean — that's left to higher-level modules like
[juneau-bean-mcp-v20250618](/docs/topics/JuneauBeanMcp).
The beans are Juneau `@Marshalled`-annotated POJOs, so they round-trip through
any Juneau serializer/parser (JSON, JSON5, MessagePack, CBOR, YAML, and more).
@@ -29,7 +29,7 @@ The beans are Juneau `@Marshalled`-annotated POJOs, so they
round-trip through a
| `JsonRpcError` | JSON-RPC error structure (`code`, `message`, `data`). |
| `McpException` | `RuntimeException` carrying JSON-RPC error fields (`code`,
`data`) for handler-side propagation; `toJsonRpcError()` converts it to a
`JsonRpcError`. |
-This module carries no MCP-specific knowledge — it's the shared framing
layer beneath protocol-specific bean modules such as
[juneau-bean-mcp-2025-06-18](/docs/topics/JuneauBeanMcp).
+This module carries no MCP-specific knowledge — it's the shared framing
layer beneath protocol-specific bean modules such as
[juneau-bean-mcp-v20250618](/docs/topics/JuneauBeanMcp).
## Basic Usage
@@ -123,7 +123,7 @@ String yaml = Yaml.of(resp);
## Related Modules
-- **[juneau-bean-mcp-2025-06-18](/docs/topics/JuneauBeanMcp)** — The
Model Context Protocol `2025-06-18` wire beans, which build their JSON-RPC
traffic on top of this envelope.
+- **[juneau-bean-mcp-v20250618](/docs/topics/JuneauBeanMcp)** — The
Model Context Protocol `2025-06-18` wire beans, which build their JSON-RPC
traffic on top of this envelope.
- **[juneau-rest-server-mcp](/docs/topics/JuneauRestServerMcp)** — A
stateless JSON-RPC REST-server endpoint built on `juneau-rest-server` and these
beans.
## Resources
diff --git a/pages/topics/11.JuneauRestServerMcp.md
b/pages/topics/11.JuneauRestServerMcp.md
index 43fb29021f..5c108c6868 100644
--- a/pages/topics/11.JuneauRestServerMcp.md
+++ b/pages/topics/11.JuneauRestServerMcp.md
@@ -5,7 +5,7 @@ slug: JuneauRestServerMcp
---
-`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-2025-06-18`**, which binds the
core to the `2025-06-18` wire beans in
[`juneau-bean-mcp-2025-06-18`](/docs/topics/JuneauBeanMcp). This p [...]
+`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 [...]
## Overview
@@ -31,7 +31,7 @@ The implementation is stateless — every request is dispatched
against the `Mcp
+------------------------------------------------+
+------------------------------------------------+ +-----------------+
| |
v v
- juneau-rest-server-mcp
juneau-bean-mcp-2025-06-18
+ juneau-rest-server-mcp
juneau-bean-mcp-v20250618
(core: McpServerConfig, (wire beans,
via
McpRevision SPI, neutral model)
org.apache.juneau.rest.server.mcp.v20250618.McpWire)
```
@@ -47,12 +47,12 @@ Application code normally depends on the `2025-06-18`
adapter, which transitivel
```xml
<dependency>
<groupId>org.apache.juneau</groupId>
- <artifactId>juneau-rest-server-mcp-2025-06-18</artifactId>
+ <artifactId>juneau-rest-server-mcp-v20250618</artifactId>
<version>${juneau.version}</version>
</dependency>
```
-This module transitively pulls in `juneau-rest-server-mcp` (the core) and
`juneau-bean-mcp-2025-06-18`.
+This module transitively pulls in `juneau-rest-server-mcp` (the core) and
`juneau-bean-mcp-v20250618`.
### Drop-in servlet
@@ -294,7 +294,128 @@ The check is memoized per `McpServerConfig` instance (an
identity-keyed weak set
MCP returns polymorphic content (`Content`, `ResourceContents`) discriminated
by a `type` property. The core `McpRestServlet` enables `addBeanTypes` on its
serializer via `@SerializerConfig(addBeanTypes="true")` so the discriminator is
emitted on the wire — this carries over unchanged onto
`org.apache.juneau.rest.server.mcp.v20250618.McpRestServlet`. If you build your
own `RestServlet` (bypassing both), apply the same configuration.
-See [juneau-bean-mcp-2025-06-18](/docs/topics/JuneauBeanMcp) for the full
wire-bean catalog.
+See [juneau-bean-mcp-v20250618](/docs/topics/JuneauBeanMcp) for the full
wire-bean catalog.
+
+## Resource Templates, Reads, and Completions
+
+**New in 10.0.0**, cross-revision (both `2025-06-18` and `2026-07-28`).
Registered resource templates are no longer listing-only: a template can now be
*read* through ordinary `resources/read`, and both prompt arguments and
resource-template variables can be completed through `completion/complete`.
Both features live entirely in the revision-neutral `juneau-rest-server-mcp`
core; each dated adapter only adds wire mapping and dispatch on top of the same
neutral model.
+
+MCP defines no separate "read from template" method. A client discovers a
template via `resources/templates/list`, expands it into a concrete URI itself,
and sends that concrete URI through an ordinary `resources/read`. The server is
responsible for resolving that concrete URI back to either an exact resource or
a registered template.
+
+### Registering a readable template
+
+`McpResourceTemplateHandler` pairs the existing `McpResourceTemplateSpec`
descriptor (`uriTemplate`, `name`, `title`, `description`, `mimeType` —
unchanged) with a variable-aware `read(...)` method and an optional
per-variable `completer(...)`:
+
+```java
+import java.util.*;
+
+import org.apache.juneau.commons.inject.*;
+import org.apache.juneau.rest.server.mcp.*;
+
+public class FileTemplate implements McpResourceTemplateHandler {
+ @Override
+ public McpResourceTemplateSpec descriptor() {
+ return new McpResourceTemplateSpec()
+ .setUriTemplate("file:///{name}")
+ .setName("files")
+ .setMimeType("text/plain");
+ }
+
+ @Override
+ public McpResourceOutcome read(String uri, Map<String,String> variables,
BeanStore ctx) {
+ String name = variables.get("name");
+ // return null if this template does not actually serve `uri`
(reported as resource-not-found)
+ return McpResourceOutcome.text(uri, loadFile(name));
+ }
+}
+
+config.addResourceTemplate(new FileTemplate());
+```
+
+`McpServerConfig`'s primary resource-template APIs are handler-based:
`getResourceTemplates()`,
`setResourceTemplates(List<McpResourceTemplateHandler>)`, and
`addResourceTemplate(McpResourceTemplateHandler...)`. The pre-existing
descriptor-only registration style from the `2026-07-28` cache-hints work below
still works unchanged, as a **listing-only convenience** — it's now a thin
wrapper around a built-in handler whose `read(...)` and `completer(...)` both
return `null`:
+
+```java
+config.addResourceTemplate(new McpResourceTemplateSpec()
+
.setUriTemplate("file:///{name}").setName("files").setMimeType("text/plain"));
+```
+
+Bulk replacement of listing-only descriptors uses
`setResourceTemplateSpecs(List<McpResourceTemplateSpec>)` (a second
erasure-conflicting `setResourceTemplates(List<McpResourceTemplateSpec>)`
overload isn't possible in Java). `read(...)` returning `null` for a
*handler-based* registration is reported as resource-not-found, exactly like a
listing-only template being selected — a selected template's outcome never
falls through to a different, less-specific template.
+
+The complete registry is validated up front:
`addResourceTemplate(...)`/`setResourceTemplates(...)`/`setResourceTemplateSpecs(...)`
reject a `null` handler/descriptor, a `null`/blank `uriTemplate`, a malformed
template, a duplicate variable name within one template, or an exact duplicate
`uriTemplate` string — all with `IllegalArgumentException` naming the offending
index and template, before any request is ever dispatched. Because
`getResourceTemplates()` returns the same mutable list a [...]
+
+### The reverse-matchable subset
+
+Juneau does **not** implement complete RFC 6570 reverse matching for every
legal template form. It hand-rolls a dependency-free, reliable *reverse*
matcher for one narrow, invertible subset — reads always match a concrete URI
back to variables, never the other direction (Juneau has no URI-template
expansion API at all: the client always sends the fully-expanded concrete URI
on `resources/read`). Reverse-matchable forms:
+
+| Form | Example | Notes |
+|---|---|---|
+| Simple scalar | `{var}` | Captures exactly one path segment; never crosses
an **unencoded** `/`. |
+| Reserved scalar | `{+var}` | May capture reserved characters, including an
unencoded `/`. |
+| Fragment scalar | `{#var}` | Like `{+var}`, with a required leading `#`. |
+| Path segments | `{/var}`, `{/x,y}` | One slash-prefixed segment per declared
variable, in order. |
+| Label segments | `{.var}`, `{.x,y}` | One dot-prefixed segment per declared
variable, in order. |
+| Query start/continuation | `{?x,y}`, `{&x,y}` | Every declared key exactly
once, in declaration order; values may be empty. |
+
+Everything else that's *syntactically* legal RFC 6570 — exploded (`{tags*}`),
prefixed (`{var:3}`), matrix (`{;x}`) forms, multi-variable
simple/reserved/fragment expressions (`{x,y}`), and expressions with ambiguous
adjacency to a neighboring expression — registers successfully (so it's still
listed and its variables are still completable) but is **never selected for a
template-backed read**; a concrete URI that only such a template could describe
reports plain resource-not-found. This [...]
+
+Matching follows RFC 3986 percent-normalization, implemented fresh (not via
`StringUtils.urlEncode`/`urlDecode`, which are form-urlencoded and would be
wrong here): `%HH` triplets are hex-normalized, percent-encoded unreserved
octets compare as their literal character, and an encoded `%2F` stays *inside*
a `{var}` segment as data rather than acting as a path separator — a captured
`%2F` is delivered to the handler already decoded to `/`. A raw, unencoded `/`
remains a segment boundary. ` [...]
+
+`file:///{a}/{b}` and `file:///{name}` are deliberately distinguishable: the
first matches `file:///one/two` with `{a=one, b=two}`; the second does not
(`{name}` can't cross the unencoded `/`), though `file:///{+name}` would,
capturing `name=one/two`.
+
+### Resolution order
+
+For each `resources/read`:
+
+1. **Exact resources always win** — `McpResourceHandler` string-equality
lookup runs first, unconditionally, even if a more-literal template would also
match.
+2. If no exact resource matches, every reverse-matchable template is
evaluated, and the winner is selected by, in order: more literal URI octets
outside `{...}` (after percent normalization) → fewer declared variables →
earlier registration index. Operator type, capture width, and descriptor
name/title are never tie-breakers.
+3. The winning handler receives the **original concrete URI**, an **immutable,
insertion-ordered map of decoded variables**, and the same per-request
`BeanStore` an exact resource handler would get.
+4. No candidate, or the winning handler's `read(...)` returning `null`, is
resource-not-found — `-32601` on `2025-06-18` (preserving that revision's
existing known-wrong error-code mapping) and `RESOURCE_NOT_FOUND` (`-32602`) on
`2026-07-28`. A handler throwing is `-32603` on both.
+
+On `2026-07-28`, a template-backed read applies the adapter's existing
cache-hint precedence (`resourceReadOverrides` → `resourcesRead` →
`defaultHint`) using the **original concrete request URI** — the same
precedence and lookup key an exact-resource read already uses; C4 adds no new
cache concept.
+
+### Completions (`completion/complete`)
+
+Both revisions dispatch `completion/complete` against the same two completion
targets:
+
+- a **prompt argument** — attach an `McpCompleter` to an `McpPromptArgument`:
+
+ ```java
+ import org.apache.juneau.rest.server.mcp.*;
+
+ McpPromptArgument city = new McpPromptArgument()
+ .setName("city")
+ .setRequired(true)
+ .setCompleter((request, ctx) -> McpCompletionResult.empty()
+ .setValues(citiesStartingWith(request.getValue())));
+ ```
+
+- a **resource-template variable** — override `completer(String)` on the
`McpResourceTemplateHandler`:
+
+ ```java
+ @Override
+ public McpCompleter completer(String variableName) {
+ return "name".equals(variableName)
+ ? (request, ctx) ->
McpCompletionResult.empty().setValues(matchingFileNames(request.getValue()))
+ : null;
+ }
+ ```
+
+`McpCompleter` is a single-method `@FunctionalInterface`: `McpCompletionResult
complete(McpCompletionRequest request, BeanStore ctx)`. A completion reference
always names an **exact declaration** — the prompt name, or the registered
`uriTemplate` string itself — never a concrete/expanded URI; dispatch looks the
target up by exact string equality, not by reverse-matching. Completer behavior:
+
+- An unknown prompt/template, an undeclared argument/variable, or a known
argument/variable with no completer attached all return a **successful empty
completion** (`{"completion":{"values":[]}}`) without ever invoking a completer
— this is normal protocol behavior, not an error.
+- A malformed request (missing/wrong-typed `ref`, `argument`, or `context`) is
`-32602`.
+- A completer that throws, returns `null`, returns a result with a `null`
values-list element, or a negative `total` is `-32603`.
+- At most 100 values are ever emitted; truncating past that forces
`hasMore=true`. Order and duplicates are exactly whatever the completer
returned — **Juneau performs no ranking, filtering, deduplication, or
additional pagination of its own.** A completer is also free to return more
than 100 candidate values already ranked by the application; only the first 100
reach the wire.
+
+On `2026-07-28`, `completion/complete` is deliberately **nameless** for
SEP-2243's `Mcp-Method`/`Mcp-Name` header agreement: `Mcp-Method` is
`completion/complete` and `Mcp-Name` is the empty string, because the actual
target is nested under `params.ref`, not one of the top-level `name`/`uri`
fields SEP-2243 routes on for `tools/call`/`prompts/get`/`resources/read`. The
request's normal per-request `_meta` (`protocolVersion`, `clientInfo`,
`capabilities`) is still validated exactly as for [...]
+
+A prompt argument's `completer` is server behavior only — it's never mapped
onto the dated wire `PromptArgument` bean (`name`/`description`/`required`
only, on both revisions).
+
+### Completions capability
+
+Both dated `ServerCapabilities` gain a nullable `completions` property,
auto-derived alongside `tools`/`prompts`/`resources`: it's advertised (as an
empty `{}` `CompletionCapability` marker) only when at least one
prompt-argument completer or resource-template variable completer is currently
registered — registering a template or prompt with no completer does not turn
it on. As with the other auto-derived capability flags, an explicit
`ServerCapabilities` override on the servlet/mixin `c [...]
+
+See
[juneau-bean-mcp-v20250618](/docs/topics/JuneauBeanMcp#completions-completioncomplete-new-in-1000)
for the `2025-06-18` completion wire-bean catalog (`CompleteRequest`,
`CompletionReference`/`PromptReference`/`ResourceTemplateReference`,
`CompletionArgument`, `CompletionContext`, `CompleteResult`, `Completion`,
`CompletionCapability`) and the equivalent `2026-07-28` family.
## Cache Hints (MCP `2026-07-28`, SEP-2549)
@@ -302,7 +423,7 @@ The `2026-07-28` adapter
(`org.apache.juneau.rest.server.mcp.v20260728`) adds tw
### Registering resource templates
-Resource templates are registered on the same neutral `McpServerConfig` used
for tools/prompts/resources, via the revision-neutral `McpResourceTemplateSpec`
descriptor (`uriTemplate`, `name`, `title`, `description`, `mimeType`).
Registering at least one resource or resource template auto-derives the
`resources` capability, exactly like resources do today.
+Resource templates are registered on the same neutral `McpServerConfig` used
for tools/prompts/resources. `addResourceTemplate(McpResourceTemplateSpec)`
(shown below) registers a **listing-only** template — descriptor only, no
`resources/read` support — via the revision-neutral `McpResourceTemplateSpec`
descriptor (`uriTemplate`, `name`, `title`, `description`, `mimeType`).
Registering at least one resource or resource template auto-derives the
`resources` capability, exactly like resour [...]
### Configuring cache hints
@@ -345,11 +466,11 @@ Every page of a paginated list result carries an
identical cache hint (or an ide
Registering resource templates through the neutral
`McpServerConfig`/`McpResourceTemplateSpec` involves no cache-related types at
all; cache policy is entirely adapter-owned, keeping the neutral core (and
hence any future MCP revision built on it) free of both cache and
dated-revision knowledge.
-See
[juneau-bean-mcp-2026-07-28](/docs/topics/JuneauBeanMcp#mcp-2026-07-28-cache-hints-resource-templates)
for the wire-bean side of cache hints (`McpCacheScope`, `CacheableResult<T>`)
and resource templates (`ResourceTemplate`, `ListResourceTemplatesResult`).
+See
[juneau-bean-mcp-v20260728](/docs/topics/JuneauBeanMcp#mcp-2026-07-28-cache-hints-resource-templates)
for the wire-bean side of cache hints (`McpCacheScope`, `CacheableResult<T>`)
and resource templates (`ResourceTemplate`, `ListResourceTemplatesResult`).
## Related Modules
-- **[juneau-bean-mcp-2025-06-18](/docs/topics/JuneauBeanMcp)** — The
`2025-06-18` wire beans consumed by the adapter module, plus the
revision-neutral JSON-RPC envelope beans (`juneau-bean-jsonrpc`) both modules
build on.
+- **[juneau-bean-mcp-v20250618](/docs/topics/JuneauBeanMcp)** — The
`2025-06-18` wire beans consumed by the adapter module, plus the
revision-neutral JSON-RPC envelope beans (`juneau-bean-jsonrpc`) both modules
build on.
- **[juneau-rest-server](/docs/topics/JuneauRestServer)** — The base REST
server framework.
## Resources
diff --git a/pages/topics/23.05.JuneauShadedAll.md
b/pages/topics/23.05.JuneauShadedAll.md
index ec0285a902..88abbfd091 100644
--- a/pages/topics/23.05.JuneauShadedAll.md
+++ b/pages/topics/23.05.JuneauShadedAll.md
@@ -22,7 +22,7 @@ This artifact includes **everything**:
- **juneau-rest-server** - REST server API
- **juneau-rest-server-springboot** - Spring Boot integration
- **juneau-rest-server-mcp** - Model Context Protocol (MCP) REST server
endpoint (revision-neutral core)
-- **juneau-rest-server-mcp-2025-06-18** - MCP `2025-06-18` REST server adapter
+- **juneau-rest-server-mcp-v20250618** - MCP `2025-06-18` REST server adapter
### Bean DTOs
- **juneau-bean-common** - Common bean utilities
@@ -30,7 +30,7 @@ This artifact includes **everything**:
- **juneau-bean-html5** - HTML5 element beans
- **juneau-bean-jsonschema** - JSON Schema beans (Draft 2020-12)
- **juneau-bean-jsonrpc** - JSON-RPC 2.0 envelope beans
-- **juneau-bean-mcp-2025-06-18** - Model Context Protocol (MCP) `2025-06-18`
beans
+- **juneau-bean-mcp-v20250618** - Model Context Protocol (MCP) `2025-06-18`
beans
- **juneau-bean-openapi-v3** - OpenAPI 3.0 beans
- **juneau-bean-swagger-v2** - Swagger 2.0 beans
diff --git a/sidebars.ts b/sidebars.ts
index 86bf19bc00..8a84bcb4e7 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -943,7 +943,7 @@ const sidebars: SidebarsConfig = {
{
type: 'doc',
id:
'topics/05.07.JuneauBeanMcp',
- label: '5.7.
juneau-bean-mcp-2025-06-18',
+ label: '5.7.
juneau-bean-mcp-v20250618',
},
{
type: 'doc',
