Guide

Getting started

MCP-first frontend spec workflow — use Cursor, Claude, or any MCP client. CLI is optional.

Prerequisites

  • Node.js 20+
  • Flutter, Next.js, or React Native project
  • An MCP-capable IDE (Cursor, Claude Desktop, Windsurf, Cline, Continue, …)
  • Optional CLI AI: GEMINI_API_KEY (free tier) or Ollama — only if you use spec commands without MCP

1. Install & connect MCP (recommended)

One command in your app project (not the spec-copilot repo):

terminal 
cd your-flutter-app
npx -y @specdrive/mcp setup --stack flutter

This creates .specdrive/, writes .specdrive/mcp.json, and updates .cursor/mcp.json when present.

Ran npx -y @specdrive/mcp and it just waits?

That means it is installed. MCP servers use stdio — they wait for your IDE to connect. You do not run MCP manually in daily use; your IDE starts it from mcp.json.

Reload MCP in your IDE

  • Cursor / Windsurf: Settings → MCP → Reload
  • Claude Desktop: paste config from spec setup mcp output into claude_desktop_config.json
  • Other clients: use .specdrive/mcp.json — same npx -y @specdrive/mcp + project cwd

Test in chat: call MCP tool search_specs — should return [] or your specs, not NOT_INITIALIZED.

2. Create a spec via MCP (Kiro-style)

SpecDrive MCP scans your repo and returns generation bundles. Your host AI writes the markdown. You approve every gate — never auto-approve.

YOUR JOURNEY 
create_spec { "title": "Product Review Screen", "ticket": "OPTIONAL-123" }
  → shows YOUR JOURNEY card

1. brief.md → STOP → you approve
2. requirements.md → STOP → approve
3. generate_gap_analysis → write → STOP → approve
4. generate_design_hld → write → STOP → approve
5. generate_design_lld → write → STOP → approve
6. generate_tasks → write → STOP → approve   ← last human gate
7. get_next_task → implement → complete_task
   (Design2Code only if user wants Figma on a UI task)
8. review_code

Each tool response includes nextSteps and a phase cheat sheet. Edit .specdrive/steering/* so gap/HLD/LLD target your real package paths.

3. UI tasks + Figma (optional)

On get_next_task, UI tasks go to Cursor/Claude by default. Figma is optional:

  • Skip (default) → Cursor/Claude implements screens from HLD/LLD + steering
  • Provide Figma token → Design2Code can scaffold UI first, then host AI finishes
  • State, BLoC, navigation, validation, tests always stay with host AI

See MCP Figma setup.

4. CLI (optional)

Use CLI when you want SpecDrive to call a free LLM (Gemini/Groq/Ollama) without MCP:

terminal 
export GEMINI_API_KEY="your-key"
spec init --stack flutter
spec create "Product Review Screen"
spec approve requirements --spec product-review-screen
spec gap-analysis --spec product-review-screen
# … same gated pipeline as MCP

Every CLI command prints suggested next steps. See CLI reference for MCP equivalents.

Next steps