Skip to main content

mcp server / the check surface, shell-less

suspec-mcp

suspec check for shell-less MCP clients. Two tools, local stdio, no verdict.

local stdiofacts onlychecks contract 0.21.0
local bridge

Shell-less clients, same checks

Terminal clients run suspec check directly. suspec-mcp gives shell-less clients the same checks over local stdio. Adapter, not second opinion.

Source: docs/reference/cli.md (opens in new tab)

client request

local stdio

  1. 01 / host

    Client

    Claude Desktop, Cursor, or anything that speaks MCP without a shell.

  2. 02 / pipe

    stdio

    A local process pipe, not a hosted service.

  3. 03 / adapter

    suspec-mcp

    A thin, hardened adapter: fixed argv, allow-listed flags, no-verdict envelope.

  4. 04 / facts

    suspec check --json

    The CLI records the facts: check ids, severity, exit code.

  5. 05 / files

    Artifacts

    Exactly the files you name, by explicit path. Read-only.

mcp.json

Claude Desktop / Cursor

config
{
  "mcpServers": {
    "suspec": {
      "command": "/absolute/path/to/suspec-mcp/bin/suspec-mcp.js",
      "args": ["--suspec-bin", "/absolute/path/to/suspec-cli/bin/suspec.js"]
    }
  }
}
guardrails.ts

Boundaries

The server treats every client input as hostile and every result as facts-only: two tools, one verb reaching the CLI, no writes, and no review result. Ever.

  • scope

    Two tools, no more

    suspec_check and suspec_get_checks. Shell-capable clients can use the CLI.

  • defer

    No verdict

    ok means the CLI returned parseable output. Verdicts stay human.

  • paths

    Explicit paths

    Absolute paths only. No workspace or artifact discovery.

  • json

    Thin, hardened adapter

    Fixed argv, allow-listed flags, read-only. Relays suspec check --json.

tools

Check · contract

One runs the checks over explicit artifact paths; one prints the contract they use. Both shell out to suspec check --jsonand relay the CLI's facts.

check

  • suspec_check

Check ordered absolute paths. Reviews name spec and optional task companions.

contract

  • suspec_get_checks

Return the contract version and each check's id, name, and severity.

For a review, spec is always required and taskexactly when the review's frontmatter names a task:. A missing companion surfaces the CLI's own blocking refusal — never a silently shallower check.

envelope + resource

The no-verdict envelope

Every result uses the same structure. ok means the CLI ran. Whether the artifact is clean lives in the facts; the server never adds an assessment of its own.

envelope

  • ok

    Runnability, not a result: the CLI ran and returned a parseable payload. A check that found blocking diagnostics is still ok: true.

  • source

    Provenance: the exact CLI command run and its exit code — 0 clean · 1 warning · 2 blocking.

  • data

    The CLI's --json facts, verbatim or a targeted slice: level, diagnostics, locations.

  • noVerdictIssued

    Always true. On every result.

resources

  • suspec://checks

The checks contract as a fixed resource — the same payload as suspec_get_checks.

install.sh

Install from source for now

The package exposes a suspec-mcp binary. It expects the Suspec CLI on PATH. Use SUSPEC_BIN or --suspec-bin to set the binary explicitly.

Binary
suspec-mcp
Requires
suspec CLI
Override
SUSPEC_BIN
pwrcheckevidence

# install from source; no published package yet

$ git clone https://github.com/jcosta33/suspec-mcp

$ cd suspec-mcp

$ corepack enable

$ pnpm install --frozen-lockfile

source

Read the adapter code

Source, issues, and tests live on GitHub. The CLI reference covers the check surface this adapter borrows.

GitHub (opens in new tab) See the CLI CLI reference notes (opens in new tab)