Sdd Mcp

io.github.juanklagos由 GitHub 帳號 juanklagos 發布v2.8.0更新於 Oct 24, 2026

Spec-Driven Development workflow: specs, plans, gates, status and logbook tools. Bilingual EN/ES.

已驗證STDIO僅桌面效率與工作流開發者工具

概覽

AI 產生的概覽

本機 MCP 伺服器，讓助理執行規格驅動開發流程：建立規格、檢查核准閘門並寫入專案日誌。

可以做什麼
  • 在專案的 specs 目錄中建立與修訂編號規格包（spec、plan、tasks、history）
  • 執行 SDD 閘門與政策檢查，並在實作前記錄使用者的同意
  • 將決策與工作階段紀錄寫入 bitacora 日誌
  • 回報目前狀態與下一步，並提供唯讀的儀表板檢視
  • 為專案設定用戶端連線並升級框架檔案
適用情境
當你希望 AI 助理在真實專案上遵循「先寫規格再寫程式」的紀律時使用：在書面規格與一致的計畫獲得核准前不寫程式，並把決策與工作階段歷史保存在檔案中而非聊天紀錄裡。
執行需求
透過 npx 從 npm 套件 @juanklagos/sdd-mcp 在本機執行（需要 Node.js）。需要一個含 specs/ 或 spec/ 附屬目錄的目標專案，由 SDD_PROJECT_ROOT 指定（預設為目前工作目錄）；SDD_WORKSPACES_ROOT 決定新工作區的建立位置。未宣告任何驗證機制。
安裝前請注意
伺服器會寫入你的專案：規格包、日誌條目、同意紀錄，以及升級時的框架檔案。connect 指令會修改偵測到的 AI 用戶端設定檔，建議先以其 dry-run 選項查看。選用的桌面應用程式未經數位簽章，首次啟動會出現系統警告。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Sdd Mcp，將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only，透過 STDIO。 STDIO 服務會啟動本機處理程序，因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

[Spec-Driven Development Template]

🌱 Spec-Driven Development Template

Learn Spec-Driven Development, then use it on real projects.
One rule: no code until you approve a written spec. A script checks that rule every time you run it, and prints exactly what it looked at.

🇺🇸 English · 🇪🇸 Español

[Version] [License] [Latest release]

[Documentation site] [Interactive course] [SDD Validate on GitHub Marketplace] [Open in GitHub Codespaces]

Non-technical start · Quickstart · AI agent start · Commands · Community

What is this?

Spec-Driven Development (SDD) means writing and approving a clear specification before any code exists. What you decided ends up in a file, instead of buried in a chat you will close and never find again. By 2026 it is how most people build software with AI agents.

This repo does double duty.

It is a school: a bilingual (EN/ES) path that starts from zero, with guides, an interactive course and a tutor you can talk to. You do not need to know how to program to get through it.

It is also a toolkit for real work: scripts that check the rule, instruction files your AI assistant reads, a connector so your AI tool can run the workflow itself (MCP, the Model Context Protocol), and a single spec/ folder you add to a project that already has code — without moving any of it.

The step-by-step commands come from GitHub Spec Kit. This repo adds the guides, the checks and the templates on top of them.

The flow in action — create a spec, validate, pass the gate (regenerated on every release):

[SDD flow demo: create a spec, validate the structure, pass the gate]

What changes in practice: decisions stop living in chat history and move into specs/. The gate stays closed until spec.md and plan.md exist, agree, and you record your consent — a script checks that, not somebody's memory. A new teammate or a new agent lands in a folder layout they already recognize. And bitacora/ keeps the session log, so six months later you can still find out why something was done the way it was.

Want the industry map? Read SDD in 2026: state of the art and how this template compares.

Choose your door

  • Non-technical (founder, PM, curious): START_HERE_NON_TECH.md — a guided start with no jargon in it.
  • Developer: QUICKSTART.md — the commands to scaffold and validate, about five minutes.
  • AI agent, or you pasting into one: AI_START_HERE.md — operating rules plus copy/paste prompts for each level.

Then pick your learning level. Every guide on the docs site carries its level badge:

[!TIP] If you would rather learn by doing, take the interactive course (GitHub Skills format): 4 steps, ~35 min, auto-graded by Actions. Your exam is the real SDD gate.

Start in 30 seconds

Copy/paste this prompt into your AI assistant (Claude, Cursor, Copilot, Gemini...):

text
Using https://github.com/juanklagos/spec-driven-development-template, guide me step by step with SDD for my project.My project is: [describe your project in plain language].If my project is new, initialize from this template and GitHub Spec Kit as the base workflow.If it already exists, adapt it without breaking current behavior.No code before approved spec and consistent plan.

Built-in commands for your AI agent

If you use Claude Code, this repo ships slash commands out of the box. Start with /sdd:help:

CommandWhat it does
/sdd:helpTells you what stage you are in and the single next step
/sdd:newGuided start: idea → first spec ready for approval
/sdd:specCreate or refine a spec bundle with EARS criteria
/sdd:gateRuns the gate — approval, plan consistency, consent — and records yours
/sdd:decisionOne decision, written down in bitacora/decisiones/: what, why, what was rejected, when to revisit
/sdd:closeValidates and closes the session with the output contract
/sdd:tutorA conversational SDD course by levels, graded by the real validation scripts

Install in any project as a plugin (no cloning):

text
/plugin marketplace add juanklagos/spec-driven-development-template/plugin install sdd@sdd-template

The golden rule

[!IMPORTANT] No code before an approved spec.md and a consistent plan.md. A script enforces this, and implementation starts only once your consent is on record.

bash
./scripts/check-sdd-policy.sh .   # multi-agent policy files are aligned./scripts/check-sdd-gate.sh .     # spec approved + plan consistent + consent recorded./scripts/confirm-user-consent.sh --spec 001-<slug> "User approved scope X"

(In sidecar projects the same scripts live under ./spec/scripts/.)

Enforce it in CI too. This repo doubles as a GitHub Action, listed on the GitHub Marketplace:

yaml
- uses: juanklagos/[email protected]  with:    path: "."      # project root (sidecar or standalone auto-detected)    strict: "true"

Reference files: sdd.policy.yaml · INSTRUCTIONS.md · AGENT_OPERATING_SYSTEM.md

How it works

mermaid
flowchart LR  A["💡 Idea in plain language"] --> B["📋 spec.md approved"]  B --> C["🗺️ plan.md consistent"]  C --> D["✅ tasks.md prioritized"]  D --> E["🚦 Gate + explicit consent"]  E --> F["⚙️ Implementation"]  F --> G["🔍 Validation + logbook"]

Every feature gets a numbered spec bundle, and every session leaves a trace in bitacora/ (the logbook):

  1. spec.md — what and why (approved by you)
  2. plan.md — how (consistent with the spec)
  3. tasks.md — concrete steps
  4. history.md — how it evolved

Full walkthrough example: examples/002-mcp-end-to-end

Apply it to a real project

Fastest start (no clone needed):

bash
npx @juanklagos/create-sdd-project@latest my-app

It asks a few questions and scaffolds the recommended spec/ sidecar, or a full workspace, from the latest template.

Three ways to use the template, from lightest to heaviest:

ModeWhenCommand
Compact spec/ sidecar ⭐Real or existing project: SDD artifacts in ./spec/, code stays in your project root./scripts/install-spec-sidecar.sh /path/to/project --profile=recommended
Internal workspace www/The runnable project should live inside this template repo./scripts/create-www-project.sh my-project codex
Full standalone copyYou explicitly want the whole framework as your workspace./scripts/init-project.sh /path/to/project --profile=full

[!TIP] The professional default is the compact spec/ sidecar and nothing else. Never copy the full framework into a real codebase unless you actually want standalone mode.

Everyday commands (sidecar mode shown; the same scripts exist at root in standalone mode)
ActionCommand
New spec./spec/scripts/new-spec.sh "my-feature" "Owner"
Validate structure./spec/scripts/validate-sdd.sh . --strict
Policy check./spec/scripts/check-sdd-policy.sh .
SDD gate./spec/scripts/check-sdd-gate.sh .
Status dashboard./spec/scripts/generate-status.sh

Folder anatomy and layout details: project organization map

mermaid
flowchart TD  A["Your project root (code)"] --> B["spec/"]  B --> C["idea/"]  B --> D["specs/ (numbered bundles)"]  B --> E["bitacora/ (logbook)"]  B --> F["scripts/ (gate + validation)"]
Connect via MCP (optional, advanced)

If your AI tool supports MCP (the Model Context Protocol), it can run this workflow itself: create specs, check the gate, write the logbook. One command sets it up, in your project's folder:

bash
npx @juanklagos/sdd-mcp@latest connect

It finds the clients you have — Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI, opencode — and writes the configuration into each one's own file. It merges into what you already have and never overwrites it. Add --dry-run first to see what it would touch. Then restart your client.

  • Prefer doing it by hand? Point your client at npm: {"command": "npx", "args": ["-y", "@juanklagos/sdd-mcp@latest"]}. The @latest matters — without it, npx can serve an old cached version with fewer tools.
  • Working on this template itself? npm install && npm run build && npm run mcp:start runs the server from source.
  • SDD Builder (visual, drag-and-drop): build once with npm run builder:build, then SDD_PROJECT_ROOT=/path/to/your/project npm run mcp:http:start and open http://127.0.0.1:3334/builder — compose your specs as connected cards, where every card is a real specs/NNN/ bundle on disk. Inside this template repository the builder is blocked by design (no target-project work in the template root), so always point SDD_PROJECT_ROOT at a real workspace. See the visual guide.
  • Already using SDD and want the latest? npx @juanklagos/sdd-mcp@latest upgrade --project-root . --dry-run shows what would change before changing it: framework files get repaired, yours are never written without --apply. See the upgrade guide.
  • SDD Desk (the same builder, as a desktop app): download it for macOS, Windows or Linux. Nothing else has to be installed: the app includes everything it needs. While it is open, your AI assistant can connect to it — copy the address the app shows you and paste it into your assistant's settings. One caveat: the app is not digitally signed, so the first time you open it macOS or Windows shows a scary-looking warning and asks you to allow it. If you would rather not deal with that, run npx @juanklagos/sdd-mcp@latest --http instead. Same tool, in your browser, no warning.
  • Visual dashboard: point the server at a project — SDD_PROJECT_ROOT=./www/my-project npm run mcp:http:start — then open http://127.0.0.1:3334/dashboard for a page you can look at but not edit: whether the gate is open, a few headline numbers, how far each spec has got, and which specs are waiting on another one. In your language, with nothing to compile. This folder — the template itself — is not a project, so if you run it here it will tell you so.
  • Easiest explanation first: Easy MCP Guide
  • Client configs: .mcp.json (Claude Code) · Cursor · Codex
  • Complete reference: docs/en/41-complete-mcp-reference.md

Note: GitMCP (free, remote) helps an AI read this public repo; the local sdd-mcp runs the real guided workflow. They complement each other: GitMCP guide.

Documentation

Browse online: the documentation site has every guide with search, an EN/ES language picker and level badges.

If you only read three:

  1. Workflow — the SDD flow step by step
  2. Structure — what each folder is for
  3. SDD in 2026: state of the art — the industry map and where this template stands

Everything else: the full documentation index organizes all 53 guides (EN/ES) by topic.

Community

Legal & authorship

  • License: MIT — use it anywhere, including commercially and inside a company, free and without asking. Keep the copyright notice. Legal guide
  • What you write with the templates is yours: TEMPLATE-OUTPUT.md
  • Publishing a release / Publicar una versión: RELEASING.md
  • Changelog: CHANGELOG.md · Latest release: v2.8.0
  • Copyright (c) 2026 Juan Carlos Alvarez Lagos (AUTHORS.md)

If this saves you one bad sprint, a ⭐ helps other people find it.

🌱 No code before approved spec and consistent plan.

⬆️ Back to top

來源：README.md，提交 939649d

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包，因此其工具未知。

版本歷史

1
  1. v2.8.0最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手；SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭，或保持端點能夠回應探測，以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list，或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分