CLI & MCP Tool Specification

CLI Command Families

The canonical terminal form is short and boring. Good. I want a runtime surface that can be scripted without ceremony: asd <tool-name> [--flag value], with the short name derived from the engine tool by stripping sd_ and replacing underscores with hyphens. The pack-local install path is fixed, Node 20 or newer is required, and the launcher never falls back to a global executable or a sibling checkout. That last point matters in release verification because the bundle is supposed to prove it can stand on its own.

node platform/compiler/emit-packs.mjs --output /tmp/asd-packs
PACK=/tmp/asd-packs/cli
mkdir -p "$HOME/.local/bin"
ln -sf "$PACK/asd" "$HOME/.local/bin/asd"
export PATH="$HOME/.local/bin:$PATH"
asd --version
asd help

Flags map one-to-one onto tool arguments. Strings stay strings. Numbers, booleans, arrays, and objects are validated before the tool runs. Arrays and objects travel as JSON literals on the command line. Unknown flags, missing required flags, positional arguments, and invalid enum values exit 1 with a real error instead of a fuzzy best effort.

Outside the 30 engine tools, the CLI also exposes asd help and asd --version. Everything else is the registry. That separation keeps the book simple: if a command begins with a practice verb such as project-create, method-run, or phase-advance, it is really the schema-backed tool under the hood.

Two CLI behaviors are worth memorizing because they surprise people coming from softer tools. First, booleans can be bare flags or explicit true/false, but arrays and objects must be valid JSON literals. Second, exit code 1 is overloaded on purpose: it means either a real usage or runtime error, or a completed gate returning a failing verdict such as sd_factcheck with \"pass\": false. That makes CI wiring simple. A green-looking report with a failing top-level gate cannot quietly slip through as success.

MCP Tools by Family

The MCP surface exposes the same 30 tools over newline-delimited JSON-RPC 2.0 on stdio. The naming stays explicit: sd_project_create, sd_method_run, sd_review, and so on. Hosts commonly prefix those names again when they mount the bundle, which is why a Claude Code transcript may show mcp__asd__sd_method_run even though the underlying tool remains sd_method_run.

What matters operationally is the family semantics. Project tools work on the workspace tree. Evidence tools allow only three evidence kinds: quote, telemetry, and document. Artifact writes always persist honestly: acceptance success still lands as draft when Critic review is outstanding, acceptance failure persists a draft with machine-readable failures, and a dangling evidence reference is rejected before any write. Review and phase tools are the governance spine, and they keep human authority separate from automated checks.

Resources and Prompts

The MCP surface serves the corpus as resources and the role library as prompts. When the corpus roots are present, resources/list returns 228 resources total. The page size is 100, so a client that wants the full inventory must keep paginating by cursor until the list is exhausted. The URI space is intentionally small:

resources/read returns exact UTF-8 payload, MIME type, version, size, and logical provenance, never an absolute filesystem path. If the runtime is copied without its corpus roots, the list can legitimately come back empty while the 30 runtime tools still work. That is a visible boundary, not a silent fallback.

prompts/get returns the shared role contract followed by the role-specific instruction set as one user message. If ASD_AGENTS_ROOT is unavailable, the prompt list is empty by design. Again: explicit boundary, no fake fallback.

Client Configurations

The pack-local rule is simple: the emitted bundle’s launcher path is relative to the pack itself. When a client runs directly from the installed pack, the relative entrypoint is correct. When a client copies the snippet elsewhere, replace the relative path with an absolute path. The server launcher does not search PATH for a spare binary.

{
  "mcpServers": {
    "asd": {
      "command": "node",
      "args": ["mcp/bin/server.mjs"]
    }
  }
}

Claude Code uses the plugin-root variant:

{
  "mcpServers": {
    "asd": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/bin/server.mjs"]
    }
  }
}

OpenCode uses the command-array form:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "asd": {
      "type": "local",
      "command": ["node", "mcp/bin/server.mjs"]
    }
  }
}

Codex supports either the registration command or a TOML block:

codex mcp add asd -- node "$PWD/platform/packs/codex/mcp/bin/server.mjs"

[mcp_servers.asd]
command = "node"
args = ["mcp/bin/server.mjs"]

Those four snippets are enough to capture the pack-local rule and the three host-specific variants readers keep asking about. The operational nuance is that each host chooses its own working directory, which is why the relative bundle path is a rule of the installed pack, not a universal truth of the client machine.

Protocol and Error Codes

The stdio server speaks newline-delimited JSON-RPC 2.0 with MCP revision 2025-06-18. The lifecycle starts with one initialize call before tools/list, tools/call, resources/list, resources/read, prompts/list, or prompts/get. The response advertises tools, resources, and prompts, and identifies the server as asd-mcp version 0.1.0. Tool failures return MCP content blocks with isError: true; protocol framing remains valid.

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}

Default tool timeout is 30 seconds. The frame limit is 1 MiB. Cancellation uses $/cancelRequest. Notifications remain silent. None of that is exotic, but it is precisely the kind of detail that matters when a client blames the server for behavior that actually belongs to the transport contract.

One more boundary belongs here because it is easy to overclaim: ACP on the MCP surface is asd-acp/1 with capability record-only. The runtime can record orchestration plans, dispatch attempts, handoffs, and human gates. It does not prove that the host launched a new process. host-agent-spawn therefore remains an explicit unsupported path on the generic surface unless a host adapter really wires it up.

Environment and Workspace

ASD_WORKSPACE sets the root directory for projects. If I do nothing, the runtime uses ~/.asd/projects. That default is fine for live use. It is a bad idea for tests, demos, and disposable verification, which is why the docs push isolated temporary roots. The project tree itself is plain: project.json, evidence/index.json, artifact JSON files, exported renders, and sops/. Files are the record of truth.

export ASD_WORKSPACE="$(mktemp -d)/projects"
mkdir -p "$ASD_WORKSPACE"
asd project-create --name "Metrovale Access" --client "Fictional composite" \
  --sector public-transport --service "step-free journeys" --phase discover

The MCP server adds three corpus-root environment variables beside the workspace root: ASD_BOOKS_ROOT, ASD_ARTICLES_ROOT, and ASD_AGENTS_ROOT. They control the served books, articles, and role prompts independently. That means a client can still use the 30 runtime tools even when the book corpus or prompt roots are unavailable.

The disposable verification pattern is stronger than it looks. Each verified bundle is run from an isolated HOME, PATH, current working directory, and workspace, then forced through a representative sequence: initialize, inspect the 30 tools, page through the 228 resources, load the 10 prompts, create a project, capture evidence, write an artifact, record an evidence-cited review, and replay factcheck. That is the right level of proof for a transport bundle. It shows pack-local interoperability without pretending that every host UI or every orchestration surface has already been exercised live.

That last sentence is the right place to stop. The CLI and MCP surfaces are fully specified, but they still obey the book’s broader honesty rule: prove what ran, say what the receipt covers, and do not promote an emitted pack into host-execution evidence unless the host actually exercised it.