Skip to main content
Glama

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

paths

ordered non-empty absolute primary paths

specPath

absolute spec for task paths

responseFormat

concise or detailed

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-lockfile

Configure 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

--suspec-bin <path>

SUSPEC_BIN

suspec on PATH

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 check and supported companion or contract flags reach the CLI. setup is 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 fixtures

test/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 tools
swarm_check_fileCheck one artifact fileA
Read-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 workspaceA
Read-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 contractA
Read-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 packetA
Read-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 specA
Read-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 boardA
Read-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 packetA
Read-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/diffA
Read-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)A
Read-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)A
Read-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

    A4.3/5.0

    Scored across 10 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    Related MCP Servers