This is an automated email from the ASF dual-hosted git repository.
robertlazarski pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/axis-axis2-java-core.git
The following commit(s) were added to refs/heads/master by this push:
new d75362d92e docs: Explain Axis2 JSON envelope translation in MCP bridge
section
d75362d92e is described below
commit d75362d92e54e34655f9bc53cd14caf55ab422b9
Author: Robert Lazarski <[email protected]>
AuthorDate: Sun May 17 04:52:16 2026 -1000
docs: Explain Axis2 JSON envelope translation in MCP bridge section
Replace terse one-liner with explanation of how the bridge translates
between standard MCP JSON-RPC 2.0 and Axis2's internal JSON convention,
including why the arg0 wrapper and array envelope exist (SOAP/XML
heritage via Axiom OMElement tree).
Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
---
src/site/markdown/docs/mcp-architecture.md | 13 +++++++++++--
1 file changed, 11 insertions(+), 2 deletions(-)
diff --git a/src/site/markdown/docs/mcp-architecture.md
b/src/site/markdown/docs/mcp-architecture.md
index bb2a71d5ff..a6ff407b05 100644
--- a/src/site/markdown/docs/mcp-architecture.md
+++ b/src/site/markdown/docs/mcp-architecture.md
@@ -211,8 +211,17 @@ handshake is straightforward enough to hand-roll correctly.
**Build**: maven-shade-plugin 3.6.0 produces
`axis2-mcp-bridge-2.0.1-SNAPSHOT-exe.jar`
(classifier: `exe`) with `MainClass=McpBridgeMain`.
-**Axis2 JSON-RPC envelope**: `tools/call` wraps arguments as `{toolName:
[arguments]}`
-before POSTing to the Axis2 endpoint, matching the existing JSON-RPC
convention.
+**Axis2 JSON envelope translation**: The bridge translates between standard MCP
+JSON-RPC 2.0 and Axis2's internal JSON convention. MCP sends clean named
parameters
+(`{"nAssets":5, "weights":[...]}`); the bridge wraps them into the envelope
that
+Axis2's `JsonRpcMessageReceiver` expects: `{"operationName":[{arguments}]}`.
The
+array wrapper and operation-name-as-key pattern are artifacts of Axis2's
SOAP/XML
+heritage — the JSON formatter maps the request body to an Axiom `OMElement`
tree
+where the operation name is the root element and each array entry corresponds
to
+a Java method parameter. When the service method takes a single POJO argument,
+callers see `{"operationName":[{"arg0":{...}}]}` where `arg0` is the default
WSDL
+parameter name. The bridge hides this from AI clients so they see only standard
+JSON-RPC 2.0.
**Notifications**: MCP `notifications/initialized` (no `id` field) is silently
consumed
with no response, as required by JSON-RPC 2.0.
