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 b9deebfd18 docs: MCP client stack (juneau-rest-client-mcp*) +
trace-inject seam (TODO-312e)
b9deebfd18 is described below
commit b9deebfd188c7f775c7624644ad6cc46a820e934
Author: James Bognar <[email protected]>
AuthorDate: Sun Aug 2 08:54:31 2026 -0400
docs: MCP client stack (juneau-rest-client-mcp*) + trace-inject seam
(TODO-312e)
- New topic page: JuneauRestClientMcp (neutral core + dated adapters,
SSE/duplex,
auth + response-cache seams, revision binding).
- Observability: add "MCP client trace-context injection seam" subsection.
- 10.0.0 release notes: add MCP client modules subsection.
- artifact-paths.json: register the 3 new client modules.
Co-authored-by: Cursor <[email protected]>
---
artifact-paths.json | 3 ++
pages/release-notes/10.0.0.md | 10 ++++++
pages/topics/10.40.RestServerObservability.md | 10 ++++++
pages/topics/11.01.JuneauRestClientMcp.md | 49 +++++++++++++++++++++++++++
sidebars.ts | 5 +++
5 files changed, 77 insertions(+)
diff --git a/artifact-paths.json b/artifact-paths.json
index e7a3880159..30f2a7b50b 100644
--- a/artifact-paths.json
+++ b/artifact-paths.json
@@ -44,6 +44,9 @@
"juneau-rest-client-apache-httpclient-50":
"juneau-rest/juneau-rest-client-apache-httpclient-50",
"juneau-rest-client-classic": "juneau-rest/juneau-rest-client-classic",
"juneau-rest-client-jetty": "juneau-rest/juneau-rest-client-jetty",
+ "juneau-rest-client-mcp": "juneau-rest/juneau-rest-client-mcp",
+ "juneau-rest-client-mcp-v20250618":
"juneau-rest/juneau-rest-client-mcp-v20250618",
+ "juneau-rest-client-mcp-v20260728":
"juneau-rest/juneau-rest-client-mcp-v20260728",
"juneau-rest-client-okhttp": "juneau-rest/juneau-rest-client-okhttp",
"juneau-rest-common": "juneau-rest/juneau-rest-common",
"juneau-rest-common-classic": "juneau-rest/juneau-rest-common-classic",
diff --git a/pages/release-notes/10.0.0.md b/pages/release-notes/10.0.0.md
index e39debca39..d590bb9e81 100644
--- a/pages/release-notes/10.0.0.md
+++ b/pages/release-notes/10.0.0.md
@@ -696,6 +696,16 @@ Juneau's first [Model Context
Protocol](https://modelcontextprotocol.io/) suppor
- **`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.
+### MCP client modules (`juneau-rest-client-mcp*`)
+
+10.0.0 adds Juneau's first first-party MCP client stack:
+
+- **`juneau-rest-client-mcp`** — revision-neutral client core on
`juneau-rest-client` (`AbstractMcpClient`) with raw JSON-RPC send/receive,
auth-token seam (`McpAuthInterceptor`), response-cache seam (`McpResponseCache`
+ `InMemoryMcpResponseCache`), and an opaque server->client duplex dispatch
seam (`McpServerRequestHandler`).
+- **`juneau-rest-client-mcp-v20250618`** — typed `McpClient` facade for MCP
`2025-06-18`.
+- **`juneau-rest-client-mcp-v20260728`** — typed `McpClient` facade for MCP
`2026-07-28`, including v2 `_meta`/header plumbing and cache-hint-aware client
behavior.
+
+The duplex path builds directly on the new general-purpose SSE APIs in
`juneau-rest-client` (`RestRequest.openEventStream()`,
`ResponseBody.asEventStream()`) and keeps server->client payloads raw/opaque by
design; typed sampling/elicitation modeling remains owned by later MCP server
slices.
+
### `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-v20250618`.
diff --git a/pages/topics/10.40.RestServerObservability.md
b/pages/topics/10.40.RestServerObservability.md
index f6413ab30f..d08e8b2058 100644
--- a/pages/topics/10.40.RestServerObservability.md
+++ b/pages/topics/10.40.RestServerObservability.md
@@ -409,6 +409,16 @@ The `gen_ai.*`/`mcp.*` span attribute names, the
tool/prompt/resource span-namin
None of the above exists on `2025-06-18`: its wire beans have no
`_meta`-carried trace fields, its adapter publishes no `TraceContextExtractor`,
and it continues to rely solely on the HTTP-header propagation and
response-header injection described earlier on this page.
+### MCP client trace-context injection seam
+
+The MCP client stack (`juneau-rest-client-mcp` + dated adapters) exposes an
injection seam that mirrors the server-side trace propagation model without
coupling client modules to server-only tracing types.
+
+- The v2 adapter writes `traceparent`, `tracestate`, and `baggage` into
request `params._meta`.
+- The same adapter reads echoed values from `result._meta` on success.
+- Injection is opt-in and builder-configurable; no tracing fields are emitted
unless configured.
+
+This seam is intentionally payload-opaque at the duplex boundary:
server->client requests are dispatched as raw `JsonRpcRequest` envelopes
through `McpServerRequestHandler`, with no typed sampling/elicitation
projection in the client core.
+
## Custom `MetricsRecorder` / `TracerHook` implementations
The SPIs are deliberately tiny — implement them directly when you need a
backend the shipped bridges don't cover (Dropwizard Metrics, an internal
time-series store, a structured-log appender, …):
diff --git a/pages/topics/11.01.JuneauRestClientMcp.md
b/pages/topics/11.01.JuneauRestClientMcp.md
new file mode 100644
index 0000000000..7d313a77c4
--- /dev/null
+++ b/pages/topics/11.01.JuneauRestClientMcp.md
@@ -0,0 +1,49 @@
+---
+id: 11.01.juneau-rest-client-mcp
+title: "juneau-rest-client-mcp"
+slug: JuneauRestClientMcp
+---
+
+`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`.
+
+## Overview
+
+The client stack is split exactly like the server stack:
+
+- `juneau-rest-client-mcp` - neutral transport/auth/cache/duplex seams
centered on `AbstractMcpClient`.
+- `juneau-rest-client-mcp-v20250618` - typed facade for MCP `2025-06-18`.
+- `juneau-rest-client-mcp-v20260728` - typed facade for MCP `2026-07-28`.
+
+The neutral core sends raw JSON-RPC (`JsonRpcRequest`/`JsonRpcResponse`) and
leaves revision-specific `_meta`/header details to dated adapters.
+
+## SSE and duplex seam
+
+The duplex loop uses the general-purpose SSE capability on
`juneau-rest-client`:
+
+- `RestRequest.openEventStream()`
+- `ResponseBody.asEventStream()`
+
+Inbound server->client requests are dispatched through
`McpServerRequestHandler` as raw `JsonRpcRequest` payloads; params remain
generic `JsonMap`/`Object` and are not typed or rewritten in the seam.
+
+## Auth seam
+
+`McpAuthInterceptor` is the client-side auth seam. It injects `Authorization:
Bearer ...` from a supplier callback at request-init time. OAuth/OIDC flows
plug in through the supplier implementation.
+
+## Response cache seam
+
+`McpResponseCache` is opt-in and off by default. `InMemoryMcpResponseCache` is
the built-in default implementation. The v2 adapter applies protocol cache
hints (`ttlMs`, `cacheScope`) when available.
+
+## Revision binding
+
+A client instance is revision-bound by construction:
+
+- Use `org.apache.juneau.rest.client.mcp.v20250618.McpClient` for `2025-06-18`.
+- Use `org.apache.juneau.rest.client.mcp.v20260728.McpClient` for `2026-07-28`.
+
+There is no automatic runtime revision switching.
+
+## See Also
+
+- [juneau-rest-server-mcp](/docs/topics/JuneauRestServerMcp)
+- [juneau-bean-mcp-v20250618](/docs/topics/JuneauBeanMcp)
+- [juneau-bean-jsonrpc](/docs/topics/JuneauBeanJsonRpc)
diff --git a/sidebars.ts b/sidebars.ts
index 8a84bcb4e7..21f910f30d 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -1773,6 +1773,11 @@ const sidebars: SidebarsConfig = {
id:
'topics/10.juneau-rest-server',
},
},
+ {
+ type: 'doc',
+ id:
'topics/11.01.juneau-rest-client-mcp',
+ label: '11.1. juneau-rest-client-mcp',
+ },
{
type: 'doc',
id: 'topics/11.juneau-rest-server-mcp',
