Complete MCP Reference

Purpose

This is the dedicated user-facing reference for the local sdd-mcp server.

Use this page when you need to know:

• what the MCP server is for
• which tools, resources, and prompts it exposes
• what each operation does
• what side effects it produces
• what output the user should expect

Keep 33-mcp-server-guide.md for setup and connectivity. Keep 40-command-results-reference.md for script-by-script output details. Keep 43-easy-mcp-guide.md for the non-technical and slash-style command view.

What sdd-mcp is

sdd-mcp is the operational MCP layer of this framework.

It gives AI clients a structured way to:

• create or bootstrap SDD workspaces
• create and inspect specs
• validate the SDD state of a project
• enforce the implementation gate
• write traceability artifacts
• read key project context through MCP resources

It is not just documentation access. It is the runnable interface to the framework.

Visual architecture

flowchart LR
  A["User"] --> B["AI Client"]
  B --> C["sdd-mcp"]
  C --> D["sdd-core"]
  C --> E["MCP Resources"]
  D --> F["Target Project"]
  E --> F
  F --> G["idea/"]
  F --> H["specs/"]
  F --> I["bitacora/"]
  F --> J["docs/"]

Reading path:

• the AI client reads MCP resources and prompts
• sdd-mcp exposes the operational contract
• sdd-core performs the actual project mutations
• the target project stores the resulting SDD artifacts

What the user can expect

When an AI client is connected to sdd-mcp, the user can expect:

• structured outputs instead of vague free text
• deterministic file writes for status, roadmap, logbook, and traceability
• explicit gate checks before implementation
• the option to use the clean default workspace under ./www/<project-name>/
• support for external target project paths on projectRoot-based tools

Scope rules

• Recommended default workspace inside this template: ./www/<project-name>/
• External target project paths are also supported on tools that receive projectRoot
• The runnable project must never be initialized in the template root
• If a target project lives inside this template, it must live under ./www/

Transports

Supported transports:

• stdio
• Streamable HTTP

Entrypoints:

• stdio: packages/sdd-mcp/dist/index.js
• HTTP: http://127.0.0.1:3334/mcp

Tool reference

sdd_create_workspace

Purpose:

• create a managed runnable workspace under ./www/<project-name>/

When to use:

• when the user wants the recommended default workspace inside this template

Input:

• projectName
• assistant
• profile
• useSpecKit

What it does:

• creates the SDD base workspace
• optionally initializes Spec Kit

What the user should expect:

• a clean runnable project folder under ./www/
• no changes outside that managed workspace

Structured output:

• projectRoot
• profile
• assistant
• usedSpecKit

sdd_create_spec

Purpose:

• create the next numbered spec folder from the template bundle

When to use:

• when the target project already has the SDD base and needs a new feature spec

Input:

• projectRoot
• featureName
• owner

What it does:

• creates spec.md, plan.md, tasks.md, research.md, history.md
• creates contracts/README.md
• appends a row to specs/INDEX.md

What the user should expect:

• one new numbered spec directory
• the project index updated automatically

Structured output:

• specId
• specDir
• indexUpdated

sdd_validate

Purpose:

• validate the SDD structure and required files of a target project

When to use:

• before closing a session
• before trusting a migrated or initialized project

Input:

• projectRoot

What it does:

• checks required folders
• checks required files
• checks numbered spec bundles

What the user should expect:

• a structured validation summary
• explicit errors and warnings

Structured output:

• ok
• errors
• warnings
• messages[]

sdd_check_gate

Purpose:

• decide whether implementation is allowed under SDD rules

When to use:

• immediately before implementation

Input:

• projectRoot

What it does:

• checks approval status
• checks plan consistency signals
• checks tasks presence
• checks consent log requirement when approved specs exist

What the user should expect:

• a clear yes/no style gate result
• explicit reasons if implementation must remain blocked

Structured output:

• ok
• errors
• warnings
• approvedSpecs
• totalSpecs
• messages[]

sdd_record_user_consent

Purpose:

• record explicit user approval before implementation starts

When to use:

• only when implementation is actually about to begin

Input:

• projectRoot
• summary

What it does:

• appends a timestamped line to .sdd/user-consent.log

What the user should expect:

• durable approval trace

Structured output:

• logFile
• summary
• timestamp

sdd_list_specs

Purpose:

• list numbered specs and their status

When to use:

• to pick the active spec for a session

Input:

• projectRoot

What it does:

• reads numbered specs
• extracts approval status from spec.md

What the user should expect:

• a compact list of current specs and states

Structured output:

• specs[]
  • id
  • dir
  • status

sdd_generate_status

Purpose:

• build a project status dashboard

When to use:

• at session close
• before handoff

Input:

• projectRoot

What it does:

• creates or replaces STATUS.md
• summarizes active specs
• summarizes task progress
• includes recent project log excerpt

What the user should expect:

• one status document ready to review or share

Structured output:

• path
• content

sdd_generate_roadmap

Purpose:

• generate a roadmap from specs/INDEX.md

When to use:

• when the user wants a visual and markdown roadmap

Input:

• projectRoot

What it does:

• creates or replaces docs/roadmap.mmd
• creates or replaces docs/roadmap.md

What the user should expect:

• one Mermaid diagram source
• one markdown roadmap document

Structured output:

• mermaidPath
• markdownPath
• mermaid
• markdown

sdd_append_project_log

Purpose:

• append a global project log entry

When to use:

• to record high-level session changes

Input:

• projectRoot
• entry

What it does:

• appends content to bitacora/global/PROJECT_LOG.md

What the user should expect:

• one updated project log file

Structured output:

• path
• content

sdd_write_daily_log

Purpose:

• create or replace one daily log file

When to use:

• to store the session note for a date

Input:

• projectRoot
• date
• content

Rules:

• date must use YYYY-MM-DD

What it does:

• creates or replaces bitacora/diaria/YYYY-MM-DD.md

What the user should expect:

• one date-scoped log document

Structured output:

• path
• content

sdd_write_handoff

Purpose:

• create or replace a handoff file

When to use:

• when one session leaves a clear next step for another operator or agent

Input:

• projectRoot
• fileName
• content

Rules:

• fileName must be a simple markdown file name

What it does:

• creates or replaces bitacora/handoffs/<fileName>

What the user should expect:

• one durable handoff document

Structured output:

• path
• content

sdd_write_decision

Purpose:

• create or replace a decision record

When to use:

• when the session makes an important project decision

Input:

• projectRoot
• fileName
• content

Rules:

• fileName must be a simple markdown file name

What it does:

• creates or replaces bitacora/decisiones/<fileName>

What the user should expect:

• one durable decision record

Structured output:

• path
• content

sdd_board_read

Purpose:

• read the visual SDD Builder board of a target project

When to use:

• when the AI needs the canvas layout plus every spec with status and task progress

Input:

• projectRoot

What it does:

• reads specs/board.canvas (JSON Canvas), generating a default layout if missing
• lists specs with approval status and done/total task counts

What the user should expect:

• the exact same view the /builder canvas renders

Structured output:

• canvas (nodes, edges)
• specs (id, dir, status, tasks)

sdd_board_write

Purpose:

• replace the board canvas layout

When to use:

• when the AI arranges or reorganizes cards and connections as a whole

Rules:

• only layout is stored; markdown files are never touched

What it does:

• validates and atomically writes specs/board.canvas

Input:

• projectRoot
• canvas

Structured output:

• ok
• nodes
• edges

sdd_board_connect

Purpose:

• connect two existing board cards with an optional labeled edge

When to use:

• when the AI records a dependency or relation between cards

Rules:

• both node ids must exist on the board
• identical edges are not duplicated (idempotent)

Input:

• projectRoot
• fromNode
• toNode
• label

Structured output:

• canvas

sdd_read_tasks

Purpose:

• read the checkbox tasks of one spec’s tasks.md

When to use:

• before toggling a task, to get line numbers and done state

Input:

• projectRoot
• specId

Structured output:

• specId
• tasks (text, done, line)

sdd_set_task_done

Purpose:

• toggle one checkbox line in a spec’s tasks.md

When to use:

• when a task is completed or reopened during a session

Rules:

• surgical edit of the single - [ ] / - [x] line, atomic write
• line comes from sdd_read_tasks

Input:

• projectRoot
• specId
• line
• done

Structured output:

• specId
• tasks

sdd_board_app

Purpose:

• show the visual SDD board inside the client as an MCP App (SEP-1865, official ext-apps extension)

When to use:

• when the user wants to see the board (cards, connections, gate semaphore, dependency warnings) without leaving the chat

Rules:

• read-only view; linked to the ui://sdd/board.html resource via _meta.ui.resourceUri (text/html;profile=mcp-app)
• hosts without MCP Apps support still get the full board + gate data as JSON text
• a closed gate is data for the view, never a tool error

Input:

• projectRoot

Structured output:

• projectRoot
• board (canvas + specs, same shape as sdd_board_read)
• gate (same shape as sdd_gate_summary)

Resource reference

Static resources

sdd-policy

• reads the current framework policy
• use when the AI needs the hard rules first

sdd-ai-start

• reads the fast AI onboarding guide
• use when the operator is starting from zero

sdd-easy-mcp-guide

• reads the friendly non-technical MCP guide
• use when the operator wants the easiest possible explanation first

sdd-quickstart

• reads the short quickstart guide
• use when the operator needs the shortest possible route

sdd-spec-template

• reads the base spec.md template
• use when the AI needs to understand the expected structure of a feature spec

Managed-workspace resource templates

These resource templates are for managed projects under ./www/<project-name>/.

sdd-project-index

• returns specs/INDEX.md
• expect the top-level snapshot of project specs

sdd-project-log

• returns bitacora/global/PROJECT_LOG.md
• expect the global project log

sdd-project-latest-handoff

• returns the latest file in bitacora/handoffs/
• expect the most recent handoff, if any

sdd-project-idea

• returns idea/IDEA_GENERAL.md
• expect the project intent and scope

sdd-spec-document

• returns a specific spec document by id and file name
• supported documents:
  • spec.md
  • plan.md
  • tasks.md
  • research.md
  • history.md

Prompt reference

start_new_sdd_project

• use when the user wants to start a new project from this framework
• expects the AI to create the SDD base first and defer implementation until the gate is met

easy_start_project

• use when the user wants a child-friendly guided project start
• expects the AI to explain the action, touched files, expected result, and next step

easy_create_spec

• use when the user says something like /create-spec payments
• expects the AI to create the spec package and explain the result in simple language

easy_show_structure

• use when the user feels lost and needs the folder map explained simply
• expects the AI to describe the project structure like a basic map

easy_validate_project

• use when the user wants validation and gate status in simple language
• expects the AI to translate warnings and errors into one clear next step

easy_show_next_step

• use when the user wants the next safe SDD action without jargon
• expects the AI to choose one exact next step

adapt_existing_project_to_sdd

• use when the user already has a project and wants to add SDD structure
• expects the AI to preserve current behavior and add traceability

close_sdd_session

• use when ending a session
• expects a summary with objective, changes, validation, risks, and next step

easy_close_session

• use when ending a session for a non-technical user
• expects the AI to summarize in simple language and leave one exact next step

Recommended user flow

flowchart LR
  A["Connect MCP"] --> B["Read policy + quickstart"]
  B --> C["Create SDD base"]
  C --> D["Create first spec"]
  D --> E["Validate"]
  E --> F["Check gate"]
  F --> G["Record consent"]
  G --> H["Implement"]
  H --> I["Write logs and handoff"]

1. Connect the MCP server.
2. Read sdd-policy and sdd-quickstart.
3. Create the SDD base with sdd_create_workspace or external bootstrap scripts.
4. Create the first spec with sdd_create_spec.
5. Validate with sdd_validate.
6. Before implementation, run sdd_check_gate.
7. If approved, record consent with sdd_record_user_consent.
8. Close the session with status, logs, and handoff tools as needed.

User expectation summary

The user should expect this MCP to:

• guide SDD work with structure, not guesswork
• create predictable files
• block implementation when documentation is not ready
• preserve traceability across sessions
• make AI clients behave more consistently across the same project