
swarm
io.github.SkaleAgents/swarm
IaC, CI and dependency security review for coding agents: local scan CLI plus hosted OAuth MCP.
Documentation
@skaleagents/swarm
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 blank when the client
asks. Setup steps for Cursor, Claude Code, Claude Desktop, ChatGPT, and Codex
are on the MCP config page.
Tools: plan_architecture_review, review_application_architecture,
review_architecture, scan_iac, and scan_dependencies. The older
scan_iac_stub name remains an alias for the IaC scanner.
scan_dependencies takes the text of one lockfile (package-lock.json, pnpm-lock.yaml, yarn.lock, composer.lock, requirements.txt or go.sum, up to 2 MB and 5000 packages) and returns known CVEs from OSV.dev as CVE001. It sends ecosystem, package name and version to api.osv.dev, never the lockfile. A failed lookup is an error, not a clean result. For larger lockfiles use scan --cves locally.
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.
Scan locally, in agent hooks, and in pull requests
npx -y @skaleagents/swarm scan [paths...] scans IaC, CI, Dockerfile and package files on your machine. It needs no account and sends nothing over the network unless you pass --cves. Use --changed for files changed against HEAD, --fail-on high to exit 1, and --json for machine output. With --fail-on, a file that cannot be read (invalid syntax, over the size or nesting limit) or a path that does not exist exits 2 instead of passing, the same way a failed CVE lookup does.
Adopt it on an existing repo: npx @skaleagents/swarm scan --write-baseline .skaleagents-baseline.json, commit the file, and later scans show only new findings. The Action reads the baseline from the PR's base commit, so a PR cannot hide findings by editing it. Findings match on rule, file and resource, not line number.
Your own rules. Commit a .skaleagents-rules.json at the repo root and every scan, agent hook and Action run checks it. The agent gets your conventions before it stops, not after review. It applies automatically and needs no account:
{ "rules": [
{ "kind": "require_tag", "resourceType": "aws_s3_bucket", "attribute": "owner", "severity": "medium" },
{ "kind": "require_attribute", "resourceType": "aws_db_instance", "attribute": "deletion_protection", "severity": "high" },
{ "kind": "forbid_value", "resourceType": "aws_s3_bucket", "attribute": "acl", "value": "public-read", "severity": "high" }
] }
Rules check Terraform .tf files. attribute is a dotted path such as versioning.enabled; a value computed from a variable or expression is skipped with a warning, not flagged. At most 25 rules. A malformed file exits 2 instead of silently skipping the check. Each rule has its own id, like HOUSE483920, shown in the finding; suppress or baseline one rule with # skaleagents-ignore HOUSE483920 reason without hiding the others. A forbid_value value may use letters, digits and . : / + = @ * - _ only. Because computed values are skipped, resolve variables and locals to literals where a rule matters.
scan also looks for committed secrets in any file it reads (AWS, GitHub, Slack, Stripe, Google, npm and Anthropic keys, private keys) as SECRET001, critical. The value is never printed. Git-ignored files such as a local .env are skipped. Rotate the key; only suppress a documented example.
scan --cves also checks the exact package versions in lockfiles against OSV.dev (GitHub Advisories, PyPI, Go, Packagist) and reports known CVEs as CVE001. It reads package-lock.json, pnpm-lock.yaml, yarn.lock, composer.lock, requirements*.txt (exact == pins only) and go.sum. It sends package names and versions to api.osv.dev, never source, and skips npm packages that do not come from the public registry, requirements files that set a custom index, and Go modules matching GOPRIVATE, GONOPROXY or GONOSUMDB (read from the environment, not from go env files). Set PIP_INDEX_URL or PIP_EXTRA_INDEX_URL to skip all requirements files. These filters are best effort. Private names in pnpm and yarn custom registries, and in Composer private repositories, are not detected and would be sent; do not use --cves on those repos. If the lookup fails, the scan exits 2 rather than reporting a clean result. Severity comes from the advisory rating, and unrated advisories show as medium. Accept a known CVE with the baseline file. In the Action, set cves: true; it then checks every tracked lockfile, not only changed ones. The Action only runs on pull requests, so also run a schedule to catch CVEs published after merge:
on: { schedule: [{ cron: "0 6 * * *" }] }
jobs:
cves:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npx -y --registry=https://registry.npmjs.org @skaleagents/swarm@0.12.1 scan --cves --fail-on high
Suppress an intended setting with a comment on the flagged line or the line above: # skaleagents-ignore DATA001 public asset bucket.
Claude Code plugin. It adds a stop hook that scans changed files, including your .skaleagents-rules.json, and asks the agent to fix high and critical findings, plus a skill and the hosted MCP server:
/plugin marketplace add SkaleAgents/mcp-server
/plugin install skaleagents@skaleagents
Cursor. Add .cursor/hooks.json:
{ "version": 1, "hooks": { "stop": [{ "command": "npx -y --registry=https://registry.npmjs.org @skaleagents/swarm@0.12.1 scan --hook" }] } }
GitHub Action. It posts one PR comment and fails on critical by default:
on: pull_request
permissions: { contents: read, pull-requests: write }
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with: { fetch-depth: 0 }
- uses: SkaleAgents/mcp-server@v0.12.1
with: { fail-on: high }
Whole-application consultation
Ask your connected assistant:
Use SkaleAgents as an independent consultant to review this application's architecture. Read the relevant files, ask me about the important design decisions, and explain what is sound, what needs changes, and what needs more evidence.
The architecture_consultation MCP prompt provides this workflow for clients
that support prompts. The tools work directly in chat too:
plan_architecture_reviewtakes a repository-relativefilePathsinventory and optionalcontext. It suggests files to read and asks up to three questions at a time.- The assistant reads related files through its own workspace tools and calls
review_application_architecturewithfiles: [{ path, content }]and the context collected so far. - Answer the follow-up questions. The assistant resubmits the relevant files and updated context, then uses the evidence to review the design and compare alternatives.
The review covers product fit, routing/rendering, module boundaries, data access, authorization, reliability, testing/delivery, and deployment/cost. JavaScript/TypeScript source is parsed into an import graph. Next.js checks include transitive client imports, private environment access, async Client Components, metadata exports, error boundaries, Server Action modules, and explicit Edge runtime incompatibilities. Type-only imports and Server Action boundaries are respected.
Context fields are purpose, criticalFlows, accessControl, data,
rendering, deployment, reliability, testing, and constraints. Each
holds the owner's answer as text. Calls are stateless: carry answers forward
instead of relying on a server-side conversation ID.
Submit up to 80 files, at most 150,000 characters per file and 500,000 combined.
Use paths relative to one application package root, including package.json
and tsconfig.json or jsconfig.json. Missing imports become evidence requests,
not invented findings. The intake accepts up to 3,000 file paths.
Results include an architecture map, referenced findings, an assessment agenda for every review area, and the next questions. The MCP provides static evidence and the connected assistant's model reasons through the architecture. No separate hosted model is invoked, and the tools do not clone repositories or run submitted code. A clean static check is not a whole-system correctness verdict. The MCP config page has an interactive review-brief builder.
Infrastructure scanning
scan_iac parses Terraform HCL/JSON, CloudFormation YAML/JSON, and Kubernetes
manifests, including multi-document YAML and Kubernetes Lists. It also reads
Dockerfiles, GitHub Actions workflows, Helm templates, Ansible playbooks,
Bicep files, and ARM templates. It returns a
resource inventory and findings with stable rule IDs, severity, property paths,
line locations, and remediation. Findings never include matched secret values.
Checks cover public ingress, wildcard IAM, public storage, encryption settings, bucket versioning, RDS protection, EC2 metadata, Kubernetes privileges, images, resource requests, probes, replicas, inline Secrets, and RBAC. Literal credential and HTTP URL checks also run against parsed resource properties.
Example tool arguments:
{
"content": "resource \"aws_db_instance\" \"app\" { publicly_accessible = true }",
"format": "terraform",
"focus": "security",
"minSeverity": "medium",
"maxFindings": 100
}
Both tools accept focus (general, security, reliability, or cost),
minSeverity (info through critical), and maxFindings (1 to 500, default
100). Content must contain 1 to 500,000 characters and cannot be whitespace.
format defaults to auto; only review_architecture accepts application.
Results are returned as JSON text and MCP structuredContent. totalFindings
and totals cover all findings matching the filters; truncated signals that
maxFindings limited the returned list. rulesEvaluated lists the IaC checks
that ran. Malformed input returns a tool error, not a clean scan.
IaC reviews use the same scanner through either tool. Application reviews use text patterns. Neither mode inspects live infrastructure. Terraform expressions, CloudFormation intrinsics, and external modules are not evaluated. HCL line 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 transport
Each hosted tools/call is counted against the account's monthly scan allowance through the API's
POST /api/mcp/usage, before the tool runs. Only the API's mcp_scan_limit_reached answer blocks a call,
as a tool error with the upgrade text. An outage or timeout (3 seconds) lets the call run. Initialize and
tools/list are not counted. The CLI and the stdio package run offline and are not metered.
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. A successful check is
reused for up to 60 seconds, so a revoked token can run tools for up to a
minute. 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 development
People working on this repo need Node.js 20 or newer. This is not the way to connect a client.
git clone https://github.com/SkaleAgents/mcp-server.git
cd mcp-server
npm install
npm run build
npm test
Environment
| Variable | Required | Description |
|---|---|---|
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. |
MCP_RESOURCE_URL | No | Hosted transport audience. Defaults to https://skaleagents.com/mcp; must match the API OAuth configuration. |
Steady-state tool latency probe
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
BENCHMARK_SAMPLES from 1 to 200 to change those counts. It refuses to start
without the token and never opens an OAuth browser flow.
Set BENCHMARK_INPUT_FILE to an existing, non-secret application source file to
measure that source instead of the fixed snippet. Run separate samples for
different file sizes or code patterns. The output reports only the input byte
count and SHA-256 digest, not its path or contents. The supplied source must be
nonempty and at most 500,000 characters. Use the same local file and pinned
package commit when comparing runs.
Each timed call includes JSON-RPC transport, hosted API account validation,
static review, and the API bot-hint lookup. Process startup, the MCP handshake,
OAuth login or refresh, and a hosted MCP runtime are outside the timer. The
output contains aggregate p50/p95/p99/max latency, the API origin, and counts.
It also reports response-header timing for the /api/user and /api/bots
fetches, their overlap, and the remaining tool-call time after subtracting the
union of those intervals. Overlapping time is counted once.
That remainder includes response bodies, local work, and stdio overhead; it is
not a single server or network measurement. Output omits the credential,
account, and source text. A failed or unauthorized
call aborts instead of being counted as a successful sample. This short,
single-client diagnostic does not establish the platform's sub-second p95 or
monthly availability target.
Auth behavior
- 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
apiRBAC.
Hub contract: docs/contracts/mcp/tools.md
@skaleagents/swarmnpm install @skaleagents/swarm