@techwavedev/agi-agent-kit 1.6.0 → 1.6.3

package/templates/skills/extended/devops/capi-mcp-gateway/references/configuration.md

@@ -0,0 +1,200 @@
+# CAPI MCP Gateway — Complete Configuration Reference
+
+## Full `config.yaml`
+
+```yaml
+capi:
+  version: 1.0.0
+  instanceName: default
+  strictToInstanceName: true
+  publicEndpoint: http://localhost:8380/api/
+  runningMode: full                     # full | websocket | sse
+  adminPort: 8381
+  reverseProxyHost:                     # Override X-Forwarded-Host
+
+  rest:
+    enabled: true
+    port: 8380
+    listeningAddress: 0.0.0.0
+    contextPath: /api
+    connectionRequestTimeout: 5000
+    requestTimeout: 5000
+    responseTimeout: 120000
+    proxyPoolSize: 200
+    proxyMaxPoolSize: 500
+
+  mcp:
+    enabled: true                       # Enable MCP Gateway
+    port: 8383                          # MCP listener port
+    sessionTtl: 1800000                 # Session TTL (ms), default 30 min
+    toolCallTimeout: 30000              # Tool execution timeout (ms)
+
+  websocket:
+    enabled: false
+    port: 8382
+    listeningAddress: 0.0.0.0
+    contextPath: /api/*
+
+  grpc:
+    enabled: false
+    port: 8384
+
+  ssl:
+    enabled: false
+    keyStoreType: PKCS12
+    path:
+    password:
+
+  trustStore:
+    enabled: false
+    path:
+    encoded:                            # Base64-encoded truststore (alt to path)
+    password:
+
+  consulCatalogDiscoverInterval: 60000  # Consul poll interval (ms)
+  consulHosts:
+    - endpoint: http://localhost:8500
+      token:                            # Consul ACL token
+  consulStore:
+    enabled: false
+    endpoint: http://localhost:8500
+    token:
+
+  oauth2:
+    enabled: false
+    cookieName:
+    keys:
+      - http://localhost:8080/realms/capi/protocol/openid-connect/certs
+
+  opa:
+    enabled: false
+    endpoint: http://localhost:8181
+
+  traces:
+    enabled: false
+    serviceName: capi
+    endpoint: http://localhost:4318     # OTLP endpoint
+    extraMetadataPrefix:
+
+  corsEnabled: false
+  allowedHeaders:
+    - Origin
+    - Accept
+    - X-Requested-With
+    - Content-Type
+    - Access-Control-Request-Method
+    - Authorization
+
+  throttle:
+    enabled: false
+    kubernetesNamespace:
+    kubernetesServiceName:
+```
+
+---
+
+## MCP-Specific Fields
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `mcp.enabled` | `false` | Start the MCP listener |
+| `mcp.port` | `8383` | Port for MCP JSON-RPC endpoint |
+| `mcp.sessionTtl` | `1800000` | Session time-to-live in ms (30 min) |
+| `mcp.toolCallTimeout` | `30000` | Per-tool execution timeout in ms |
+
+---
+
+## Ports Summary
+
+| Port | Purpose | Config Key |
+|------|---------|------------|
+| 8380 | REST Gateway | `capi.rest.port` |
+| 8381 | Admin API | `capi.adminPort` |
+| 8382 | WebSocket / SSE | `capi.websocket.port` |
+| 8383 | **MCP Gateway** | `capi.mcp.port` |
+| 8384 | gRPC Gateway | `capi.grpc.port` |
+
+---
+
+## Consul MCP Metadata (Service Registration)
+
+| Key | Required | Description |
+|-----|----------|-------------|
+| `group` | **Yes** | Route group (e.g. `v1`). Services without `group` are ignored. |
+| `mcp-enabled` | **Yes** | `"true"` to expose as MCP tools |
+| `mcp-tools` | **Yes** | Comma-separated tool names |
+| `mcp-tools-{name}-description` | **Yes** | Human-readable description per tool |
+| `mcp-tools-{name}-inputSchema` | Recommended | JSON Schema string for tool input |
+| `mcp-toolPrefix` | Recommended | Namespace prefix (e.g. `orders` → `orders.get`) |
+| `mcp-streaming` | No | Tools supporting SSE streaming |
+| `mcp-category` | No | Semantic category for OPA policies |
+| `mcp-timeout` | No | Per-service timeout override (ms) |
+| `root-context` | No | Backend path prefix (default `/`) |
+| `scheme` | No | `http` or `https` (default `http`) |
+| `secured` | No | Require OAuth2 for this service |
+| `opa-rego` | No | OPA policy path for authorization |
+
+---
+
+## Docker Compose Example
+
+```yaml
+version: "3.8"
+services:
+  consul:
+    image: hashicorp/consul:1.17
+    ports:
+      - "8500:8500"
+    command: agent -dev -client=0.0.0.0
+
+  capi:
+    image: surisoft/capi-core
+    ports:
+      - "8380:8380"
+      - "8381:8381"
+      - "8383:8383"
+    volumes:
+      - ./config.yaml:/capi/config/config.yaml
+    environment:
+      CAPI_CONFIG_FILE: /capi/config/config.yaml
+    depends_on:
+      - consul
+
+  # Example backend (your REST API)
+  order-service:
+    image: my-order-service:latest
+    ports:
+      - "8080:8080"
+```
+
+---
+
+## Helm Values (Kubernetes)
+
+Key values for MCP:
+
+```yaml
+capi:
+  mcp:
+    enabled: true
+    port: 8383
+
+# Expose MCP port in service
+service:
+  ports:
+    - name: mcp
+      port: 8383
+      targetPort: 8383
+
+# Ingress for MCP (optional)
+ingress:
+  enabled: true
+  hosts:
+    - host: mcp.example.com
+      paths:
+        - path: /mcp
+          pathType: Prefix
+          servicePort: 8383
+```
+
+See [helm/capi-core/values.yaml](https://github.com/surisoft-io/capi-core/blob/main/helm/capi-core/values.yaml) for all options.

package/templates/skills/extended/devops/capi-mcp-gateway/references/security.md

@@ -0,0 +1,199 @@
+# CAPI MCP Gateway — Security & Authorization
+
+## OAuth2 / OIDC Configuration
+
+Enable JWT token validation in `config.yaml`:
+
+```yaml
+capi:
+  oauth2:
+    enabled: true
+    cookieName: auth_token       # optional, for browser clients
+    keys:
+      - http://keycloak:8080/realms/capi/protocol/openid-connect/certs
+      # Multiple OIDC providers supported:
+      - http://auth0.com/.well-known/jwks.json
+```
+
+When enabled, ALL MCP requests require a valid Bearer token:
+
+```bash
+curl -X POST http://localhost:8383/mcp \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"initialize","id":1}'
+```
+
+Per-service opt-in: set `"secured": "true"` in Consul metadata to require auth for specific services only.
+
+---
+
+## OPA Authorization
+
+Enable Open Policy Agent for fine-grained tool-level authorization:
+
+```yaml
+capi:
+  opa:
+    enabled: true
+    endpoint: http://localhost:8181
+```
+
+### OPA Input for MCP Requests
+
+CAPI extends the standard OPA input with MCP context:
+
+```json
+{
+  "input": {
+    "method": "tools/call",
+    "path": "/mcp",
+    "token": {
+      "sub": "user@example.com",
+      "roles": ["analyst"],
+      "iss": "https://keycloak/realms/capi"
+    },
+    "mcp": {
+      "sessionId": "abc-123",
+      "toolName": "orders.get",
+      "toolCategory": "commerce",
+      "clientIdentity": "claude-desktop"
+    }
+  }
+}
+```
+
+### Example Rego Policies
+
+**Allow only specific roles to call tools:**
+
+```rego
+package capi.mcp_policy
+
+default allow = false
+
+# Allow analysts to use commerce tools
+allow {
+    input.token.roles[_] == "analyst"
+    input.mcp.toolCategory == "commerce"
+}
+
+# Allow admins to use everything
+allow {
+    input.token.roles[_] == "admin"
+}
+```
+
+**Restrict specific tools:**
+
+```rego
+package capi.mcp_policy
+
+default allow = false
+
+# Block destructive tools for read-only users
+allow {
+    input.token.roles[_] == "viewer"
+    not endswith(input.mcp.toolName, ".delete")
+    not endswith(input.mcp.toolName, ".create")
+}
+
+# Full access for editors
+allow {
+    input.token.roles[_] == "editor"
+}
+```
+
+**Rate-limit by tool category:**
+
+```rego
+package capi.mcp_policy
+
+default allow = true
+
+# Deny access to financial tools outside business hours
+deny {
+    input.mcp.toolCategory == "finance"
+    not is_business_hours
+}
+
+is_business_hours {
+    time.clock(time.now_ns())[0] >= 9
+    time.clock(time.now_ns())[0] < 17
+}
+
+allow {
+    not deny
+}
+```
+
+### Consul Metadata for OPA
+
+Set `opa-rego` in service metadata to specify the policy path:
+
+```json
+{
+  "Meta": {
+    "mcp-enabled": "true",
+    "mcp-category": "commerce",
+    "opa-rego": "capi/mcp_policy"
+  }
+}
+```
+
+---
+
+## Claude Desktop with Auth
+
+When OAuth2 is enabled, use `mcp-remote` with auth headers:
+
+```json
+{
+  "mcpServers": {
+    "capi": {
+      "command": "npx",
+      "args": [
+        "-y", "mcp-remote",
+        "http://localhost:8383/mcp",
+        "--header", "Authorization: Bearer ${CAPI_TOKEN}"
+      ]
+    }
+  }
+}
+```
+
+Set `CAPI_TOKEN` as an environment variable for token management.
+
+---
+
+## TLS / SSL
+
+Enable TLS termination on all CAPI listeners:
+
+```yaml
+capi:
+  ssl:
+    enabled: true
+    keyStoreType: PKCS12
+    path: /certs/keystore.p12
+    password: changeit
+
+  trustStore:
+    enabled: true
+    path: /certs/truststore.jks
+    password: changeit
+```
+
+With TLS, MCP endpoint becomes `https://localhost:8383/mcp`.
+
+---
+
+## Security Checklist
+
+- [ ] Enable OAuth2 with at least one JWKS endpoint
+- [ ] Configure OPA policies for tool-level authorization
+- [ ] Set `"secured": "true"` on sensitive Consul services
+- [ ] Use TLS in production
+- [ ] Set `mcp-category` on services to enable category-based OPA policies
+- [ ] Review session TTL (default 30 min) — shorten for high-security environments
+- [ ] Monitor active sessions via `GET /info/mcp/sessions`

package/templates/skills/extended/devops/capi-mcp-gateway/scripts/capi_mcp_client.py

@@ -0,0 +1,255 @@
+#!/usr/bin/env python3
+"""
+Script: capi_mcp_client.py
+Purpose: CLI client for interacting with CAPI MCP Gateway
+
+Usage:
+    python capi_mcp_client.py --url http://localhost:8383/mcp init
+    python capi_mcp_client.py --url http://localhost:8383/mcp --session <id> list-tools
+    python capi_mcp_client.py --url http://localhost:8383/mcp --session <id> call --tool orders.get --args '{"orderId":"123"}'
+    python capi_mcp_client.py --url http://localhost:8383/mcp ping
+    python capi_mcp_client.py --admin-url http://localhost:8381 status
+
+Exit Codes:
+    0 - Success
+    1 - Invalid arguments
+    2 - Connection error
+    3 - MCP protocol error
+    4 - Unexpected error
+"""
+
+import argparse
+import json
+import sys
+
+try:
+    import requests
+except ImportError:
+    print(json.dumps({
+        "status": "error",
+        "message": "Missing dependency: pip install requests"
+    }), file=sys.stderr)
+    sys.exit(1)
+
+
+def jsonrpc_call(url, method, params=None, req_id=1, session_id=None, token=None):
+    """Send a JSON-RPC 2.0 request to the CAPI MCP endpoint."""
+    body = {"jsonrpc": "2.0", "method": method, "id": req_id}
+    if params:
+        body["params"] = params
+
+    headers = {"Content-Type": "application/json"}
+    if session_id:
+        headers["Mcp-Session-Id"] = session_id
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+
+    try:
+        resp = requests.post(url, json=body, headers=headers, timeout=30)
+        resp.raise_for_status()
+    except requests.ConnectionError:
+        print(json.dumps({
+            "status": "error",
+            "message": f"Cannot connect to {url}"
+        }), file=sys.stderr)
+        sys.exit(2)
+    except requests.HTTPError as e:
+        print(json.dumps({
+            "status": "error",
+            "message": f"HTTP {e.response.status_code}: {e.response.text}"
+        }), file=sys.stderr)
+        sys.exit(2)
+
+    session = resp.headers.get("Mcp-Session-Id")
+    data = resp.json()
+
+    if "error" in data:
+        print(json.dumps({
+            "status": "mcp_error",
+            "code": data["error"]["code"],
+            "message": data["error"]["message"]
+        }), file=sys.stderr)
+        sys.exit(3)
+
+    return data["result"], session
+
+
+def cmd_init(args):
+    """Initialize MCP session."""
+    result, session_id = jsonrpc_call(
+        args.url, "initialize", token=args.token
+    )
+    output = {
+        "status": "success",
+        "session_id": session_id,
+        "server_info": result.get("serverInfo", {}),
+        "capabilities": result.get("capabilities", {}),
+        "protocol_version": result.get("protocolVersion", "")
+    }
+    print(json.dumps(output, indent=2))
+
+
+def cmd_list_tools(args):
+    """List available MCP tools."""
+    if not args.session:
+        print(json.dumps({
+            "status": "error",
+            "message": "Session ID required. Run 'init' first."
+        }), file=sys.stderr)
+        sys.exit(1)
+
+    result, _ = jsonrpc_call(
+        args.url, "tools/list", req_id=2,
+        session_id=args.session, token=args.token
+    )
+    tools = result.get("tools", [])
+    output = {
+        "status": "success",
+        "tool_count": len(tools),
+        "tools": [{
+            "name": t["name"],
+            "description": t.get("description", ""),
+            "input_schema": t.get("inputSchema", {})
+        } for t in tools]
+    }
+    print(json.dumps(output, indent=2))
+
+
+def cmd_call(args):
+    """Call an MCP tool."""
+    if not args.session:
+        print(json.dumps({
+            "status": "error",
+            "message": "Session ID required. Run 'init' first."
+        }), file=sys.stderr)
+        sys.exit(1)
+    if not args.tool:
+        print(json.dumps({
+            "status": "error",
+            "message": "--tool is required for 'call' command"
+        }), file=sys.stderr)
+        sys.exit(1)
+
+    arguments = {}
+    if args.args:
+        try:
+            arguments = json.loads(args.args)
+        except json.JSONDecodeError:
+            print(json.dumps({
+                "status": "error",
+                "message": f"Invalid JSON in --args: {args.args}"
+            }), file=sys.stderr)
+            sys.exit(1)
+
+    result, _ = jsonrpc_call(
+        args.url, "tools/call", req_id=3,
+        params={"name": args.tool, "arguments": arguments},
+        session_id=args.session, token=args.token
+    )
+    content = result.get("content", [])
+    output = {
+        "status": "success",
+        "tool": args.tool,
+        "result": content[0]["text"] if content else None
+    }
+    print(json.dumps(output, indent=2))
+
+
+def cmd_ping(args):
+    """Ping the MCP endpoint."""
+    result, _ = jsonrpc_call(args.url, "ping", token=args.token)
+    print(json.dumps({"status": "success", "ping": "ok"}, indent=2))
+
+
+def cmd_status(args):
+    """Check MCP gateway status via Admin API."""
+    admin_url = args.admin_url or "http://localhost:8381"
+    try:
+        # MCP info
+        mcp_resp = requests.get(f"{admin_url}/info/mcp", timeout=10)
+        mcp_data = mcp_resp.json() if mcp_resp.ok else {"error": mcp_resp.status_code}
+
+        # Health
+        health_resp = requests.get(f"{admin_url}/info/health", timeout=10)
+        health_data = health_resp.json() if health_resp.ok else {"error": health_resp.status_code}
+
+        output = {
+            "status": "success",
+            "health": health_data,
+            "mcp": mcp_data
+        }
+        print(json.dumps(output, indent=2))
+    except requests.ConnectionError:
+        print(json.dumps({
+            "status": "error",
+            "message": f"Cannot connect to admin API at {admin_url}"
+        }), file=sys.stderr)
+        sys.exit(2)
+
+
+def cmd_tools_admin(args):
+    """List tools via Admin API (no session required)."""
+    admin_url = args.admin_url or "http://localhost:8381"
+    try:
+        resp = requests.get(f"{admin_url}/info/mcp/tools", timeout=10)
+        if resp.ok:
+            print(json.dumps({
+                "status": "success",
+                "tools": resp.json()
+            }, indent=2))
+        else:
+            print(json.dumps({
+                "status": "error",
+                "message": f"HTTP {resp.status_code}: {resp.text}"
+            }), file=sys.stderr)
+            sys.exit(2)
+    except requests.ConnectionError:
+        print(json.dumps({
+            "status": "error",
+            "message": f"Cannot connect to admin API at {admin_url}"
+        }), file=sys.stderr)
+        sys.exit(2)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="CLI client for CAPI MCP Gateway"
+    )
+    parser.add_argument("--url", default="http://localhost:8383/mcp",
+                        help="MCP endpoint URL")
+    parser.add_argument("--admin-url", default="http://localhost:8381",
+                        help="Admin API URL")
+    parser.add_argument("--session", help="MCP session ID")
+    parser.add_argument("--token", help="Bearer token for OAuth2")
+    parser.add_argument("--tool", help="Tool name (for 'call' command)")
+    parser.add_argument("--args", help="Tool arguments as JSON string")
+
+    parser.add_argument("command",
+                        choices=["init", "list-tools", "call", "ping",
+                                 "status", "tools-admin"],
+                        help="Command to execute")
+
+    args = parser.parse_args()
+
+    commands = {
+        "init": cmd_init,
+        "list-tools": cmd_list_tools,
+        "call": cmd_call,
+        "ping": cmd_ping,
+        "status": cmd_status,
+        "tools-admin": cmd_tools_admin,
+    }
+
+    try:
+        commands[args.command](args)
+    except Exception as e:
+        print(json.dumps({
+            "status": "error",
+            "type": type(e).__name__,
+            "message": str(e)
+        }), file=sys.stderr)
+        sys.exit(4)
+
+
+if __name__ == "__main__":
+    main()