@skaleagents/swarm 0.2.2 → 0.3.0

package/README.md

@@ -1,7 +1,7 @@
 # @skaleagents/swarm
 
 Public stdio MCP server for SkaleAgents Phase 1. Talks to the Laravel **api**
-(JSON only, no web UI) with a Sanctum bearer token.
+over JSON and uses browser OAuth for sign-in.
 
 Tools: `review_architecture`, `scan_iac_stub`.
 
@@ -12,13 +12,12 @@ the MCP tool for a structured review.
 ## Prerequisites
 
 1. **API running:** Sail on `http://localhost:8082` (or your hosted API URL later).
-2. **Bearer token:** mint one in the web app: sign in → **MCP** → Create token.
-   Or for local-only testing:
-   ```bash
-    curl -s -X POST http://localhost:8082/api/auth/google/callback \
-      -H 'Content-Type: application/json' \
-      -d '{"code":"mcp","displayName":"MCP User","email":"mcp@example.com"}' | jq -r .token
-   ```
+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
+to your AI client. The package stores the OAuth refresh credential locally and
+refreshes access automatically. You do not need to create or paste an API key.
+Active connections can be revoked from the web app's MCP settings page.
 
 ## Local development
 
@@ -27,7 +26,6 @@ git clone https://github.com/SkaleAgents/mcp-server.git
 cd mcp-server
 npm install
 cp .env.example .env
-# Set SKALEAGENTS_API_TOKEN=<token from web app or curl above>
 npm run build
 npm test
 npm run smoke   # needs API on :8082
@@ -46,7 +44,6 @@ Add to `.cursor/mcp.json` (project) or Cursor Settings → MCP:
       "command": "node",
       "args": ["/absolute/path/to/mcp-server/dist/index.js"],
       "env": {
-        "SKALEAGENTS_API_TOKEN": "<paste token from web app → API tokens>",
         "PLATFORM_API_URL": "http://localhost:8082"
       }
     }
@@ -63,7 +60,6 @@ Dev without build:
       "command": "npx",
       "args": ["tsx", "/absolute/path/to/mcp-server/src/index.ts"],
       "env": {
-        "SKALEAGENTS_API_TOKEN": "<token>",
         "PLATFORM_API_URL": "http://localhost:8082"
       }
     }
@@ -80,7 +76,6 @@ Dev without build:
       "command": "npx",
       "args": ["-y", "@skaleagents/swarm"],
       "env": {
-        "SKALEAGENTS_API_TOKEN": "<token>",
         "PLATFORM_API_URL": "https://api.skaleagents.com"
       }
     }
@@ -92,18 +87,22 @@ Restart Cursor after saving. In Agent/Chat, tools should appear as `review_archi
 
 ## Claude Code
 
-Same env vars; point `command`/`args` at `node …/dist/index.js` or `npx @skaleagents/swarm` once published.
+Point `command`/`args` at `node .../dist/index.js` or `npx @skaleagents/swarm` once published. OAuth starts on the first tool call.
 
 ## Environment
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `SKALEAGENTS_API_TOKEN` | Yes | Sanctum bearer token (from the web **MCP** page) |
+| `SKALEAGENTS_API_TOKEN` | No | Legacy Sanctum bearer-token override. OAuth is used when empty. |
 | `PLATFORM_API_URL` | No | Default `http://localhost:8082` |
+| `SKALEAGENTS_OAUTH_CACHE` | No | OAuth cache path. Default `~/.config/skaleagents/oauth.json`. |
+| `SKALEAGENTS_OAUTH_ENABLED` | No | Set to `false` only to disable browser OAuth. |
 
 ## Auth behavior
 
-- Missing/invalid token → tools return an **unauthorized** error (fail closed).
-- Token is user-scoped; bot visibility follows `api` RBAC.
+- Missing bearer override → browser OAuth starts automatically.
+- OAuth access and refresh credentials are stored with local-user-only file permissions.
+- A rejected or revoked connection returns an auth error and does not run a tool.
+- The connection is user-scoped; bot visibility follows `api` RBAC.
 
 Hub contract: [docs/contracts/mcp/tools.md](https://github.com/SkaleAgents/workspace/blob/main/docs/contracts/mcp/tools.md)

package/dist/auth.d.ts

@@ -3,12 +3,14 @@ export type AuthResult = {
     userId?: string;
 } | {
     ok: false;
-    reason: "missing_token" | "unauthorized" | "api_unavailable";
+    reason: "oauth_required" | "oauth_failed" | "unauthorized" | "api_unavailable";
 };
 /**
- * Require the API to validate the bearer token before running any tool.
+ * Validate the API bearer token before running any tool. OAuth starts in the
+ * user's browser when no legacy SKALEAGENTS_API_TOKEN is configured.
  */
 export declare function requireApiAuth(): Promise<AuthResult>;
+export declare function getApiAccessToken(): Promise<string | null>;
 export declare function unauthorizedContent(reason: AuthResult & {
     ok: false;
 }): {

package/dist/auth.js

@@ -1,19 +1,31 @@
-import { getApiToken, getApiUrl } from "./config.js";
+import { createServer } from "node:http";
+import { spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { chmod, mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { getApiToken, getApiUrl, getOAuthCachePath, isOAuthEnabled } from "./config.js";
+let cachedCredentials = null;
+let authenticationInFlight = null;
 /**
- * Require the API to validate the bearer token before running any tool.
+ * Validate the API bearer token before running any tool. OAuth starts in the
+ * user's browser when no legacy SKALEAGENTS_API_TOKEN is configured.
  */
 export async function requireApiAuth() {
-    const token = getApiToken();
+    const token = await getAccessToken();
     if (!token) {
-        return { ok: false, reason: "missing_token" };
+        return {
+            ok: false,
+            reason: isOAuthEnabled() ? "oauth_failed" : "oauth_required",
+        };
     }
     try {
-        const res = await fetch(`${getApiUrl()}/api/user`, {
-            headers: {
-                Accept: "application/json",
-                Authorization: `Bearer ${token}`,
-            },
-        });
+        let res = await fetchApiUser(token);
+        if ((res.status === 401 || res.status === 403) && !getApiToken()) {
+            const replacementToken = await reauthorizeAfterRejection();
+            if (replacementToken) {
+                res = await fetchApiUser(replacementToken);
+            }
+        }
         if (res.status === 401 || res.status === 403) {
             return { ok: false, reason: "unauthorized" };
         }
@@ -27,14 +39,247 @@ export async function requireApiAuth() {
         return { ok: false, reason: "api_unavailable" };
     }
 }
+export async function getApiAccessToken() {
+    return getAccessToken();
+}
 export function unauthorizedContent(reason) {
-    const text = reason.reason === "missing_token"
-        ? "unauthorized: set SKALEAGENTS_API_TOKEN"
-        : reason.reason === "unauthorized"
-            ? "unauthorized: invalid SKALEAGENTS_API_TOKEN"
-            : "api unavailable: could not validate SKALEAGENTS_API_TOKEN";
+    const text = reason.reason === "oauth_required"
+        ? "MCP OAuth is disabled. Set SKALEAGENTS_API_TOKEN or enable OAuth."
+        : reason.reason === "oauth_failed"
+            ? "MCP sign-in could not be completed. Check the browser window and try again."
+            : reason.reason === "unauthorized"
+                ? "unauthorized: the SkaleAgents connection was rejected"
+                : "api unavailable: could not validate the SkaleAgents connection";
     return {
         isError: true,
         content: [{ type: "text", text }],
     };
 }
+async function getAccessToken() {
+    const legacyToken = getApiToken();
+    if (legacyToken)
+        return legacyToken;
+    if (!isOAuthEnabled())
+        return null;
+    if (!authenticationInFlight) {
+        authenticationInFlight = getOAuthAccessToken().finally(() => {
+            authenticationInFlight = null;
+        });
+    }
+    try {
+        return await authenticationInFlight;
+    }
+    catch {
+        return null;
+    }
+}
+async function fetchApiUser(token) {
+    return fetch(`${getApiUrl()}/api/user`, {
+        headers: {
+            Accept: "application/json",
+            Authorization: `Bearer ${token}`,
+        },
+    });
+}
+async function reauthorizeAfterRejection() {
+    cachedCredentials = null;
+    await removeCredentials();
+    return getAccessToken();
+}
+async function getOAuthAccessToken() {
+    const apiUrl = getApiUrl();
+    const metadata = await getMetadata(apiUrl);
+    const stored = await readCredentials(apiUrl);
+    if (stored && stored.expiresAt > Date.now() + 30_000) {
+        cachedCredentials = stored;
+        return stored.accessToken;
+    }
+    if (stored?.refreshToken) {
+        try {
+            const refreshed = await exchangeRefreshToken(metadata.token_endpoint, stored.refreshToken);
+            await saveCredentials(apiUrl, refreshed);
+            return refreshed.accessToken;
+        }
+        catch {
+            cachedCredentials = null;
+            await removeCredentials();
+        }
+    }
+    const authorizationCode = await authorizeInBrowser(metadata.authorization_endpoint);
+    const exchanged = await exchangeAuthorizationCode(metadata.token_endpoint, authorizationCode.code, authorizationCode.redirectUri, authorizationCode.verifier);
+    await saveCredentials(apiUrl, exchanged);
+    return exchanged.accessToken;
+}
+async function getMetadata(apiUrl) {
+    const response = await fetch(`${apiUrl}/.well-known/oauth-authorization-server`, {
+        headers: { Accept: "application/json" },
+    });
+    if (!response.ok) {
+        throw new Error(`OAuth metadata request failed with status ${response.status}`);
+    }
+    const metadata = (await response.json());
+    if (typeof metadata.authorization_endpoint !== "string" ||
+        typeof metadata.token_endpoint !== "string") {
+        throw new Error("OAuth metadata is incomplete");
+    }
+    return metadata;
+}
+async function authorizeInBrowser(authorizationEndpoint) {
+    const verifier = randomBytes(48).toString("base64url");
+    const challenge = createCodeChallenge(verifier);
+    const state = randomBytes(32).toString("base64url");
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let redirectUri = "";
+        const server = createServer((request, response) => {
+            const requestUrl = new URL(request.url ?? "/", `http://${request.headers.host ?? "127.0.0.1"}`);
+            if (requestUrl.pathname !== "/oauth/callback") {
+                response.writeHead(404);
+                response.end("Not found");
+                return;
+            }
+            const receivedState = requestUrl.searchParams.get("state");
+            const error = requestUrl.searchParams.get("error");
+            const code = requestUrl.searchParams.get("code");
+            response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+            response.end("<!doctype html><title>SkaleAgents connected</title>" +
+                "<p>You can close this window and return to your AI client.</p>");
+            if (settled)
+                return;
+            settled = true;
+            server.close();
+            if (receivedState !== state) {
+                reject(new Error("OAuth state validation failed"));
+                return;
+            }
+            if (error || !code) {
+                reject(new Error("OAuth authorization was denied"));
+                return;
+            }
+            resolve({
+                code,
+                redirectUri,
+                verifier,
+            });
+        });
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const port = addressPort(server);
+            redirectUri = `http://127.0.0.1:${port}/oauth/callback`;
+            const url = new URL(authorizationEndpoint);
+            url.search = new URLSearchParams({
+                client_id: "skaleagents-mcp",
+                response_type: "code",
+                redirect_uri: redirectUri,
+                scope: "mcp",
+                state,
+                code_challenge: challenge,
+                code_challenge_method: "S256",
+            }).toString();
+            console.error("Opening SkaleAgents sign-in in your browser...");
+            console.error(url.toString());
+            openBrowser(url.toString());
+        });
+    });
+}
+async function exchangeAuthorizationCode(tokenEndpoint, code, redirectUri, verifier) {
+    const response = await fetchToken(tokenEndpoint, {
+        grant_type: "authorization_code",
+        client_id: "skaleagents-mcp",
+        code,
+        redirect_uri: redirectUri,
+        code_verifier: verifier,
+    });
+    return parseTokenResponse(response);
+}
+async function exchangeRefreshToken(tokenEndpoint, refreshToken) {
+    const response = await fetchToken(tokenEndpoint, {
+        grant_type: "refresh_token",
+        client_id: "skaleagents-mcp",
+        refresh_token: refreshToken,
+    });
+    return parseTokenResponse(response);
+}
+async function fetchToken(tokenEndpoint, values) {
+    const response = await fetch(tokenEndpoint, {
+        method: "POST",
+        headers: {
+            Accept: "application/json",
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: new URLSearchParams(values),
+    });
+    const payload = (await response.json().catch(() => ({})));
+    if (!response.ok) {
+        throw new Error(`OAuth token request failed with status ${response.status}`);
+    }
+    return payload;
+}
+function parseTokenResponse(response) {
+    if (typeof response.access_token !== "string" ||
+        typeof response.refresh_token !== "string" ||
+        typeof response.expires_in !== "number") {
+        throw new Error("OAuth token response is incomplete");
+    }
+    return {
+        apiUrl: getApiUrl(),
+        accessToken: response.access_token,
+        refreshToken: response.refresh_token,
+        expiresAt: Date.now() + response.expires_in * 1000,
+    };
+}
+async function readCredentials(apiUrl) {
+    if (cachedCredentials?.apiUrl === apiUrl)
+        return cachedCredentials;
+    try {
+        const parsed = JSON.parse(await readFile(getOAuthCachePath(), "utf8"));
+        if (parsed.apiUrl !== apiUrl ||
+            typeof parsed.accessToken !== "string" ||
+            typeof parsed.refreshToken !== "string" ||
+            typeof parsed.expiresAt !== "number") {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+async function saveCredentials(apiUrl, credentials) {
+    cachedCredentials = { ...credentials, apiUrl };
+    const path = getOAuthCachePath();
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await writeFile(path, JSON.stringify(cachedCredentials), { encoding: "utf8", mode: 0o600 });
+    await chmod(path, 0o600);
+}
+async function removeCredentials() {
+    try {
+        await unlink(getOAuthCachePath());
+    }
+    catch {
+        /* Cache may not exist. */
+    }
+}
+function createCodeChallenge(verifier) {
+    return createHash("sha256").update(verifier).digest("base64url");
+}
+function addressPort(server) {
+    const address = server.address();
+    if (address === null || typeof address === "string") {
+        throw new Error("OAuth callback server did not receive a port");
+    }
+    return address.port;
+}
+function openBrowser(url) {
+    const command = process.platform === "darwin"
+        ? "open"
+        : process.platform === "win32"
+            ? "cmd"
+            : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    const child = spawn(command, args, { detached: true, stdio: "ignore" });
+    child.once("error", () => {
+        console.error("Could not open a browser automatically. Open the URL printed above.");
+    });
+    child.unref();
+}

package/dist/config.d.ts

@@ -1,2 +1,4 @@
 export declare function getApiUrl(): string;
 export declare function getApiToken(): string;
+export declare function getOAuthCachePath(): string;
+export declare function isOAuthEnabled(): boolean;

package/dist/config.js

@@ -1,6 +1,15 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
 export function getApiUrl() {
     return (process.env.PLATFORM_API_URL?.replace(/\/$/, "") ?? "http://localhost:8082");
 }
 export function getApiToken() {
     return process.env.SKALEAGENTS_API_TOKEN?.trim() ?? "";
 }
+export function getOAuthCachePath() {
+    return (process.env.SKALEAGENTS_OAUTH_CACHE?.trim() ??
+        join(homedir(), ".config", "skaleagents", "oauth.json"));
+}
+export function isOAuthEnabled() {
+    return process.env.SKALEAGENTS_OAUTH_ENABLED !== "false";
+}

package/dist/index.js

@@ -2,11 +2,11 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { requireApiAuth, unauthorizedContent } from "./auth.js";
+import { getApiAccessToken, requireApiAuth, unauthorizedContent, } from "./auth.js";
 import { architectureFindings, countIacResources, fetchPublicBotHints, } from "./review.js";
 const server = new McpServer({
     name: "skaleagents-swarm",
-    version: "0.2.2",
+    version: "0.3.0",
 });
 server.registerTool("review_architecture", {
     title: "Review architecture",
@@ -32,7 +32,10 @@ server.registerTool("review_architecture", {
     const auth = await requireApiAuth();
     if (!auth.ok)
         return unauthorizedContent(auth);
-    const botHints = await fetchPublicBotHints();
+    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 = {

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(): Promise<string[]>;
+export declare function fetchPublicBotHints(token: string): Promise<string[]>;
 export declare function countIacResources(content: string): number;

package/dist/review.js

@@ -1,4 +1,4 @@
-import { getApiToken, getApiUrl } from "./config.js";
+import { getApiUrl } from "./config.js";
 function shouldInclude(focus, category) {
     return focus === "general" || focus === category;
 }
@@ -104,12 +104,12 @@ export function architectureFindings(content, focus) {
     }
     return findings;
 }
-export async function fetchPublicBotHints() {
+export async function fetchPublicBotHints(token) {
     try {
         const res = await fetch(`${getApiUrl()}/api/bots`, {
             headers: {
                 Accept: "application/json",
-                Authorization: `Bearer ${getApiToken()}`,
+                Authorization: `Bearer ${token}`,
             },
         });
         if (!res.ok)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skaleagents/swarm",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "private": false,
   "publishConfig": {
     "access": "public"