@skaleagents/swarm 0.3.0 → 0.4.0

package/README.md

@@ -1,7 +1,7 @@
 # @skaleagents/swarm
 
-Public stdio MCP server for SkaleAgents Phase 1. Talks to the Laravel **api**
-over JSON and uses browser OAuth for sign-in.
+SkaleAgents MCP server with local stdio and hosted Streamable HTTP transports.
+Uses browser OAuth for sign-in.
 
 Tools: `review_architecture`, `scan_iac_stub`.
 
@@ -9,9 +9,26 @@ Tools: `review_architecture`, `scan_iac_stub`.
 client reads the files in its workspace and sends the relevant content through
 the MCP tool for a structured review.
 
-## Prerequisites
+## Hosted connection
 
-1. **API running:** Sail on `http://localhost:8082` (or your hosted API URL later).
+Use `https://skaleagents.com/mcp` in Claude Desktop or ChatGPT's custom connector
+settings. Choose OAuth and leave client ID and secret fields blank. The client
+registers itself, opens Google sign-in, and asks you to approve MCP access.
+See [client setup](https://skaleagents.com/settings) for Cursor, Claude Code,
+Claude Desktop, ChatGPT, and Codex instructions.
+
+The web app hosts this endpoint using `handleMcpRequest` from
+`@skaleagents/swarm/http`. It validates each bearer credential with the API's
+`/api/oauth/mcp-token` endpoint before running a tool. Tokens are bound to the
+MCP resource and cannot access unrelated API routes. Credentials are not
+forwarded to the public bot directory.
+
+`protectedResourceMetadata` exports the discovery response for
+`/.well-known/oauth-protected-resource/mcp`.
+
+## Local stdio prerequisites
+
+1. Node.js 20 or newer. The client connects to `https://api.skaleagents.com` by default.
 2. A browser that can open the SkaleAgents sign-in page.
 
 The first tool call opens browser sign-in. Approve MCP access there and return
@@ -67,17 +84,14 @@ Dev without build:
 }
 ```
 
-### Option B: after npm publish (hosted API)
+### Option B: published package (hosted API)
 
 ```json
 {
   "mcpServers": {
     "skaleagents": {
       "command": "npx",
-      "args": ["-y", "@skaleagents/swarm"],
-      "env": {
-        "PLATFORM_API_URL": "https://api.skaleagents.com"
-      }
+      "args": ["-y", "@skaleagents/swarm@0.4.0"]
     }
   }
 }
@@ -87,16 +101,17 @@ Restart Cursor after saving. In Agent/Chat, tools should appear as `review_archi
 
 ## Claude Code
 
-Point `command`/`args` at `node .../dist/index.js` or `npx @skaleagents/swarm` once published. OAuth starts on the first tool call.
+Use the published package configuration above in `.mcp.json`. OAuth starts on the first tool call. No API URL or keys are needed.
 
 ## Environment
 
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `SKALEAGENTS_API_TOKEN` | No | Legacy Sanctum bearer-token override. OAuth is used when empty. |
-| `PLATFORM_API_URL` | No | Default `http://localhost:8082` |
+| `PLATFORM_API_URL` | No | Defaults to `https://api.skaleagents.com`. Override only for local development or another API deployment. Empty values use the default. |
 | `SKALEAGENTS_OAUTH_CACHE` | No | OAuth cache path. Default `~/.config/skaleagents/oauth.json`. |
 | `SKALEAGENTS_OAUTH_ENABLED` | No | Set to `false` only to disable browser OAuth. |
+| `MCP_RESOURCE_URL` | No | Hosted transport audience. Defaults to `https://skaleagents.com/mcp`; must match the API OAuth configuration. |
 
 ## Auth behavior
 

package/dist/config.js

@@ -1,7 +1,7 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
 export function getApiUrl() {
-    return (process.env.PLATFORM_API_URL?.replace(/\/$/, "") ?? "http://localhost:8082");
+    return (process.env.PLATFORM_API_URL?.trim().replace(/\/+$/, "") || "https://api.skaleagents.com");
 }
 export function getApiToken() {
     return process.env.SKALEAGENTS_API_TOKEN?.trim() ?? "";

package/dist/http.d.ts

@@ -0,0 +1,2 @@
+export declare function protectedResourceMetadata(): Response;
+export declare function handleMcpRequest(request: Request): Promise<Response>;

package/dist/http.js

@@ -0,0 +1,134 @@
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { createServer } from "./server.js";
+import { getApiUrl } from "./config.js";
+const resource = process.env.MCP_RESOURCE_URL ?? "https://skaleagents.com/mcp";
+const metadataUrl = `${new URL(resource).origin}/.well-known/oauth-protected-resource/mcp`;
+const allowedOrigins = new Set([
+    "https://claude.ai",
+    "https://chatgpt.com",
+    "https://platform.openai.com",
+    new URL(resource).origin,
+]);
+const headers = {
+    "Cache-Control": "no-store",
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
+    "Access-Control-Allow-Headers": "Authorization, Content-Type, Accept, MCP-Protocol-Version, MCP-Session-Id, Last-Event-ID",
+    "Access-Control-Expose-Headers": "WWW-Authenticate, MCP-Session-Id, MCP-Protocol-Version",
+};
+function json(status, body, extraHeaders = {}) {
+    return Response.json(body, {
+        status,
+        headers: { ...headers, ...extraHeaders },
+    });
+}
+function challenge() {
+    return json(401, { error: "unauthorized" }, {
+        "WWW-Authenticate": `Bearer resource_metadata="${metadataUrl}", scope="mcp"`,
+    });
+}
+export function protectedResourceMetadata() {
+    return json(200, {
+        resource,
+        authorization_servers: [getApiUrl()],
+        scopes_supported: ["mcp"],
+        bearer_methods_supported: ["header"],
+        resource_documentation: "https://skaleagents.com/settings",
+    });
+}
+export async function handleMcpRequest(request) {
+    const origin = request.headers.get("origin");
+    if (origin && !allowedOrigins.has(origin))
+        return json(403, { error: "origin_not_allowed" });
+    if (request.method === "OPTIONS")
+        return new Response(null, { status: 204, headers });
+    const authorization = request.headers.get("authorization");
+    if (!authorization || !/^Bearer [^\s]+$/i.test(authorization))
+        return challenge();
+    try {
+        // Validate the opaque token with its issuer, including the MCP audience.
+        const validation = await fetch(`${getApiUrl()}/api/oauth/mcp-token`, {
+            headers: { Authorization: authorization, Accept: "application/json" },
+            signal: AbortSignal.timeout(10_000),
+            redirect: "error",
+            cache: "no-store",
+        });
+        if (validation.status === 401 || validation.status === 403)
+            return challenge();
+        if (!validation.ok)
+            return json(503, { error: "authorization_unavailable" });
+        const token = (await validation.json());
+        if (!token.active ||
+            token.resource !== resource ||
+            token.scope !== "mcp" ||
+            !token.expiresAt ||
+            token.expiresAt * 1000 <= Date.now()) {
+            return challenge();
+        }
+    }
+    catch {
+        return json(503, { error: "authorization_unavailable" });
+    }
+    if (request.method !== "POST")
+        return json(405, { error: "method_not_allowed" }, { Allow: "POST, OPTIONS" });
+    if (!request.headers.get("content-type")?.startsWith("application/json"))
+        return json(415, { error: "expected_json" });
+    let body;
+    try {
+        const reader = request.body?.getReader();
+        if (!reader)
+            return json(400, { error: "missing_body" });
+        const chunks = [];
+        let size = 0;
+        try {
+            for (;;) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                size += value.byteLength;
+                if (size > 2_100_000) {
+                    await reader.cancel();
+                    return json(413, { error: "request_too_large" });
+                }
+                chunks.push(value);
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        return json(400, {
+            jsonrpc: "2.0",
+            id: null,
+            error: { code: -32700, message: "Invalid JSON" },
+        });
+    }
+    const server = createServer(true);
+    const transport = new WebStandardStreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+        enableJsonResponse: true,
+    });
+    try {
+        await server.connect(transport);
+        const response = await transport.handleRequest(request, {
+            parsedBody: body,
+        });
+        // Finish the JSON response before closing this request-scoped transport.
+        const responseBody = await response.arrayBuffer();
+        const responseHeaders = new Headers(response.headers);
+        for (const [key, value] of Object.entries(headers))
+            responseHeaders.set(key, value);
+        return new Response(responseBody.byteLength ? responseBody : null, {
+            status: response.status,
+            headers: responseHeaders,
+        });
+    }
+    catch {
+        return json(500, { error: "mcp_request_failed" });
+    }
+    finally {
+        await server.close();
+    }
+}

package/dist/index.js

@@ -1,91 +1,9 @@
 #!/usr/bin/env node
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-import { getApiAccessToken, requireApiAuth, unauthorizedContent, } from "./auth.js";
-import { architectureFindings, countIacResources, fetchPublicBotHints, } from "./review.js";
-const server = new McpServer({
-    name: "skaleagents-swarm",
-    version: "0.3.0",
-});
-server.registerTool("review_architecture", {
-    title: "Review architecture",
-    description: "Review application source or infrastructure text for security, reliability, and cost risks.",
-    inputSchema: {
-        content: z
-            .string()
-            .min(1)
-            .max(500_000)
-            .describe("Application source or IaC text to review"),
-        focus: z
-            .enum(["security", "reliability", "cost", "general"])
-            .optional()
-            .default("general")
-            .describe("Review focus: security, reliability, cost, general"),
-        format: z
-            .enum(["terraform", "cloudformation", "kubernetes", "application", "auto"])
-            .optional()
-            .default("auto")
-            .describe("Content format: terraform, cloudformation, kubernetes, application, auto"),
-    },
-}, async ({ content, focus, format }) => {
-    const auth = await requireApiAuth();
-    if (!auth.ok)
-        return unauthorizedContent(auth);
-    const token = await getApiAccessToken();
-    if (!token)
-        return unauthorizedContent({ ok: false, reason: "oauth_failed" });
-    const botHints = await fetchPublicBotHints(token);
-    const focusValue = focus ?? "general";
-    const formatValue = format ?? "auto";
-    const output = {
-        summary: `Structured architecture review from @skaleagents/swarm (focus=${focusValue}, format=${formatValue})`,
-        findings: architectureFindings(content, focusValue),
-        botHints,
-    };
-    return {
-        content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
-    };
-});
-server.registerTool("scan_iac_stub", {
-    title: "Scan IaC (stub)",
-    description: "Stub seam for Phase 2 DevSecOps IaC scanning.",
-    inputSchema: {
-        content: z
-            .string()
-            .min(1)
-            .max(500_000)
-            .describe("Terraform / CloudFormation / Kubernetes YAML"),
-        format: z
-            .string()
-            .optional()
-            .describe("terraform, cloudformation, kubernetes, auto"),
-    },
-}, async ({ content, format }) => {
-    const auth = await requireApiAuth();
-    if (!auth.ok)
-        return unauthorizedContent(auth);
-    const formatValue = format === "terraform" ||
-        format === "cloudformation" ||
-        format === "kubernetes" ||
-        format === "auto"
-        ? format
-        : "auto";
-    const output = {
-        status: "stub",
-        message: "Full IaC scanning lands in Phase 2 agent-swarm",
-        format: formatValue,
-        parsedResourceCount: countIacResources(content),
-    };
-    return {
-        content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
-    };
-});
-async function main() {
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-}
-main().catch((err) => {
-    console.error(err);
+import { createServer } from "./server.js";
+createServer()
+    .connect(new StdioServerTransport())
+    .catch((error) => {
+    console.error(error);
     process.exit(1);
 });

package/dist/review.d.ts

@@ -5,5 +5,5 @@ export type Finding = {
     detail: string;
 };
 export declare function architectureFindings(content: string, focus: string): Finding[];
-export declare function fetchPublicBotHints(token: string): Promise<string[]>;
+export declare function fetchPublicBotHints(token?: string): Promise<string[]>;
 export declare function countIacResources(content: string): number;

package/dist/review.js

@@ -107,9 +107,10 @@ export function architectureFindings(content, focus) {
 export async function fetchPublicBotHints(token) {
     try {
         const res = await fetch(`${getApiUrl()}/api/bots`, {
+            signal: AbortSignal.timeout(10_000),
             headers: {
                 Accept: "application/json",
-                Authorization: `Bearer ${token}`,
+                ...(token ? { Authorization: `Bearer ${token}` } : {}),
             },
         });
         if (!res.ok)

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(remote?: boolean): McpServer;

package/dist/server.js

@@ -0,0 +1,107 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { getApiAccessToken, requireApiAuth, unauthorizedContent, } from "./auth.js";
+import { architectureFindings, countIacResources, fetchPublicBotHints, } from "./review.js";
+export function createServer(remote = false) {
+    const server = new McpServer({
+        name: "skaleagents-swarm",
+        version: "0.4.0",
+    });
+    server.registerTool("review_architecture", {
+        title: "Review architecture",
+        description: "Review application source or infrastructure text for security, reliability, and cost risks.",
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+        _meta: { securitySchemes: [{ type: "oauth2", scopes: ["mcp"] }] },
+        inputSchema: {
+            content: z
+                .string()
+                .min(1)
+                .max(500_000)
+                .describe("Application source or IaC text to review"),
+            focus: z
+                .enum(["security", "reliability", "cost", "general"])
+                .optional()
+                .default("general")
+                .describe("Review focus: security, reliability, cost, general"),
+            format: z
+                .enum([
+                "terraform",
+                "cloudformation",
+                "kubernetes",
+                "application",
+                "auto",
+            ])
+                .optional()
+                .default("auto")
+                .describe("Content format: terraform, cloudformation, kubernetes, application, auto"),
+        },
+    }, async ({ content, focus, format }) => {
+        let token;
+        if (!remote) {
+            const auth = await requireApiAuth();
+            if (!auth.ok)
+                return unauthorizedContent(auth);
+            token = (await getApiAccessToken()) ?? undefined;
+            if (!token)
+                return unauthorizedContent({ ok: false, reason: "oauth_failed" });
+        }
+        const botHints = await fetchPublicBotHints(token);
+        const focusValue = focus ?? "general";
+        const formatValue = format ?? "auto";
+        const output = {
+            summary: `Structured architecture review from @skaleagents/swarm (focus=${focusValue}, format=${formatValue})`,
+            findings: architectureFindings(content, focusValue),
+            botHints,
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
+        };
+    });
+    server.registerTool("scan_iac_stub", {
+        title: "Scan IaC (stub)",
+        description: "Stub seam for Phase 2 DevSecOps IaC scanning.",
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+        _meta: { securitySchemes: [{ type: "oauth2", scopes: ["mcp"] }] },
+        inputSchema: {
+            content: z
+                .string()
+                .min(1)
+                .max(500_000)
+                .describe("Terraform / CloudFormation / Kubernetes YAML"),
+            format: z
+                .string()
+                .optional()
+                .describe("terraform, cloudformation, kubernetes, auto"),
+        },
+    }, async ({ content, format }) => {
+        if (!remote) {
+            const auth = await requireApiAuth();
+            if (!auth.ok)
+                return unauthorizedContent(auth);
+        }
+        const formatValue = format === "terraform" ||
+            format === "cloudformation" ||
+            format === "kubernetes" ||
+            format === "auto"
+            ? format
+            : "auto";
+        const output = {
+            status: "stub",
+            message: "Full IaC scanning lands in Phase 2 agent-swarm",
+            format: formatValue,
+            parsedResourceCount: countIacResources(content),
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
+        };
+    });
+    return server;
+}

package/package.json

@@ -1,12 +1,18 @@
 {
   "name": "@skaleagents/swarm",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "private": false,
   "publishConfig": {
     "access": "public"
   },
   "type": "module",
-  "description": "SkaleAgents MCP server — stdio tools against the Laravel api",
+  "description": "SkaleAgents review tools with OAuth for local and hosted MCP clients",
+  "exports": {
+    "./http": {
+      "types": "./dist/http.d.ts",
+      "import": "./dist/http.js"
+    }
+  },
   "bin": {
     "skaleagents-swarm": "dist/index.js"
   },