Skip to main content
Suspec
mcp server / verdict-free adapter

suspec-mcp

A verdict-free MCP for Suspec workspace facts.

Status, checks, artifacts, and review data over stdio.

v0.2 surfaceno boardno verdict

client request

local stdio

  1. 01 / host

    Client

    Claude Desktop, Cursor, or another MCP host.

  2. 02 / pipe

    stdio

    A local process pipe, not a hosted service.

  3. 03 / adapter

    suspec-mcp

    Verdict-free adapter around the workspace.

  4. 04 / json

    CLI JSON

    Commands return structured facts.

  5. 05 / records

    Workspace

    Markdown artifacts stay the source of truth.

pwrcheckevidence

// Claude Desktop / Cursor MCP config

{

"mcpServers": {

"suspec": {

"command": "suspec-mcp",

"args": ["--workspace", "/path/to/workspace"]

}

}

}

package boundary

adapter package / cli stays small

note

suspec-mcp adapts the CLI's public --json contract. The SDK lives here so suspec-cli can stay small.

guardrails.ts

What it does not do

It does not run an agent loop, write a board or a review result, or decide whether code is done. Safe-write tools only scaffold fresh artifacts; they issue no verdict.

  • scope

    No board, no result

    It writes no board and no review result. Safe-write tools only scaffold fresh artifacts.

  • defer

    No verdict

    It reports facts. Review owns Pass, Fail, Unverified, or Blocked.

  • bound

    Root-confined

    Paths stay inside the configured workspace root.

  • json

    CLI contract only

    It calls the CLI JSON surface.

tools / 12

MCP tools

Read and reconcile calls, plus a verdict-free safe-write tier that scaffolds fresh artifacts. Each maps to a CLI JSON command.

read

  • suspec_get_status
  • suspec_list
  • suspec_check_workspace
  • suspec_check_file
  • suspec_get_task
  • suspec_get_spec
  • suspec_get_review
  • suspec_get_checks

reconcile

  • suspec_reconcile

safe-write

  • suspec_scaffold_spec
  • suspec_split_task
  • suspec_scaffold_finding
resources + prompts

Context the client can ask for

Resources expose the board, checks, and selected artifacts. Prompts give clients a Suspec-shaped starting point.

resources

  • suspec://workspace
  • suspec://status
  • suspec://checks
  • suspec://tasks/{id}
  • suspec://specs/{id}
  • suspec://reviews/{id}
  • suspec://findings/{id}

prompts

  • suspec_task_briefing
  • suspec_before_done
  • suspec_review_assistant
  • suspec_evidence_rule
  • suspec_finding_candidate
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

# until a published build is available

$ HOST=github.com/jcosta33

$ PKG=suspec-mcp

$ SRC=$HOST/$PKG.git

$ git clone https://$SRC

$ cd "$PKG"

$ pnpm install

$ pnpm build

$ npm link

source

Read the adapter code

Source, issues, and tests live on GitHub.

GitHub See the CLI