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 f49c6d21fd MCP 2026-07-28 cache hints (SEP-2549) + v2
resources/templates/list
f49c6d21fd is described below
commit f49c6d21fd17d71781f23d798b0a2394f892d6bb
Author: James Bognar <[email protected]>
AuthorDate: Fri Jul 31 07:47:38 2026 -0400
MCP 2026-07-28 cache hints (SEP-2549) + v2 resources/templates/list
Add optional ttlMs/cacheScope hints to all five v2 result carriers
(tools/list, prompts/list, resources/list, resources/templates/list,
resources/read) plus real paginated resources/templates/list dispatch.
V2-only cache config (McpCacheHint/McpCacheConfig, servlet
createCacheConfig()/getCacheConfig(), McpEndpoint.cacheConfig());
revision-neutral core stays cache-free (dependency-fence proven).
New v2 beans: McpCacheScope, CacheableResult<T>, ResourceTemplate,
ListResourceTemplatesResult. New neutral McpResourceTemplateSpec +
registration.
TODO-312c2.
---
pages/release-notes/10.0.0.md | 10 +++++++
pages/topics/05.07.JuneauBeanMcp.md | 21 ++++++++++++++
pages/topics/11.JuneauRestServerMcp.md | 51 ++++++++++++++++++++++++++++++++++
3 files changed, 82 insertions(+)
diff --git a/pages/release-notes/10.0.0.md b/pages/release-notes/10.0.0.md
index e31457859b..209255a3ff 100644
--- a/pages/release-notes/10.0.0.md
+++ b/pages/release-notes/10.0.0.md
@@ -883,6 +883,16 @@ Requests without an `id` are treated as JSON-RPC
notifications: handlers run, ex
See [juneau-rest-server-mcp-2025-06-18](/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.
+
+- **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.
+
### Bug Fixes
- **Fixed RRPC method calls never dispatching over POST.** Every HTTP POST to
an `@RestOp(method="RRPC")` operation previously returned a 404 instead of
reaching the target method. `RrpcRestOpSession` derived the RRPC method key by
splitting the request path on the last `/`, but RRPC keys are of the form
`methodName/(paramTypes)` and themselves contain a `/`, so the method name was
stripped off and the lookup always fell through to `NotFound`. The key is now
derived from the already-comp [...]
diff --git a/pages/topics/05.07.JuneauBeanMcp.md
b/pages/topics/05.07.JuneauBeanMcp.md
index 7ab9a7d5aa..70a85b6fe4 100644
--- a/pages/topics/05.07.JuneauBeanMcp.md
+++ b/pages/topics/05.07.JuneauBeanMcp.md
@@ -225,6 +225,27 @@ String yaml = Yaml.of(r);
Set `addBeanTypes` and the discriminator property names on the corresponding
builders to round-trip polymorphic content correctly.
+## 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.
+
+| Bean | Purpose |
+|---|---|
+| `McpCacheScope` | Enum with exactly two wire values: `public`, `private`. |
+| `CacheableResult<T>` | Abstract CRTP base contributing inherited, nullable,
top-level `ttlMs` (`Integer`) and `cacheScope` (`McpCacheScope`) properties to
a result bean. `ListToolsResult`, `ListPromptsResult`, `ListResourcesResult`,
`ListResourceTemplatesResult`, and `ReadResourceResult` all extend it. |
+| `ResourceTemplate` | Resource-template descriptor: `uriTemplate`, `name`,
`title`, `description`, `mimeType`. |
+| `ListResourceTemplatesResult` | Result of `resources/templates/list`:
`resourceTemplates`, `nextCursor`, plus the inherited cache fields. |
+
+A compact example showing both features on the same result:
+
+```json
+{"resourceTemplates":[{"uriTemplate":"file:///{name}","name":"files"}],"ttlMs":0,"cacheScope":"private"}
+```
+
+`ttlMs: 0` means the result is immediately stale (a valid, explicit hint —
distinct from omitting the field entirely). An absent `cacheScope` is
interpreted by a consumer as public; Juneau never writes a default scope onto
the wire — the property is only serialized when explicitly set. These fields
describe the *whole* result, not individual list items.
+
+`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.
+
## 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/11.JuneauRestServerMcp.md
b/pages/topics/11.JuneauRestServerMcp.md
index 64e9edd7e9..43fb29021f 100644
--- a/pages/topics/11.JuneauRestServerMcp.md
+++ b/pages/topics/11.JuneauRestServerMcp.md
@@ -296,6 +296,57 @@ MCP returns polymorphic content (`Content`,
`ResourceContents`) discriminated by
See [juneau-bean-mcp-2025-06-18](/docs/topics/JuneauBeanMcp) for the full
wire-bean catalog.
+## Cache Hints (MCP `2026-07-28`, SEP-2549)
+
+The `2026-07-28` adapter (`org.apache.juneau.rest.server.mcp.v20260728`) adds
two capabilities on top of the neutral core: SEP-2549 cache hints on five
list/read results, and a `resources/templates/list` endpoint. Both are
configured statically, at server-construction time — there is no
dynamic/per-request cache callback, and neither concept exists on the neutral
`juneau-rest-server-mcp` core or the `2025-06-18` adapter.
+
+### 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.
+
+### Configuring cache hints
+
+`McpCacheConfig` (adapter-owned, immutable after construction) carries one
`McpCacheHint` (nullable `ttlMs` + `McpCacheScope`) per list method, plus a
`resourcesRead` default and an exact-URI override map for individual resource
reads:
+
+```java
+private final McpCacheConfig cache = new McpCacheConfig()
+ .setDefaultHint(new McpCacheHint().setTtlMs(60_000))
+ .setToolsList(new McpCacheHint().setTtlMs(0))
+ .setResourcesRead(new
McpCacheHint().setCacheScope(McpCacheScope.PUBLIC))
+ .addResourceReadOverride("file:///private",
+ new
McpCacheHint().setTtlMs(5_000).setCacheScope(McpCacheScope.PRIVATE));
+
+@Override protected McpServerConfig createMcpConfig() {
+ return new McpServerConfig().addResourceTemplate(new
McpResourceTemplateSpec()
+
.setUriTemplate("file:///{name}").setName("files").setMimeType("text/plain"));
+}
+
+@Override protected McpCacheConfig createCacheConfig() {
+ return cache;
+}
+```
+
+The `McpEndpoint` mixin path is the same shape, with a stable `cacheConfig()`
override instead of `createCacheConfig()`:
+
+```java
+private final McpCacheConfig cache = new McpCacheConfig().setToolsList(new
McpCacheHint().setTtlMs(0));
+
+@Override public McpCacheConfig cacheConfig() {
+ return cache;
+}
+```
+
+**Precedence is atomic — a matched hint's `ttlMs`/`cacheScope` pair is applied
as a whole, never merged field-by-field with a lower-precedence hint:**
+
+- **List methods** (`tools/list`, `prompts/list`, `resources/list`,
`resources/templates/list`): the method-specific hint (e.g. `toolsList`) if
set, else `defaultHint` if set, else no cache fields are written at all. An
explicitly-set *empty* hint (both fields `null`) at a higher precedence still
suppresses the lower one — it does not fall through.
+- **`resources/read`**: `resourceReadOverrides.get(uri)` (exact string match —
no URI normalization or template expansion) if present, else `resourcesRead` if
set, else `defaultHint` if set, else no cache fields.
+
+Every page of a paginated list result carries an identical cache hint (or an
identical absence of one) — cache hints describe the whole result, not a side
channel keyed by page.
+
+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`).
+
## 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.
