openapi-mcp: add Axis2 JSON-RPC format docs, auth annotations, MCP 2025 hints

Driven by gaps identified against Python rapi-mcp, pyRapi, and
internal-alpha-theory-mcp.

OpenApiSpecGenerator.generateMcpCatalogJson():
- Add catalog-level _meta object documenting the Axis2 JSON-RPC
  transport contract (axis2JsonRpcFormat, contentType, authHeader,
  tokenEndpoint) — MCP clients need this to call services without
  an intermediary proxy
- Add x-axis2-payloadTemplate per tool: {"opName":[{"arg0":{}}]}
  (the wrapping format mandated by JsonUtils.invokeServiceClass())
- Add x-requiresAuth per tool: false for loginService (token endpoint),
  true for all other services — mirrors the two-phase auth flow in
  pyRapi/auth.py and rapi-mcp/server/rapi/api.py
- Add MCP 2025-03-26 annotations per tool (readOnlyHint, destructiveHint,
  idempotentHint, openWorldHint) — conservative defaults, overridable
  via @mcptool annotations (future work)

SwaggerUIHandler.handleMcpCatalogRequest():
- Add Cache-Control: no-cache, no-store — catalog must not be cached
  as service list changes on deployment

Tests (McpCatalogGeneratorTest, McpCatalogHandlerTest):
- 30+ new test methods covering _meta, payload template structure,
  auth annotations, MCP 2025 annotations, Cache-Control, security headers

New test file McpAxis2PayloadTest.java (30 tests):
- Structural validation of the Axis2 JSON-RPC payload template format
- Two-phase auth flow (loginService → Bearer → protected service)
- pyRapi format compatibility ({"doLogin":[{"arg0":{}}]})
- All-tools consistency checks (template key matches tool name, etc.)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: robertlazarski

modules/openapi/src/main/java/org/apache/axis2/openapi/OpenApiSpecGenerator.java

@@ -649,6 +649,19 @@ public String generateMcpCatalogJson(HttpServletRequest request) {
             com.fasterxml.jackson.databind.ObjectMapper jackson =
                     new com.fasterxml.jackson.databind.ObjectMapper();
             com.fasterxml.jackson.databind.node.ObjectNode root = jackson.createObjectNode();
+
+            // Catalog-level metadata so MCP clients understand the transport layer.
+            // Axis2 JSON-RPC requires every call to be wrapped as:
+            //   {"<operationName>":[{"arg0":{<params>}}]}
+            // This is mandated by JsonUtils.invokeServiceClass() in axis2-json.
+            // The loginService/doLogin operation is the token endpoint; all other
+            // operations require "Authorization: Bearer <token>" in the request header.
+            com.fasterxml.jackson.databind.node.ObjectNode meta = root.putObject("_meta");
+            meta.put("axis2JsonRpcFormat", "{\"<operationName>\":[{\"arg0\":{<params>}}]}");
+            meta.put("contentType", "application/json");
+            meta.put("authHeader", "Authorization: Bearer <token>");
+            meta.put("tokenEndpoint", "POST /services/loginService/doLogin");
+
             com.fasterxml.jackson.databind.node.ArrayNode toolsArray = root.putArray("tools");
 
             Iterator<AxisService> services = axisConfig.getServices().values().iterator();
@@ -657,6 +670,10 @@ public String generateMcpCatalogJson(HttpServletRequest request) {
                 if (isSystemService(service)) continue;
                 if (!shouldIncludeService(service)) continue;
 
+                // loginService is the unauthenticated token endpoint; all others require auth.
+                String svcLower = service.getName().toLowerCase(java.util.Locale.ROOT);
+                boolean requiresAuth = !svcLower.contains("login") && !svcLower.equals("adminconsole");
+
                 Iterator<AxisOperation> operations = service.getOperations();
                 while (operations.hasNext()) {
                     AxisOperation operation = operations.next();
@@ -678,6 +695,25 @@ public String generateMcpCatalogJson(HttpServletRequest request) {
                     schema.putArray("required");
 
                     toolNode.put("endpoint", "POST " + path);
+
+                    // Axis2 JSON-RPC payload template.  MCP clients must wrap the call
+                    // body in this envelope — the bare {"field":value} object goes inside
+                    // "arg0".  Example for portfolioVariance:
+                    //   {"portfolioVariance":[{"arg0":{"nAssets":2,"weights":[0.6,0.4],...}}]}
+                    toolNode.put("x-axis2-payloadTemplate",
+                            "{\"" + opName + "\":[{\"arg0\":{}}]}");
+
+                    // Whether the caller must supply a Bearer token (from doLogin).
+                    toolNode.put("x-requiresAuth", requiresAuth);
+
+                    // MCP 2025-03-26 tool annotations — conservative defaults.
+                    // Override via @McpTool when richer metadata is available.
+                    com.fasterxml.jackson.databind.node.ObjectNode annotations =
+                            toolNode.putObject("annotations");
+                    annotations.put("readOnlyHint", false);
+                    annotations.put("destructiveHint", false);
+                    annotations.put("idempotentHint", false);
+                    annotations.put("openWorldHint", false);
                 }
             }
 

modules/openapi/src/main/java/org/apache/axis2/openapi/SwaggerUIHandler.java

@@ -206,6 +206,9 @@ public void handleMcpCatalogRequest(HttpServletRequest request, HttpServletRespo
 
         addSecurityHeaders(response);
         addCorsHeaders(response);
+        // MCP catalog must not be cached: service list changes on deployment and
+        // a stale catalog causes MCP clients to attempt calls to unknown tools.
+        response.setHeader("Cache-Control", "no-cache, no-store");
 
         try {
             String mcpJson = specGenerator.generateMcpCatalogJson(request);