You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-commits@axis.apache.org by ro...@apache.org on 2026/05/16 16:18:39 UTC
(axis-axis2-java-core) 01/03: docs: Prune stale entries from MCP architecture doc
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
commit 79ad7c147338fce5dfd72468fc2eaebc82363706
Author: Robert Lazarski <ro...@gmail.com>
AuthorDate: Sat May 16 06:16:49 2026 -1000
docs: Prune stale entries from MCP architecture doc
Remove non-existent @RestMapping references (Phase 3 NOT STARTED),
prune HTTP/SSE transport sections (no market demand), add monteCarlo
Merton jump-diffusion tool schema to catalog example, update date
and WildFly validation references.
Co-Authored-By: Claude Opus 4.6 (1M context) <no...@anthropic.com>
---
src/site/markdown/docs/mcp-architecture.md | 76 +++++++++++++-----------------
1 file changed, 33 insertions(+), 43 deletions(-)
diff --git a/src/site/markdown/docs/mcp-architecture.md b/src/site/markdown/docs/mcp-architecture.md
index 4ab3b98ee9..bb2a71d5ff 100644
--- a/src/site/markdown/docs/mcp-architecture.md
+++ b/src/site/markdown/docs/mcp-architecture.md
@@ -7,13 +7,13 @@ novel Apache contribution) implements `axis2-transport-mcp` so Axis2 speaks MCP
directly — no wrapper. One service deployment, three protocols: JSON-RPC, REST, MCP.
MCP is JSON-RPC 2.0. The three required methods are `initialize`, `tools/list`, and
-`tools/call`. Everything else (transport: stdio or HTTP/SSE, tool schema format,
+`tools/call`. Everything else (transport: stdio, tool schema format,
capability negotiation) is specified by the MCP protocol document at
modelcontextprotocol.io.
---
-## Current State (2026-04-09)
+## Current State (2026-05-16)
### What exists today
@@ -27,7 +27,6 @@ modelcontextprotocol.io.
| X.509 Spring Security | ✅ Done | `X509AuthenticationFilter` at `@Order(2)`, CN → `ROLE_X509_CLIENT` |
| A3 end-to-end validation | ✅ Done | `Claude Desktop → bridge → mTLS 8443 → BigDataH2Service` confirmed |
| `axis2-spring-boot-starter` | ❌ Not started | Phase 1 of modernization plan |
-| A4 HTTP/SSE transport | ❌ Not started | Post-demo, deferred |
| `axis2-transport-mcp` native | ❌ Not started | Track B — novel Apache contribution |
### Reference implementations
@@ -43,9 +42,9 @@ springbootdemo-tomcat11 base URL: https://localhost:8443/axis2-json-api
springbootdemo-wildfly base URL: https://localhost:8443/axis2-json-api
- LoginService (JWT auth)
- - FinancialBenchmarkService (portfolioVariance, monteCarlo VaR, scenarioAnalysis)
+ - FinancialBenchmarkService (portfolioVariance, monteCarlo VaR with Merton jump-diffusion, scenarioAnalysis)
- BigDataH2Service (HTTP/2 streaming)
- Deployed and validated on WildFly 32.0.1 (2026-04-09)
+ Deployed and validated on WildFly 32 and WildFly 39
```
`BigDataH2Service` request format (confirmed working via MCP bridge):
@@ -158,6 +157,29 @@ Client presents cert → Tomcat TLS handshake (certificateVerification=required)
}
},
"endpoint": "POST /services/FinancialBenchmarkService/portfolioVariance"
+ },
+ {
+ "name": "monteCarlo",
+ "description": "Monte Carlo VaR simulation using Geometric Brownian Motion or Merton jump-diffusion...",
+ "inputSchema": {
+ "type": "object",
+ "required": [],
+ "properties": {
+ "nSimulations": {"type": "integer", "default": 10000, "maximum": 1000000},
+ "nPeriods": {"type": "integer", "default": 252},
+ "initialValue": {"type": "number", "default": 1000000},
+ "expectedReturn": {"type": "number", "default": 0.08},
+ "volatility": {"type": "number", "default": 0.20},
+ "model": {"type": "string", "default": "gbm", "enum": ["gbm", "merton"]},
+ "jumpIntensity": {"type": "number", "default": 1.0},
+ "jumpMean": {"type": "number", "default": -0.03},
+ "jumpVol": {"type": "number", "default": 0.05},
+ "nPeriodsPerYear": {"type": "integer", "default": 252},
+ "randomSeed": {"type": "integer", "default": 0},
+ "percentiles": {"type": "array", "default": [0.01, 0.05]}
+ }
+ },
+ "endpoint": "POST /services/FinancialBenchmarkService/monteCarlo"
}
]
}
@@ -228,16 +250,6 @@ Tomcat log confirmation:
X509AuthenticationFilter: authenticated CN=axis2-mcp-bridge on port 8443
```
-### A4 — HTTP/SSE transport (deferred)
-
-Adds persistent server mode (multiple Claude sessions sharing one bridge). Required for
-production. Additive — no changes to Axis2 side or tool catalog format.
-
-```
-POST /mcp → JSON-RPC request
-GET /mcp/sse → SSE stream for server-initiated messages
-```
-
---
## Track B — Native MCP Transport (`axis2-transport-mcp`)
@@ -267,13 +279,6 @@ axis2-transport-mcp
MCP tools/call result (JSON-RPC 2.0)
```
-### Sequencing within Track B
-
-1. **stdio first** — simpler, no connection management, validates the
- JSON-RPC 2.0 ↔ MessageContext translation layer end-to-end
-2. **HTTP/SSE second** — reuses Axis2's existing HTTP infrastructure, adds
- SSE for progress notifications on long-running service operations
-
### Tool schema generation
Populated from `axis2-openapi` Phase 2 output. `initialize` response includes
@@ -283,8 +288,7 @@ Populated from `axis2-openapi` Phase 2 output. `initialize` response includes
```properties
axis2.transport.mcp.enabled=true
-axis2.transport.mcp.transport=stdio # or http
-axis2.transport.mcp.path=/mcp # only for http transport
+axis2.transport.mcp.transport=stdio
```
### End state
@@ -292,7 +296,7 @@ axis2.transport.mcp.path=/mcp # only for http transport
```
Claude Desktop / AI agent → MCP (axis2-transport-mcp, native)
↓
-REST clients → REST (@RestMapping, Phase 3) → Axis2 Service
+REST clients → REST (planned, Phase 3) → Axis2 Service
↑ (one Java class)
Existing JSON-RPC callers → JSON-RPC (unchanged)
```
@@ -301,9 +305,9 @@ Existing JSON-RPC callers → JSON-RPC (unchanged)
## Key Design Decisions
-**Why stdio first for both tracks**: Simplest MCP transport, zero port conflicts,
-works immediately with Claude Desktop and Cursor. Validates the translation layer before
-adding HTTP connection management complexity.
+**Why stdio transport**: Simplest MCP transport, zero port conflicts,
+works immediately with Claude Desktop and Cursor. No market demand yet for
+HTTP/SSE transport — stdio covers all current use cases.
**Why OpenAPI as the bridge, not direct Axis2 introspection**: `/openapi-mcp.json`
decouples the bridge from Axis2 internals. The bridge works against any HTTP service
@@ -325,11 +329,6 @@ enforces the TLS handshake before any HTTP processing. Invalid client certs are
at the TCP layer — Spring Security never sees them. `X509AuthenticationFilter` only
needs to extract identity from an already-verified cert, not verify it.
-**Why not JAX-RS instead of `@RestMapping`**: JAX-RS brings a second framework
-dependency and its own lifecycle. `@RestMapping` is a thin annotation processed by
-Axis2's existing REST dispatcher — no container dependency, backwards compatible,
-opt-in per-operation.
-
---
## Next Steps
@@ -339,13 +338,11 @@ opt-in per-operation.
| Step | Work | Notes |
|------|------|-------|
| `mcpInputSchema` in services.xml | ✅ Done | All financial benchmark tools + login have full parameter schemas |
-| A4 HTTP/SSE | Persistent bridge server mode | Required for production, additive |
### Track B
1. `modules/transport-mcp/` — new module scaffolding
-2. stdio transport first (B1) — validates JSON-RPC 2.0 ↔ MessageContext translation
-3. HTTP/SSE transport (B2) — reuses Axis2 HTTP infrastructure
+2. stdio transport (B1) — validates JSON-RPC 2.0 ↔ MessageContext translation
### Testing matrix
@@ -398,13 +395,6 @@ Monte Carlo 100K paths in ~0.7 seconds, 500-asset portfolio variance in
Both implementations expose identical MCP tool schemas — an AI assistant
configured with either backend gets the same financial capabilities.
-### Stdio transport only (HTTP/SSE deferred)
-
-The MCP bridge currently supports stdio transport only (Claude Desktop
-subprocess model). HTTP/SSE transport (A4) — which would enable Claude
-API tool use, multi-user bridge sharing, and remote MCP clients — is
-deferred. Contributions welcome.
-
### Auto-generated inputSchema from Java types
When `mcpInputSchema` is not set in `services.xml`, the MCP catalog