@skaleagents/swarm 0.1.0 → 0.2.1

package/README.md

@@ -1,29 +1,60 @@
-# @skaleagents/swarm (legacy template)
+# @skaleagents/swarm
 
-Historical stdio MCP starter for SkaleAgents Phase 1 (`review_architecture`, `scan_iac_stub`).
-The extracted [`mcp-server`](https://github.com/SkaleAgents/mcp-server) repo is canonical.
+Public stdio MCP server for SkaleAgents Phase 1. Talks to the Laravel **api**
+(JSON only, no web UI) with a Sanctum bearer token.
 
-This template talks to the legacy Fastify API with `SKALEAGENTS_API_TOKEN` (personal access token from mock Google login).
+Tools: `review_architecture`, `scan_iac_stub`.
 
-The default points at the Fastify template on `:4000`. For the extracted Laravel API, use `PLATFORM_API_URL=http://localhost:8082` and `PLATFORM_API_PREFIX=/api`.
+`review_architecture` accepts application source or infrastructure text. Your AI
+client reads the files in its workspace and sends the relevant content through
+the MCP tool for a structured review.
 
-## Local
+## 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
+   ```
+
+## Local development
 
 ```bash
+git clone https://github.com/SkaleAgents/mcp-server.git
+cd mcp-server
 npm install
 cp .env.example .env
-# Get a token:
-# curl -s -X POST http://localhost:4000/auth/google/callback \
-#   -H 'Content-Type: application/json' \
-#   -d '{"code":"mcp","displayName":"MCP","email":"mcp@example.com"}'
+# Set SKALEAGENTS_API_TOKEN=<token from web app or curl above>
 npm run build
 npm test
-npm run smoke   # needs platform-api on PLATFORM_API_URL
-# Extracted Laravel API:
-# PLATFORM_API_URL=http://localhost:8082 PLATFORM_API_PREFIX=/api npm run smoke
+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": {
+        "SKALEAGENTS_API_TOKEN": "<paste token from web app → API tokens>",
+        "PLATFORM_API_URL": "http://localhost:8082"
+      }
+    }
+  }
+}
 ```
 
-## Cursor / Claude Code
+Dev without build:
 
 ```json
 {
@@ -32,15 +63,47 @@ npm run smoke   # needs platform-api on PLATFORM_API_URL
       "command": "npx",
       "args": ["tsx", "/absolute/path/to/mcp-server/src/index.ts"],
       "env": {
-        "SKALEAGENTS_API_TOKEN": "<token from Google callback>",
-        "PLATFORM_API_URL": "http://localhost:4000",
-        "PLATFORM_API_PREFIX": ""
+        "SKALEAGENTS_API_TOKEN": "<token>",
+        "PLATFORM_API_URL": "http://localhost:8082"
       }
     }
   }
 }
 ```
 
-Or after build: `"command": "node", "args": ["/absolute/path/to/mcp-server/dist/index.js"]`.
+### Option B: after npm publish (hosted API)
+
+```json
+{
+  "mcpServers": {
+    "skaleagents": {
+      "command": "npx",
+      "args": ["-y", "@skaleagents/swarm"],
+      "env": {
+        "SKALEAGENTS_API_TOKEN": "<token>",
+        "PLATFORM_API_URL": "https://api.skaleagents.com"
+      }
+    }
+  }
+}
+```
+
+Restart Cursor after saving. In Agent/Chat, tools should appear as `review_architecture` and `scan_iac_stub`.
+
+## Claude Code
+
+Same env vars; point `command`/`args` at `node …/dist/index.js` or `npx @skaleagents/swarm` once published.
+
+## Environment
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `SKALEAGENTS_API_TOKEN` | Yes | Sanctum bearer token (from the web **MCP** page) |
+| `PLATFORM_API_URL` | No | Default `http://localhost:8082` |
+
+## Auth behavior
+
+- Missing/invalid token → tools return an **unauthorized** error (fail closed).
+- Token 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.js

@@ -1,4 +1,4 @@
-import { getApiEndpoint, getApiToken } from "./config.js";
+import { getApiToken, getApiUrl } from "./config.js";
 /**
  * Require the API to validate the bearer token before running any tool.
  */
@@ -8,7 +8,7 @@ export async function requireApiAuth() {
         return { ok: false, reason: "missing_token" };
     }
     try {
-        const res = await fetch(getApiEndpoint("/user"), {
+        const res = await fetch(`${getApiUrl()}/api/user`, {
             headers: {
                 Accept: "application/json",
                 Authorization: `Bearer ${token}`,
@@ -18,7 +18,7 @@ export async function requireApiAuth() {
             return { ok: false, reason: "unauthorized" };
         }
         if (!res.ok) {
-            return { ok: false, reason: "unauthorized" };
+            return { ok: false, reason: "api_unavailable" };
         }
         const user = (await res.json());
         return { ok: true, userId: user.id };

package/dist/config.d.ts

@@ -1,3 +1,2 @@
 export declare function getApiUrl(): string;
-export declare function getApiEndpoint(path: string): string;
 export declare function getApiToken(): string;

package/dist/config.js

@@ -1,10 +1,5 @@
 export function getApiUrl() {
-    return (process.env.PLATFORM_API_URL?.replace(/\/$/, "") ?? "http://localhost:4000");
-}
-export function getApiEndpoint(path) {
-    const rawPrefix = (process.env.PLATFORM_API_PREFIX ?? "").replace(/\/$/, "");
-    const prefix = rawPrefix && !rawPrefix.startsWith("/") ? `/${rawPrefix}` : rawPrefix;
-    return `${getApiUrl()}${prefix}${path.startsWith("/") ? path : `/${path}`}`;
+    return (process.env.PLATFORM_API_URL?.replace(/\/$/, "") ?? "http://localhost:8082");
 }
 export function getApiToken() {
     return process.env.SKALEAGENTS_API_TOKEN?.trim() ?? "";

package/dist/index.js

@@ -3,35 +3,41 @@ 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 { cannedFindings, countIacResources, fetchPublicBotHints, } from "./review.js";
+import { architectureFindings, countIacResources, fetchPublicBotHints, } from "./review.js";
 const server = new McpServer({
     name: "skaleagents-swarm",
-    version: "0.1.0",
+    version: "0.2.0",
 });
 server.registerTool("review_architecture", {
     title: "Review architecture",
-    description: "Request a high-level architecture / security review of a code or IaC snippet.",
+    description: "Review application source or infrastructure text for security, reliability, and cost risks.",
     inputSchema: {
-        content: z.string().describe("Source or IaC text to review"),
-        focus: z
+        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 }) => {
+}, async ({ content, focus, format }) => {
     const auth = await requireApiAuth();
     if (!auth.ok)
         return unauthorizedContent(auth);
     const botHints = await fetchPublicBotHints();
-    const focusValue = focus === "security" ||
-        focus === "reliability" ||
-        focus === "cost" ||
-        focus === "general"
-        ? focus
-        : "general";
+    const focusValue = focus ?? "general";
+    const formatValue = format ?? "auto";
     const output = {
-        summary: "Phase 1 stub architecture review from @skaleagents/swarm",
-        findings: cannedFindings(content, focusValue),
+        summary: `Structured architecture review from @skaleagents/swarm (focus=${focusValue}, format=${formatValue})`,
+        findings: architectureFindings(content, focusValue),
         botHints,
     };
     return {
@@ -44,6 +50,8 @@ server.registerTool("scan_iac_stub", {
     inputSchema: {
         content: z
             .string()
+            .min(1)
+            .max(500_000)
             .describe("Terraform / CloudFormation / Kubernetes YAML"),
         format: z
             .string()

package/dist/review.d.ts

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

package/dist/review.js

@@ -1,31 +1,112 @@
-import { getApiEndpoint, getApiToken } from "./config.js";
-export function cannedFindings(content, focus) {
+import { getApiToken, getApiUrl } from "./config.js";
+function shouldInclude(focus, category) {
+    return focus === "general" || focus === category;
+}
+export function architectureFindings(content, focus) {
+    const focusValue = focus === "security" ||
+        focus === "reliability" ||
+        focus === "cost" ||
+        focus === "general"
+        ? focus
+        : "general";
     const findings = [
         {
             severity: "info",
-            title: "Stub review",
-            detail: `Phase 1 canned review (focus=${focus}). Length=${content.length} chars.`,
+            title: "Structured review completed",
+            detail: `Checked ${content.length} characters with the ${focusValue} ruleset. Findings are pattern-based and should be validated against the running system.`,
         },
     ];
-    if (/0\.0\.0\.0(?:\/0)?/.test(content)) {
+    if (shouldInclude(focusValue, "security") && /0\.0\.0\.0(?:\/0)?/.test(content)) {
         findings.push({
             severity: "high",
             title: "Broad network exposure",
-            detail: "Detected a possible wide-open CIDR or bind address.",
+            detail: "Detected a possible wide-open CIDR or bind address. Restrict ingress to approved sources and keep public listeners behind the intended edge control.",
         });
     }
-    if (/AKIA[0-9A-Z]{16}/.test(content)) {
+    if (shouldInclude(focusValue, "security") && /AKIA[0-9A-Z]{16}/.test(content)) {
         findings.push({
             severity: "critical",
             title: "Possible AWS access key",
-            detail: "Remove secrets from source; rotate credentials.",
+            detail: "A value matches an AWS access-key pattern. Remove it from source, rotate the credential, and check repository history.",
+        });
+    }
+    if (shouldInclude(focusValue, "security") &&
+        /-----BEGIN (?:RSA |EC |OPENSSH |DSA |)PRIVATE KEY-----/.test(content)) {
+        findings.push({
+            severity: "critical",
+            title: "Private key material in source",
+            detail: "Detected a private-key block. Revoke or rotate the key, remove it from source and history, and load replacement credentials through a secret manager.",
+        });
+    }
+    if (shouldInclude(focusValue, "security") &&
+        /(?:password|passwd|secret|api[_-]?key|auth[_-]?token)\s*[:=]\s*["'][^"']{8,}["']/i.test(content) &&
+        !/(?:process\.env|secrets?\.|vault|parameter|<[^>]+>|\$\{)/i.test(content)) {
+        findings.push({
+            severity: "high",
+            title: "Hardcoded credential-like value",
+            detail: "A credential-like assignment contains a literal value. Move it to a secret manager or runtime environment and rotate the exposed value.",
+        });
+    }
+    if (shouldInclude(focusValue, "security") &&
+        /(?:Action|actions?)\s*[:=][^\n]*["']?\*["']?/i.test(content)) {
+        findings.push({
+            severity: "high",
+            title: "Wildcard permission detected",
+            detail: "An IAM or policy action uses a wildcard. Replace it with the smallest permission set required by the workload.",
+        });
+    }
+    if (shouldInclude(focusValue, "security") &&
+        /(?:privileged\s*:\s*true|hostNetwork\s*:\s*true|allowPrivilegeEscalation\s*:\s*true)/i.test(content)) {
+        findings.push({
+            severity: "critical",
+            title: "Elevated container privileges",
+            detail: "The content enables a privileged container setting. Remove it unless the workload requires it, then isolate and monitor that workload.",
+        });
+    }
+    if (shouldInclude(focusValue, "security") &&
+        /(?:^|[\s"'])https?:\/\/(?!localhost\b|127\.0\.0\.1\b)/i.test(content)) {
+        findings.push({
+            severity: "medium",
+            title: "Unencrypted HTTP endpoint",
+            detail: "Detected an HTTP URL outside localhost. Use HTTPS for service and dependency traffic, and verify certificate validation is enabled.",
+        });
+    }
+    if ((shouldInclude(focusValue, "security") || shouldInclude(focusValue, "reliability")) &&
+        /(?:^|[\s:=])(?:[\w./-]+:)?latest(?:[\s"']|$)/im.test(content)) {
+        findings.push({
+            severity: "medium",
+            title: "Unpinned container image",
+            detail: "An image uses the mutable latest tag. Pin a version or digest so deployments are repeatable and rollback targets remain known.",
+        });
+    }
+    if (shouldInclude(focusValue, "security") &&
+        /(?:public-read|publicRead|allUsers)/i.test(content)) {
+        findings.push({
+            severity: "high",
+            title: "Public data access pattern",
+            detail: "Detected a public access setting. Confirm the resource is intended to be public and restrict access when it is not.",
+        });
+    }
+    if (shouldInclude(focusValue, "reliability") &&
+        /(?:debug|app_debug)\s*[:=]\s*["']?(?:true|1|yes)["']?/i.test(content)) {
+        findings.push({
+            severity: "medium",
+            title: "Debug mode enabled",
+            detail: "The content enables debug mode. Disable it in production to avoid noisy behavior and accidental disclosure of internal details.",
+        });
+    }
+    if (shouldInclude(focusValue, "cost") && /(?:instance_type|machine_type|vm_size)\s*[:=]/i.test(content)) {
+        findings.push({
+            severity: "info",
+            title: "Compute sizing needs review",
+            detail: "Detected an explicit compute size. Compare the selected size with observed utilization and set a review point for scale-up and scale-down decisions.",
         });
     }
     return findings;
 }
 export async function fetchPublicBotHints() {
     try {
-        const res = await fetch(getApiEndpoint("/bots"), {
+        const res = await fetch(`${getApiUrl()}/api/bots`, {
             headers: {
                 Accept: "application/json",
                 Authorization: `Bearer ${getApiToken()}`,

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@skaleagents/swarm",
-  "version": "0.1.0",
+  "version": "0.2.1",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
   "type": "module",
   "description": "SkaleAgents MCP server — stdio tools against the Laravel api",
   "bin": {
-    "skaleagents-swarm": "./dist/index.js"
+    "skaleagents-swarm": "dist/index.js"
   },
   "files": [
     "dist"