You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@juneau.apache.org by ja...@apache.org on 2026/07/31 11:47:45 UTC
(juneau) branch docs updated: MCP 2026-07-28 cache hints (SEP-2549) + v2 resources/templates/list
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 <ja...@apache.org>
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.