asd-mcp

Generated from the canonical monorepo the-agentic-service-designer at commit 5acee17c1949. This repository is mirrored at sammozaffari/asd-mcp; both copies are pushed from the same publish run and carry identical content.

Standalone MCP server for the Agentic Service Designer (ASD): a Service Design practice encoded as an evidence-gated runtime. One self-contained server.mjs (Node >= 20, zero npm dependencies, node builtins only) exposing:

• 29 tools — projects, evidence, typed artifacts, method SOPs, Critic review, orchestration, exports, factcheck, phase gates.
• 226 resources — the Service Design knowledge corpus (asd://books/*, asd://articles/*, role contracts, templates, artifact schemas).
• 10 role prompts — the canonical SD roles (critic, researcher, synthesizer, ideator, prototyper, mapper, measurer, librarian, presenter, orchestrator).

State lives in a portable on-disk project store, so an engagement can move between hosts without loss.

1. Quick start

git clone https://github.com/imehr/asd-mcp.git
./asd-mcp                        # or: node mcp/bin/server.mjs

Speaks newline-delimited JSON-RPC 2.0 over stdio (MCP protocol 2025-06-18). Smoke test:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  | node mcp/bin/server.mjs

Expect a result envelope advertising tools, resources, and prompts capabilities plus a derived inventory.currentToolCount.

2. Client configuration

The launcher resolves its corpus from mcp/data/ next to itself — copy or clone anywhere; only Node matters.

Claude Code (project .mcp.json)

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

(For the full native plugin — agents + skills + /asd + this server — use the asd-plugin repository instead.)

Codex CLI / desktop (~/.codex/config.toml)

[mcp_servers.asd]
command = "node"
args = ["/absolute/path/to/asd-mcp/mcp/bin/server.mjs"]

The desktop app reads the same registration as the CLI.

Kimi Code (mcp.json)

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

Project-level servers need Trust this folder.

OpenCode / generic stdio clients

Point any MCP stdio client at node /absolute/path/to/asd-mcp/mcp/bin/server.mjs. Because clients choose their own working directory, prefer absolute paths.

3. Environment

Variable	Purpose
ASD_WORKSPACE	Project store root (default: cwd; store default ~/.asd/projects).
ASD_BOOKS_ROOT / ASD_ARTICLES_ROOT / ASD_AGENTS_ROOT	Override individual bundled corpus roots.
ASD_CORPUS_DATA_ROOT	Override the whole bundled data directory.

With every corpus root pointed elsewhere, prompts list empty and resources reduce to the 9 built-in metadata/template entries — tool surfaces stay intact.

4. Tool reference (29 tools)

Family	Tools	What they do
Projects	sd_project_list sd_project_create sd_project_open	Create/open/list engagements; project carries phase, client, sector, service.
Evidence	sd_evidence_add sd_evidence_query sd_evidence_import	Capture quote/telemetry/document records; ids are content hashes; everything downstream must cite them.
Methods	sd_method_list sd_method_run	List 74 SOPs by phase; run one to get steps, owner role, provenance, acceptance rules, and output artifact kind.
Artifacts	sd_artifact_write sd_artifact_get sd_artifact_list	Write typed artifacts against closed kind schemas (32 kinds, 38 catalog rows); drafts persist with machine-readable failure rows; dangling evidence refs are hard errors.
Review	sd_review sd_review_list	The Critic gate: pass promotes draft→final when acceptance holds; veto requires defect rows with fixes and writes an evidence-cited review log.
Factcheck & gates	sd_factcheck sd_phase_advance	Project-wide integrity check (CI treats false as exit 1); advance discover→define→develop→deliver with a required human approval receipt.
Orchestration	sd_orchestration_plan sd_orchestration_status sd_orchestration_dispatch sd_orchestration_handoff	Plan multi-role work, dispatch, track, and hand off between roles.
Canvas	sd_canvas_add sd_canvas_list sd_canvas_remove	Shared scratch space for links/notes during collaboration.
Export	sd_export_artifact sd_export_report	Render artifacts/reports to deliverable form.
Knowledge & meta	sd_knowledge sd_practice_get sd_schema_get sd_template_list sd_template_get	Query the canon; get practice contract; fetch closed schemas; browse 6 authored templates.

CLI parity: every tool is also a kebab-case subcommand of the standalone CLI pack (sd_project_create → asd project-create).

5. Resources & prompts

• resources/list is cursor-paginated (page size 100, opaque base64url cursor): pass {"params": {"cursor": "<nextCursor>"}} until absent. URIs look like asd://books/01-this-is-service-design-doing, asd://articles/31, plus template/schema/metadata entries.
• resources/read returns the text — books as chaptered markdown, articles as case studies labelled synthetic or illustrative.
• prompts/list → the ten role prompts (critic, researcher, …); prompts/get with a name returns the role's contract prompt.

6. Tutorial — first engagement over raw JSON-RPC

Same scenario as the plugin repo README (Metrovale Council housing repairs), driven directly so you can see every call. Initialize first, then:

1. Create the project

{"jsonrpc":"2.0","id":10,"method":"tools/call","params":{"name":"sd_project_create",
 "arguments":{"name":"Housing Repairs","client":"Metrovale Council",
              "sector":"local-government","service":"housing-repairs"}}}

Note the returned projectId (e.g. housing-repairs-9cb49d1c) and that the phase starts at discover.

2. Capture three evidence records (methods enforce minimums)

{"jsonrpc":"2.0","id":11,"method":"tools/call","params":{"name":"sd_evidence_add",
 "arguments":{"projectId":"…","kind":"quote","source":"tenant-interview-01",
              "body":"Repairs take weeks to get acknowledged"}}}

Repeat for "No single point of contact for repairs" (quote) and "Median first-response time 19 days" (telemetry). Copy the returned hash ids.

3. Run a method SOP

{"jsonrpc":"2.0","id":12,"method":"tools/call","params":{"name":"sd_method_run",
 "arguments":{"projectId":"…","methodId":"aeiou-coding"}}}

Read the contract it returns: owner synthesizer, provenance (18-universal-methods-of-design ch.05), acceptance (min-nodes 3, min-evidence-per-node 2, non-empty theme), output kind affinity-cluster-set.

4. Check the schema, then write the artifact

{"jsonrpc":"2.0","id":13,"method":"tools/call","params":{"name":"sd_schema_get",
 "arguments":{"kind":"affinity-cluster-set"}}}

Node members are closed: id, label, evidence[] ({evidenceId, quote?}), fields{} with cluster required. Then:

{"jsonrpc":"2.0","id":14,"method":"tools/call","params":{"name":"sd_artifact_write",
 "arguments":{"projectId":"…","methodId":"aeiou-coding","title":"AEIOU clusters",
 "nodes":[
   {"id":"n1","label":"Latency",
    "evidence":[{"evidenceId":"<hash1>"},{"evidenceId":"<hash3>"}],
    "fields":{"cluster":"responsiveness","theme":"slow response"}},
   {"id":"n2","label":"Ownership",
    "evidence":[{"evidenceId":"<hash2>"},{"evidenceId":"<hash1>"}],
    "fields":{"cluster":"accountability","theme":"fragmented ownership"}},
   {"id":"n3","label":"Backlog growth",
    "evidence":[{"evidenceId":"<hash3>"},{"evidenceId":"<hash2>"}],
    "fields":{"cluster":"demand","theme":"rising demand"}}],
 "edges":[]}}}

Result: an artifact with status:"draft" and an artifactId. Expect strict rejections while learning the schema — unknown fields, unresolvable evidence ids, and unmet acceptance minimums all fail with named errors instead of silently passing.

5. Critic pass → final

{"jsonrpc":"2.0","id":15,"method":"tools/call","params":{"name":"sd_review",
 "arguments":{"projectId":"…","artifactId":"…","verdict":"pass",
 "rows":[{"rowKind":"proposal","severity":"low","check":"clusters-grounded",
          "result":"pass","message":"All clusters cite captured tenant evidence",
          "evidenceId":"<hash1>"}]}}}

A pass needs at least one evidence-cited row (and no defects); if acceptance holds against the live manifest, status flips to "final".

6. Factcheck, then the human gate

{"jsonrpc":"2.0","id":16,"method":"tools/call","params":{"name":"sd_factcheck",
 "arguments":{"projectId":"…"}}}

{"jsonrpc":"2.0","id":17,"method":"tools/call","params":{"name":"sd_phase_advance",
 "arguments":{"projectId":"…","toPhase":"define","idempotencyKey":"gate-discover-1",
 "approvalReceipt":{"receiptId":"gate-discover-1","decision":"approve",
                   "rationale":"Discover complete","approvedBy":"service-lead",
                   "approvedAt":"2026-08-22T12:00:00Z"}}}}

decision must be "approve"; the receipt requires receiptId, rationale, approvedBy, approvedAt. The gate re-checks that every design artifact is final before advancing. That receipt is the audit record of a human decision — agents cannot forge the phase forward.

7. Troubleshooting

• Server starts but lists no corpus — you moved the checkout without mcp/data/; keep the tree intact or set the override env vars.
• Client shows no tools — check the path is absolute after copying; Kimi needs workspace trust; Claude Code plugins should use the vendored .mcp.json from asd-plugin instead.
• macOS /tmp paths — launch through real paths; symlinked temp dirs can break main-module detection.
• unknown tool (-32602) — tool names are the sd_* registry names, snake_case over MCP, kebab-case on the CLI.

8. Provenance and boundaries

Generated by scripts/publish-distribution-repos.mjs; provenance.json records the source commit. Host execution claims live in the source repo's release receipts; this server itself was verified disposable-live (initialize, 29-tool inventory, paginated 225-resource corpus, 10 prompts) at publish time.