@skaleagents/swarm 0.6.17 → 0.6.19

package/README.md

@@ -5,12 +5,9 @@ SkaleAgents MCP server. The hosted connection is `https://skaleagents.com/mcp`.
 ## Quick start
 
 Copy `https://skaleagents.com/mcp` into your client and choose OAuth. Sign in
-with Google and click Allow. Leave client ID and secret fields blank when the
-client asks. Setup steps for Cursor, Claude Code, Claude Desktop, ChatGPT, and
-Codex are on the [MCP config page](https://skaleagents.com/mcp-config).
-
-The hosted URL is the way to connect. A local stdio process can still run this
-package; it opens the browser for OAuth when no token is set.
+with Google and click Allow. Leave client ID and secret blank when the client
+asks. Setup steps for Cursor, Claude Code, Claude Desktop, ChatGPT, and Codex
+are on the [MCP config page](https://skaleagents.com/mcp-config).
 
 Tools: `plan_architecture_review`, `review_application_architecture`,
 `review_architecture`, and `scan_iac`. The older `scan_iac_stub` name remains
@@ -111,15 +108,9 @@ locations point to resource declarations; property paths identify the setting.
 YAML aliases must be expanded before submission. Coverage limits are included
 in every result. An empty finding list is not proof that a system is secure.
 
-## Hosted connection
-
-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 click Allow.
-See [client setup](https://skaleagents.com/mcp-config) for Cursor, Claude Code,
-Claude Desktop, ChatGPT, and Codex instructions.
+## Hosted transport
 
-The web app hosts this endpoint using `handleMcpRequest` from
+The web app hosts `https://skaleagents.com/mcp` using `handleMcpRequest` from
 `@skaleagents/swarm/http`. Audit workers import `scanIac` from
 `@skaleagents/swarm/scan`. It validates each bearer credential with the API's
 `/api/oauth/mcp-token` endpoint before running a tool. Tokens are bound to the
@@ -129,94 +120,23 @@ 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
-to your AI client. The package stores the OAuth refresh credential locally and
-refreshes access automatically. Active connections can be revoked from the
-[MCP config page](https://skaleagents.com/mcp-config).
-
-Local `review_architecture` calls validate the account and fetch public bot
-hints concurrently. The public directory request carries no credential. Every
-review still requires successful account validation. An anonymous directory
-request may already be in flight when validation rejects a connection.
-
 ## Local development
 
+People working on this repo need Node.js 20 or newer. This is not the way to connect a client.
+
 ```bash
 git clone https://github.com/SkaleAgents/mcp-server.git
 cd mcp-server
 npm install
-cp .env.example .env
 npm run build
 npm test
-npm run smoke   # needs API on :8082
-```
-
-## Cursor
-
-Add to `.cursor/mcp.json` (project) or Cursor Settings → MCP:
-
-### Option A: local clone (recommended while API is local)
-
-```json
-{
-  "mcpServers": {
-    "skaleagents": {
-      "command": "node",
-      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
-      "env": {
-        "PLATFORM_API_URL": "http://localhost:8082"
-      }
-    }
-  }
-}
 ```
 
-Dev without build:
-
-```json
-{
-  "mcpServers": {
-    "skaleagents": {
-      "command": "npx",
-      "args": ["tsx", "/absolute/path/to/mcp-server/src/index.ts"],
-      "env": {
-        "PLATFORM_API_URL": "http://localhost:8082"
-      }
-    }
-  }
-}
-```
-
-### Option B: published package (hosted API)
-
-```json
-{
-  "mcpServers": {
-    "skaleagents": {
-      "command": "npx",
-       "args": ["-y", "@skaleagents/swarm@0.6.1"]
-    }
-  }
-}
-```
-
-Reconnect after upgrading to refresh the tool catalog. The consultation tools,
-snippet review, IaC scanner, and compatibility alias should all appear.
-
-## Claude Code
-
-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. |
+| `SKALEAGENTS_API_TOKEN` | No | Legacy override for CI only, not the way to connect. |
 | `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. |
@@ -224,7 +144,7 @@ Use the published package configuration above in `.mcp.json`. OAuth starts on th
 
 ## Steady-state tool latency probe
 
-With an existing, authorized `SKALEAGENTS_API_TOKEN` in the environment, run
+This probe uses the legacy `SKALEAGENTS_API_TOKEN` CI override. It is not how a client connects. With that variable already set, run
 `npm run benchmark:tool`. The script builds this checkout, starts its stdio MCP
 server, makes five warmup calls, then times 50 `review_architecture` calls on a
 fixed synthetic application snippet. Set `BENCHMARK_WARMUP` from 0 to 20 and

package/dist/application/tools.js

@@ -3,14 +3,16 @@ import { requireApiAuth, unauthorizedContent } from "../auth.js";
 import { ScanInputError } from "../iac/parse.js";
 import { contextSchema, fileSchema, planReview, consultationInstructions, } from "./intake.js";
 import { reviewApplication } from "./review.js";
-async function run(remote, compute) {
+import { applicationTargetSchema, withSavedReview } from "../saved-review.js";
+async function run(remote, compute, save) {
     if (!remote) {
         const auth = await requireApiAuth();
         if (!auth.ok)
             return unauthorizedContent(auth);
     }
     try {
-        const output = compute();
+        const computed = compute();
+        const output = save ? await withSavedReview(computed, save) : computed;
         return {
             content: [
                 { type: "text", text: JSON.stringify(output, null, 2) },
@@ -67,8 +69,13 @@ export function registerConsultation(server, remote) {
                 .max(80)
                 .describe("Related source/config/test files with repository-relative paths; include package.json and tsconfig.json. At most 500,000 combined content characters"),
             context: contextSchema,
+            target: applicationTargetSchema,
         },
-    }, ({ files, context }) => run(remote, () => reviewApplication(files, context)));
+    }, ({ files, context, target }) => run(remote, () => reviewApplication(files, context), {
+        tool: "review_application_architecture",
+        target: target ?? null,
+        submittedPaths: files.map((file) => file.path),
+    }));
     server.registerPrompt("architecture_consultation", {
         title: "Independent application architecture consultation",
         description: "Guide a multi-turn whole-application review with source evidence, follow-up questions, and design tradeoffs.",

package/dist/http.js

@@ -1,6 +1,7 @@
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import { createServer } from "./server.js";
 import { getApiUrl } from "./config.js";
+import { requestAuthorization } from "./saved-review.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([
@@ -105,30 +106,32 @@ export async function handleMcpRequest(request) {
             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,
+    return requestAuthorization.run(authorization, async () => {
+        const server = createServer(true);
+        const transport = new WebStandardStreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+            enableJsonResponse: true,
         });
-        // 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();
-    }
+        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/saved-review.d.ts

@@ -0,0 +1,36 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { z } from "zod";
+export declare const savedTargetSchema: z.ZodOptional<z.ZodObject<{
+    repository: z.ZodOptional<z.ZodString>;
+    path: z.ZodOptional<z.ZodString>;
+    revision: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+export declare const applicationTargetSchema: z.ZodOptional<z.ZodObject<{
+    repository: z.ZodOptional<z.ZodString>;
+    revision: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+export declare const requestAuthorization: AsyncLocalStorage<string>;
+export declare const ASSISTANT_INSTRUCTION = "Report the headline and the one recommended change. Include the share link. If the headline says the finding is gone, say that. If there are no findings, say that this does not prove the system is secure. Do not paste source, diffs, or account details. Do not invent a link when the share link is missing.";
+type Target = {
+    repository?: string;
+    path?: string;
+    revision?: string;
+};
+type SaveInput = {
+    tool: string;
+    target?: Target | null;
+    submittedPaths: string[];
+};
+export declare function buildProjection(input: SaveInput, output: Record<string, unknown>): {
+    tool: string;
+    engineVersion: string;
+    target: Target | null;
+    riskSentence: unknown;
+    findings: Record<string, unknown>[];
+    truncated: boolean;
+    checked: string[];
+    skipped: string[];
+    submittedPaths: string[];
+};
+export declare function withSavedReview(output: Record<string, unknown>, input: SaveInput): Promise<Record<string, unknown>>;
+export {};

package/dist/saved-review.js

@@ -0,0 +1,177 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { z } from "zod";
+import { getApiAccessToken } from "./auth.js";
+import { getApiUrl } from "./config.js";
+import { VERSION } from "./version.js";
+const repositoryLabel = z
+    .string()
+    .regex(/^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)?$/)
+    .max(200);
+const relativePath = z
+    .string()
+    .min(1)
+    .max(500)
+    .refine((path) => !path.startsWith("/") && !path.includes("..") && !path.includes("\\"));
+const revision = z.string().regex(/^[A-Za-z0-9._-]{1,64}$/);
+export const savedTargetSchema = z
+    .object({
+    repository: repositoryLabel.optional(),
+    path: relativePath.optional(),
+    revision: revision.optional(),
+})
+    .strict()
+    .optional()
+    .describe("Repository label for the next comparison. The server does not fetch it.");
+export const applicationTargetSchema = z
+    .object({
+    repository: repositoryLabel.optional(),
+    revision: revision.optional(),
+})
+    .strict()
+    .optional()
+    .describe("Repository label for the next comparison. Send paths on each file.");
+export const requestAuthorization = new AsyncLocalStorage();
+export const ASSISTANT_INSTRUCTION = "Report the headline and the one recommended change. Include the share link. If the headline says the finding is gone, say that. If there are no findings, say that this does not prove the system is secure. Do not paste source, diffs, or account details. Do not invent a link when the share link is missing.";
+const refused = {
+    saved: false,
+    id: null,
+    ownerUrl: null,
+    shareUrl: null,
+    shareExpiresAt: null,
+    comparison: null,
+    headline: null,
+    assistantInstruction: ASSISTANT_INSTRUCTION,
+};
+function clip(value, max = 200) {
+    if (typeof value !== "string")
+        return null;
+    const text = value.replaceAll("\n", " ").trim();
+    if (!text || text.length > max)
+        return null;
+    return text;
+}
+function findingPath(finding, fallback) {
+    const location = finding.location;
+    if (location && typeof location === "object" && "path" in location && fallback) {
+        return fallback;
+    }
+    const evidence = finding.evidence;
+    if (Array.isArray(evidence) && evidence[0] && typeof evidence[0] === "object" && "file" in evidence[0]) {
+        const file = clip(evidence[0].file, 500);
+        if (file)
+            return file;
+    }
+    return fallback;
+}
+export function buildProjection(input, output) {
+    const findings = Array.isArray(output.findings) ? output.findings : [];
+    const fallbackPath = input.target?.path ?? "";
+    const projected = findings.slice(0, 100).flatMap((item) => {
+        if (!item || typeof item !== "object")
+            return [];
+        const finding = item;
+        const title = clip(finding.title);
+        const severity = clip(finding.severity, 16);
+        if (!title || !severity)
+            return [];
+        const row = { title, severity };
+        const ruleId = clip(finding.ruleId, 64);
+        if (ruleId)
+            row.ruleId = ruleId;
+        for (const field of ["detail", "resource", "remediation"]) {
+            const text = clip(finding[field]);
+            if (text)
+                row[field] = text;
+        }
+        const path = findingPath(finding, fallbackPath);
+        if (path)
+            row.path = path;
+        const line = finding.location && typeof finding.location === "object" && "line" in finding.location
+            ? finding.location.line
+            : Array.isArray(finding.evidence) && finding.evidence[0] && typeof finding.evidence[0] === "object"
+                ? finding.evidence[0].line
+                : null;
+        if (typeof line === "number" && Number.isInteger(line) && line > 0)
+            row.line = line;
+        return [row];
+    });
+    const checked = Array.isArray(output.rulesEvaluated)
+        ? output.rulesEvaluated.flatMap((rule) => {
+            const text = clip(rule, 64);
+            return text ? [text] : [];
+        })
+        : [];
+    if (input.tool === "review_application_architecture") {
+        checked.unshift(`Reviewed ${input.submittedPaths.length} files.`);
+        checked.push(...input.submittedPaths);
+    }
+    const skipped = [];
+    if (Array.isArray(output.warnings) && output.warnings.length > 0) {
+        const count = output.warnings.length;
+        skipped.push(`The scanner reported ${count} ${count === 1 ? "warning" : "warnings"}.`);
+    }
+    for (const field of ["evidenceGaps", "limitations"]) {
+        if (!Array.isArray(output[field]))
+            continue;
+        for (const entry of output[field]) {
+            const text = clip(entry);
+            if (text)
+                skipped.push(text);
+            if (skipped.length >= 20)
+                break;
+        }
+    }
+    const summary = clip(output.summary);
+    const riskSentence = summary
+        ?? (projected.length === 0
+            ? "No findings. That does not prove the system is secure."
+            : projected[0].title);
+    return {
+        tool: input.tool,
+        engineVersion: VERSION,
+        target: input.target ?? null,
+        riskSentence,
+        findings: projected,
+        truncated: output.truncated === true || findings.length > 100,
+        checked: checked.length > 0 ? checked.slice(0, 20) : ["Individual checks were not recorded."],
+        skipped: skipped.length > 0 ? skipped.slice(0, 20) : ["Nothing was recorded as skipped."],
+        submittedPaths: input.submittedPaths.length > 0 ? input.submittedPaths : [fallbackPath],
+    };
+}
+async function authorizationHeader() {
+    const fromRequest = requestAuthorization.getStore();
+    if (fromRequest)
+        return fromRequest;
+    const token = await getApiAccessToken();
+    return token ? `Bearer ${token}` : null;
+}
+export async function withSavedReview(output, input) {
+    const projection = buildProjection(input, output);
+    let savedReview = refused;
+    const authorization = await authorizationHeader();
+    if (authorization) {
+        try {
+            const response = await fetch(`${getApiUrl()}/api/mcp/reviews`, {
+                method: "POST",
+                headers: {
+                    Authorization: authorization,
+                    Accept: "application/json",
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify(projection),
+                signal: AbortSignal.timeout(10_000),
+                redirect: "error",
+                cache: "no-store",
+            });
+            if (response.ok) {
+                const body = await response.json();
+                if (body.savedReview)
+                    savedReview = body.savedReview;
+            }
+        }
+        catch {
+            savedReview = refused;
+        }
+    }
+    return { ...output, savedReview };
+}

package/dist/server.js

@@ -6,6 +6,7 @@ import { looksLikeIac, ScanInputError } from "./iac/parse.js";
 import { filterFindings, scanIac, summarize } from "./iac/scan.js";
 import { registerConsultation } from "./application/tools.js";
 import { presentReview } from "./review-edits.js";
+import { savedTargetSchema, withSavedReview } from "./saved-review.js";
 import { VERSION } from "./version.js";
 const contentSchema = z
     .string()
@@ -93,8 +94,9 @@ export function createServer(remote = false) {
                 .optional()
                 .default("auto")
                 .describe("Content format: terraform, cloudformation, kubernetes, pulumi, compose, dockerfile, github, helm, ansible, bicep, arm, gitlab, azure-pipelines, cloudbuild, tfvars, serverless, iam, package, application, auto."),
+            target: savedTargetSchema,
         },
-    }, async ({ content, focus, format, minSeverity, maxFindings }) => {
+    }, async ({ content, focus, format, minSeverity, maxFindings, target }) => {
         const botHints = fetchPublicBotHints();
         if (!remote) {
             const auth = await requireApiAuth();
@@ -103,15 +105,20 @@ export function createServer(remote = false) {
         }
         try {
             const options = { focus, minSeverity, maxFindings };
+            const save = {
+                tool: "review_architecture",
+                target: target ?? null,
+                submittedPaths: [target?.path ?? ""],
+            };
             if (format !== "application" &&
                 (format !== "auto" || looksLikeIac(content))) {
-                return result(presentReview(content, {
+                return result(await withSavedReview(presentReview(content, {
                     ...scanIac(content, { ...options, format }),
                     botHints: await botHints,
-                }));
+                }), save));
             }
             const findings = filterFindings(architectureFindings(content, focus).slice(1), options);
-            return result(presentReview(content, {
+            return result(await withSavedReview(presentReview(content, {
                 status: "completed",
                 engineVersion: VERSION,
                 format: "application",
@@ -125,7 +132,7 @@ export function createServer(remote = false) {
                     "Infrastructure bottleneck checks cover a disabled timeout, a one-connection pool, and an unbounded retry limit.",
                 ],
                 botHints: await botHints,
-            }));
+            }), save));
         }
         catch (error) {
             return inputError(error);
@@ -172,15 +179,20 @@ export function createServer(remote = false) {
                 ])
                     .default("auto"),
                 ...filters,
+                target: savedTargetSchema,
             },
-        }, async ({ content, format, focus, minSeverity, maxFindings }) => {
+        }, async ({ content, format, focus, minSeverity, maxFindings, target }) => {
             if (!remote) {
                 const auth = await requireApiAuth();
                 if (!auth.ok)
                     return unauthorizedContent(auth);
             }
             try {
-                return result(presentReview(content, scanIac(content, { format, focus, minSeverity, maxFindings })));
+                return result(await withSavedReview(presentReview(content, scanIac(content, { format, focus, minSeverity, maxFindings })), {
+                    tool: name,
+                    target: target ?? null,
+                    submittedPaths: [target?.path ?? ""],
+                }));
             }
             catch (error) {
                 return inputError(error);

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.6.17";
+export declare const VERSION = "0.6.19";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.6.17";
+export const VERSION = "0.6.19";

package/package.json

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