swarm-mcp
The swarm-mcp server provides workspace inspection, reconciliation, and safe-write scaffolding for a spec/review discipline system. All outputs surface facts and diagnostics — never a pass/fail verdict (noVerdictIssued: true), keeping authority with human reviewers.
Workspace Status & Checks
swarm_get_status: Retrieve the derived board showing specs, tasks, and review statuses.swarm_check_workspace: Run the checks contract over every artifact in the workspace, returning diagnostics.swarm_check_file: Run checks against a single file (spec, task, review, or change-plan) by path.swarm_get_checks: Retrieve the checks contract (version, check IDs, names, severities).
Inspect Artifacts
swarm_get_task: Get a parsed task packet — scope, affected areas, claimed changes, frontmatter.swarm_get_spec: Get a parsed spec — frontmatter, requirements, verify commands, sections.swarm_get_review: Get a parsed review packet — status, coverage rows, verify blocks.
Reconcile & Validate
swarm_scan_task: Reconcile a task in progress against its spec and current worktree diff — surfaces coverage gaps, out-of-scope changes, self-report mismatches.swarm_reconcile_review: Compare a finished review packet against the task, spec, and git diff — surfaces coverage gaps, empty-evidence Pass rows, scope drift, and self-report mismatches.swarm_validate_review_packet: Check a review packet's structure, status fields, and evidence requirements.
Safe-Write Scaffolding (no verdicts, no board modifications)
swarm_scaffold_spec: Create a new specification.swarm_split_task: Split a task by copying scope from an existing one.swarm_scaffold_finding: Promote and scaffold a finding.
Resources & Prompts: Templated URIs expose workspace, status, checks, and individual artifacts; prompts provide contextual stances (implementer, reviewer, evidence rule, finding candidate) to guide agent behavior.
Provides tools for reconciling facts, checking workspace state, scanning tasks, managing reviews, and loading parsed artifacts via the Swarm CLI.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@swarm-mcp what evidence is missing?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
suspec-mcp
A thin MCP stdio adapter for shell-less access to Suspec's deterministic checker. Thin is the feature.
It requires checks contract 0.27.0, validates every CLI JSON payload, and preserves ordered reports
and exit status.
Tools
suspec_check
Runs one CLI process over an ordered non-empty array of absolute artifact paths. Frontmatter type:
selects behavior.
Input | Meaning |
| ordered non-empty absolute primary paths |
| absolute spec for task paths |
|
|
Spec, task, change-plan, and campaign inputs receive their CLI checks. Inventory, audit, research,
and panel return checked: false. Missing and unknown types are rejected.
One invocation preserves cross-file checks such as C002. Task paths share one specPath; every task
must name that spec. Invalid companion pairing produces the CLI's structured refusal with ok: false.
Every artifact result repeats its type. Only the optional final (file set) report has none.
suspec_get_checks
Returns the contract version plus each core check's ID and severity in concise mode. Use
responseFormat: "detailed" for names. The same contract is available at suspec://checks.
Startup and resource reads require exact contract 0.27.0 at exit 0. Resource failure throws instead
of returning an error document as resource content.
Related MCP server: governed-mcp
Envelope
Every successful adapter invocation returns:
ok: whether the CLI ran and produced a valid payload, not whether diagnostics are clean;source: exact command and exit code;data: validated detailed output or concise projection;optional
note;responseFormat.
ok means the adapter worked, not that the artifact is good. A check with blocking diagnostics
remains ok: true; inspect data.level, diagnostics, and source.exitCode.
CLI exits 0, 1, and 2 belong to the contract. Any other exit is an adapter launch failure.
JSON-shaped stdout does not negotiate a new contract. Structured CLI errors are accepted only at
exit 2.
Install
Requires Node.js 22.6 or newer and a suspec CLI. Neither package is published.
git clone https://github.com/jcosta33/suspec-mcp
cd suspec-mcp
corepack enable
pnpm install --frozen-lockfileConfigure absolute entry points so GUI clients do not depend on shell PATH:
{
"mcpServers": {
"suspec": {
"command": "/absolute/path/to/suspec-mcp/bin/suspec-mcp.js",
"args": ["--suspec-bin", "/absolute/path/to/suspec-cli/bin/suspec.js"]
}
}
}CLI precedence:
Flag | Environment | Default |
|
|
|
Each tool call supplies full artifact paths. The server binds no repository, workspace,
configuration, or store. It is an adapter, not a second product brain.
~/.agents/artifacts/<workspace>/ has no special runtime meaning. User-level policy installation is
the CLI's job: run suspec setup directly. MCP exposes no setup, storage, promotion, lifecycle, or
orchestration surface.
Security
Primary and companion paths must be absolute and contain no control, format, or line-separator characters.
The adapter passes a fixed argument array without a shell.
Only
checkand supported companion or contract flags reach the CLI.setupis rejected before a subprocess starts.The CLI check surface is read-only.
The server can read any path available to its process. Filesystem permission is the security boundary, not a suggestion. Match process permissions to the client trust boundary or apply OS sandboxing.
Develop
Fixture drift uses the real CLI. Handwritten agreement proves nothing. Set SUSPEC_BIN to an
absolute CLI source path; otherwise a sibling package named suspec-cli may satisfy discovery.
Generation rejects other packages.
export SUSPEC_BIN=/absolute/path/to/suspec-cli/bin/suspec.js
pnpm install
pnpm test:run
pnpm gate
pnpm fixturestest/fixtures/provenance.json records CLI git HEAD, complete dirty-worktree hash, and binary hash.
scripts/generate-fixtures.mjs captures output; tests parse every fixture through
src/suspec/contract.ts. Fixtures are generated, never hand-edited.
License
MIT
Available Tools
10 toolsswarm_check_fileCheck one artifact fileARead-onlyIdempotent
Run the Swarm checks contract over one file (spec / task / review / change-plan). Returns diagnostics, never a verdict.
Inputs: path (required). Returns: ok, noVerdictIssued, noVerdictNote, source, +3 more
swarm_check_workspaceCheck the whole workspaceARead-onlyIdempotent
Run the Swarm checks contract over every spec + change plan. Returns diagnostics, never a verdict.
Inputs: no named parameters. Returns: ok, noVerdictIssued, noVerdictNote, source, +3 more
swarm_get_checksGet the checks contractARead-onlyIdempotent
The checks contract — version + the core checks (id/name/severity). What review must satisfy.
Inputs: no named parameters. Returns: ok, noVerdictIssued, noVerdictNote, source, +3 more
swarm_get_reviewGet a parsed review packetARead-onlyIdempotent
The review packets status, coverage rows, and verify blocks. Read-only; the verdict is the humans.
Inputs: task (required). Returns: ok, noVerdictIssued, noVerdictNote, source, +3 more
swarm_get_specGet a parsed specARead-onlyIdempotent
The spec`s frontmatter, requirements (id + line + named verify command), and sections. Read-only.
Inputs: spec (required). Returns: ok, noVerdictIssued, noVerdictNote, source, +3 more
swarm_get_statusSwarm workspace boardARead-onlyIdempotent
The derived workspace board — specs, their tasks, and review status. Read-only; no verdict.
Inputs: no named parameters. Returns: ok, noVerdictIssued, noVerdictNote, source, +3 more
swarm_get_taskGet a parsed task packetARead-onlyIdempotent
The task packet`s scope, affected areas, claimed changes, and frontmatter (id/source/status). Read-only.
Inputs: task (required). Returns: ok, noVerdictIssued, noVerdictNote, source, +3 more
swarm_reconcile_reviewReconcile a review packet vs task/spec/diffARead-onlyIdempotent
Reconcile a finished run: compare task, spec, review packet, and git diff. Returns coverage gaps, empty-evidence Pass rows, scope drift, and self-report mismatches as facts + a derived human-attention list. Never issues a final verdict — a human or an independent reviewer owns the result.
Inputs: task (required), base. Returns: ok, noVerdictIssued, noVerdictNote, source, +3 more
swarm_scan_taskScan a task in progress (reconcile vs the diff)ARead-onlyIdempotent
Reconcile a task against its spec and the worktree diff to surface coverage gaps, out-of-scope changes, and self-report mismatches — before a review packet exists. Same engine as reconcile_review. Never a verdict. If the task has no live worktree, returns a structured "not runnable here" result, not an error.
Inputs: task (required), base. Returns: ok, noVerdictIssued, noVerdictNote, source, +3 more
swarm_validate_review_packetValidate a review packet (structure + evidence)ARead-onlyIdempotent
Run the review-file checks (C012 coverage, C013 verify-evidence) over a review packet: structure, status, and that Pass rows carry evidence. The diff-aware half (out-of-scope, self-report) comes from reconcile_review when a worktree exists. Returns diagnostics, never a verdict.
Inputs: review (required). Returns: ok, noVerdictIssued, noVerdictNote, source, +3 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool has a clearly distinct purpose: checking files vs workspace, getting different entities (checks, review, spec, status, task), reconciling reviews, scanning tasks, and validating packets. No overlapping functionality.
All tools follow the consistent pattern 'swarm_verb_noun' using snake_case. Verbs are appropriate (check, get, reconcile, scan, validate) and nouns are specific, making the set predictable and easy to navigate.
10 tools is well-scoped for a server focused on analysis and verification of specifications, tasks, and reviews. Each tool serves a necessary function without redundancy or bloat.
The tool surface covers all essential operations for the server's analysis purpose: checking, retrieving all relevant entities, reconciling, scanning, and validating. No obvious gaps given the read-only/analysis scope.
Related MCP Connectors
Hosted MCP server for pre-action AI governance verdicts, model routing, and evidence verification.
41MCP server providing access to the Scorecard API to evaluate and optimize LLM systems.
Guarded MCP server for agent-readable business truth, provenance, readiness, and discovery.
Evidence-readiness MCP server: validate, audit, and score briefs, memos, and evidence packs.
Related MCP Servers
- AlicenseAqualityBmaintenanceAgent memory on a local SQLite file or on PostgreSQL with pgvector, with provenance, trust verdicts and explicit abstention when memory cannot support an answer.5551 PyPI7AGPL 3.0
- FlicenseNot gradedqualityDmaintenanceMCP server that enforces governance on agentic decisions with auditable evidence records, providing tools for understanding, calibrating confidence, and navigating handoffs based on policy.-
- AlicenseAqualityBmaintenanceA local-first MCP server for retrieving a small evidence set and recording reviewed conclusions, policy-gated and redacted without giving an agent general filesystem access.5MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that exposes Elephant Accountability's audit tiers, EVI v0.9 methodology, fit assessment, proof points, and agent-initiated audit requests to AI agents.MIT