# Directory Structure
```
├── .gitignore
├── AGENTS.md
├── CLAUDE.md
├── package.json
├── pnpm-lock.yaml
├── README.md
├── src
│ ├── index.ts
│ ├── server.ts
│ ├── tools
│ │ ├── design_confirmed.ts
│ │ ├── design.ts
│ │ ├── execute.ts
│ │ ├── goal.ts
│ │ ├── requirements_confirmed.ts
│ │ ├── requirements.ts
│ │ ├── tasks_confirmed.ts
│ │ ├── tasks.ts
│ │ └── workflow.ts
│ └── utils
│ ├── template.ts
│ └── workflow.ts
├── templates
│ ├── ask-goal.md
│ ├── execute-task.md
│ ├── gen-design.md
│ ├── gen-requirement.md
│ └── gen-tasks.md
└── tsconfig.json
```
# Files
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
1 | # Dependencies
2 | node_modules/
3 | npm-debug.log*
4 | yarn-debug.log*
5 | yarn-error.log*
6 | pnpm-debug.log*
7 |
8 | # Build outputs
9 | dist/
10 | build/
11 | *.tsbuildinfo
12 |
13 | # TypeScript cache
14 | *.tsbuildinfo
15 |
16 | # Runtime data
17 | pids
18 | *.pid
19 | *.seed
20 | *.pid.lock
21 |
22 | # Coverage directory used by tools like istanbul
23 | coverage/
24 | *.lcov
25 |
26 | # nyc test coverage
27 | .nyc_output
28 |
29 | # Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
30 | .grunt
31 |
32 | # Bower dependency directory (https://bower.io/)
33 | bower_components
34 |
35 | # node-waf configuration
36 | .lock-wscript
37 |
38 | # Compiled binary addons (https://nodejs.org/api/addons.html)
39 | build/Release
40 |
41 | # Dependency directories
42 | jspm_packages/
43 |
44 | # Snowpack dependency directory (https://snowpack.dev/)
45 | web_modules/
46 |
47 | # TypeScript v1 declaration files
48 | typings/
49 |
50 | # Optional npm cache directory
51 | .npm
52 |
53 | # Optional eslint cache
54 | .eslintcache
55 |
56 | # Optional stylelint cache
57 | .stylelintcache
58 |
59 | # Microbundle cache
60 | .rpt2_cache/
61 | .rts2_cache_cjs/
62 | .rts2_cache_es/
63 | .rts2_cache_umd/
64 |
65 | # Optional REPL history
66 | .node_repl_history
67 |
68 | # Output of 'npm pack'
69 | *.tgz
70 |
71 | # Yarn Integrity file
72 | .yarn-integrity
73 |
74 | # dotenv environment variable files
75 | .env
76 | .env.development.local
77 | .env.test.local
78 | .env.production.local
79 | .env.local
80 |
81 | # parcel-bundler cache (https://parceljs.org/)
82 | .cache
83 | .parcel-cache
84 |
85 | # Next.js build output
86 | .next
87 | out
88 |
89 | # Nuxt.js build / generate output
90 | .nuxt
91 | dist
92 |
93 | # Gatsby files
94 | .cache/
95 | # Comment in the public line in if your project uses Gatsby and not Next.js
96 | # https://nextjs.org/blog/next-9-1#public-directory-support
97 | # public
98 |
99 | # vuepress build output
100 | .vuepress/dist
101 |
102 | # vuepress v2.x temp and cache directory
103 | .temp
104 | .cache
105 |
106 | # Serverless directories
107 | .serverless/
108 |
109 | # FuseBox cache
110 | .fusebox/
111 |
112 | # DynamoDB Local files
113 | .dynamodb/
114 |
115 | # TernJS port file
116 | .tern-port
117 |
118 | # Stores VSCode versions used for testing VSCode extensions
119 | .vscode-test
120 |
121 | # yarn v2
122 | .yarn/cache
123 | .yarn/unplugged
124 | .yarn/build-state.yml
125 | .yarn/install-state.gz
126 | .pnp.*
127 |
128 | # MacOS
129 | .DS_Store
130 | .AppleDouble
131 | .LSOverride
132 |
133 | # Icon must end with two \r
134 | Icon
135 |
136 | # Thumbnails
137 | ._*
138 |
139 | # Files that might appear in the root of a volume
140 | .DocumentRevisions-V100
141 | .fseventsd
142 | .Spotlight-V100
143 | .TemporaryItems
144 | .Trashes
145 | .VolumeIcon.icns
146 | .com.apple.timemachine.donotpresent
147 |
148 | # Directories potentially created on remote AFP share
149 | .AppleDB
150 | .AppleDesktop
151 | Network Trash Folder
152 | Temporary Items
153 | .apdisk
154 |
155 | # Windows
156 | Thumbs.db
157 | Thumbs.db:encryptable
158 | ehthumbs.db
159 | ehthumbs_vista.db
160 |
161 | # Dump file
162 | *.stackdump
163 |
164 | # Folder config file
165 | [Dd]esktop.ini
166 |
167 | # Recycle Bin used on file shares
168 | $RECYCLE.BIN/
169 |
170 | # Windows Installer files
171 | *.cab
172 | *.msi
173 | *.msix
174 | *.msm
175 | *.msp
176 |
177 | # Windows shortcuts
178 | *.lnk
179 |
180 | # Linux
181 | *~
182 |
183 | # temporary files which can be created if a process still has a handle open of a deleted file
184 | .fuse_hidden*
185 |
186 | # KDE directory preferences
187 | .directory
188 |
189 | # Linux trash folder which might appear on any partition or disk
190 | .Trash-*
191 |
192 | # .nfs files are created when an open file is removed but is still being accessed
193 | .nfs*
194 |
195 | # IDE and Editor files
196 | .vscode/
197 | .idea/
198 | *.swp
199 | *.swo
200 | *~
201 |
202 | # Cursor AI IDE
203 | .cursor/
204 |
205 | # History files (often created by various tools)
206 | .history/
207 |
208 | # Claude files
209 | .claude/
210 |
211 | # Smithery files
212 | .smithery/
213 |
214 | # Logs
215 | logs
216 | *.log
217 |
218 | # Runtime data
219 | pids
220 | *.pid
221 | *.seed
222 | *.pid.lock
223 |
224 | # Optional npm cache directory
225 | .npm
226 |
227 | # Optional REPL history
228 | .node_repl_history
229 |
230 | # Output of 'npm pack'
231 | *.tgz
232 |
233 | # Yarn Integrity file
234 | .yarn-integrity
235 |
236 | # MCP Server specific
237 | # Add any MCP-specific files that shouldn't be tracked
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
1 | # Spec-driven Development MCP Server
2 |
3 | [](https://smithery.ai/server/@kevinlin/spec-coding-mcp)
4 |
5 | An MCP server that brings AI-guided spec-driven development workflow to any AI-powered IDEs beyonnd Kiro. Transform your development process with structured, step-by-step guidance from idea to implementation.
6 |
7 | ## What is Spec-driven Development?
8 |
9 | Spec-driven development is a methodology that emphasizes creating detailed specifications before writing code. This approach helps ensure clear requirements, better design decisions, and more maintainable code. Our MCP server guides you through this process with AI assistance.
10 |
11 | ## Features
12 |
13 | - **Complete Development Workflow**: From goal collection to task execution
14 | - **AI-Powered Guidance**: Step-by-step instructions for each development phase
15 | - **Structured Documentation**: Generates organized specs in EARS format
16 | - **Template-Based**: Uses proven templates for requirements, design, and tasks
17 |
18 | ## Installation
19 |
20 | ### Installing via Smithery
21 |
22 | To install spec-coding-mcp for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@kevinlin/spec-coding-mcp):
23 |
24 | ```bash
25 | npx -y @smithery/cli install @kevinlin/spec-coding-mcp --client claude
26 | ```
27 |
28 | ### Using npx (Recommended)
29 |
30 | ```bash
31 | # Always get the latest version
32 | npx spec-coding-mcp@latest
33 |
34 | # Or simply (will also get latest)
35 | npx spec-coding-mcp
36 | ```
37 |
38 | ### Using npm
39 |
40 | ```bash
41 | npm install -g spec-coding-mcp
42 | spec-coding-mcp
43 | ```
44 |
45 | ## Usage
46 |
47 | ### With Cursor
48 |
49 | Add to your Cursor MCP settings:
50 |
51 | ```json
52 | {
53 | "mcpServers": {
54 | "spec-coding-mcp": {
55 | "command": "npx",
56 | "args": ["spec-coding-mcp@latest"],
57 | "env": {},
58 | "disabled": false
59 | }
60 | }
61 | }
62 | ```
63 |
64 | ### Available Tools
65 |
66 | 1. **spec_coding_workflow_start** - Start the development workflow
67 | 2. **spec_coding_goal_confirmed** - Confirm feature goals
68 | 3. **spec_coding_requirements_start** - Begin requirements gathering
69 | 4. **spec_coding_requirements_confirmed** - Confirm requirements completion
70 | 5. **spec_coding_design_start** - Start design documentation
71 | 6. **spec_coding_design_confirmed** - Confirm design completion
72 | 7. **spec_coding_tasks_start** - Begin task planning
73 | 8. **spec_coding_tasks_confirmed** - Confirm task planning completion
74 | 9. **spec_coding_execute_start** - Start task execution
75 |
76 | ## Workflow Stages & Example
77 |
78 | The spec-driven development process follows five distinct stages. Here's how it works with a real example - building a user authentication feature:
79 |
80 | ### 1. Goal Collection - Define What You Want to Build
81 |
82 | **Purpose**: Establish clear, specific objectives for your feature.
83 |
84 | **Example Interaction**:
85 | ```
86 | User: I want to build a user authentication feature
87 | Assistant: Let me start the spec-driven development workflow for you.
88 | [calls spec_coding_workflow_start]
89 |
90 | Let's define your feature goals:
91 |
92 | 1. What specific authentication methods do you want to support?
93 | 2. Do you need social login (Google, GitHub, etc.)?
94 | 3. What user roles and permissions are required?
95 |
96 | User: I need email/password login with JWT tokens, plus Google OAuth, and basic user/admin roles.
97 |
98 | Assistant: Perfect! Let me confirm:
99 | - Feature: User authentication system
100 | - Methods: Email/password + Google OAuth
101 | - Tokens: JWT-based
102 | - Roles: User and Admin
103 | - Feature name: "user-authentication"
104 |
105 | Is this correct?
106 | User: Yes, that's exactly what I need.
107 | [calls spec_coding_goal_confirmed with feature_name="user-authentication"]
108 | ```
109 |
110 | ### 2. Requirements Gathering - Create Detailed EARS-format Requirements
111 |
112 | **Purpose**: Transform your goals into specific, testable requirements using the EARS (Easy Approach to Requirements Syntax) format.
113 |
114 | **Example Interaction**:
115 | ```
116 | Assistant: Great! Now let's gather detailed requirements.
117 | [calls spec_coding_requirements_start]
118 |
119 | [Assistant generates detailed EARS-format requirements in docs/specs/user-authentication/requirements.md]
120 | - WHEN a user provides valid email/password THEN the system SHALL authenticate them
121 | - GIVEN a user wants Google OAuth WHEN they click "Sign in with Google" THEN the system SHALL redirect to Google
122 | - WHERE user roles are needed IF user is admin THEN they SHALL access admin features
123 |
124 | User: The requirements look comprehensive. Approved!
125 | [calls spec_coding_requirements_confirmed]
126 | ```
127 |
128 | ### 3. Design Documentation - Technical Architecture and Design
129 |
130 | **Purpose**: Create detailed technical specifications including architecture, component design, data models, and API specifications.
131 |
132 | **Example Interaction**:
133 | ```
134 | Assistant: Now let's create the technical design.
135 | [calls spec_coding_design_start]
136 |
137 | [Assistant creates detailed design document including:]
138 | - Database schema for users, sessions, oauth_tokens
139 | - Authentication middleware architecture
140 | - JWT token structure and validation flow
141 | - Google OAuth integration endpoints
142 | - Role-based access control implementation
143 |
144 | User: Design looks good, proceed!
145 | [calls spec_coding_design_confirmed]
146 | ```
147 |
148 | ### 4. Task Planning - Break Down into Executable Tasks
149 |
150 | **Purpose**: Decompose the feature into specific, prioritized development tasks with clear dependencies.
151 |
152 | **Example Interaction**:
153 | ```
154 | Assistant: Let's break this down into executable tasks.
155 | [calls spec_coding_tasks_start]
156 |
157 | [Assistant creates numbered task list:]
158 | 1. Set up database models (User, Session, OAuthToken)
159 | 2. Implement JWT token service
160 | 3. Create email/password authentication endpoints
161 | 4. Integrate Google OAuth flow
162 | 5. Build role-based middleware
163 | 6. Add frontend login/register forms
164 | 7. Write integration tests
165 |
166 | User: Task breakdown is perfect!
167 | [calls spec_coding_tasks_confirmed]
168 | ```
169 |
170 | ### 5. Task Execution - Implement the Code
171 |
172 | **Purpose**: Execute the planned tasks systematically, implementing the feature according to specifications.
173 |
174 | **Example Interaction**:
175 | ```
176 | Assistant: Time to implement! Let's start coding.
177 | [calls spec_coding_execute_start]
178 |
179 | [Assistant implements each task step by step:]
180 | - Creates User model with email, password_hash, role fields
181 | - Builds JWT service with sign/verify methods
182 | - Implements /auth/login and /auth/register endpoints
183 | - Integrates Google OAuth with Passport.js
184 | - Creates role-checking middleware
185 | - Builds React login/register components
186 | - Writes comprehensive test suite
187 | ```
188 |
189 | ## Generated Project Structure
190 |
191 | Throughout the workflow, the following documentation structure is created:
192 |
193 | ```
194 | docs/specs/{feature_name}/
195 | ├── requirements.md # EARS-format requirements
196 | ├── design.md # Technical architecture
197 | └── tasks.md # Implementation checklist
198 | ```
199 |
200 | ## Development
201 |
202 | ### Prerequisites
203 |
204 | Make sure you have Node.js 18+ installed.
205 |
206 | ### Setup
207 |
208 | ```bash
209 | # Install dependencies with pnpm (recommended)
210 | pnpm install
211 |
212 | # Or with npm
213 | npm install
214 | ```
215 |
216 | ### Running the Project
217 |
218 | ```bash
219 | # Development mode with pnpm
220 | pnpm dev
221 |
222 | # Or with npm
223 | npm run dev
224 |
225 | # Build with pnpm
226 | pnpm build
227 |
228 | # Or with npm
229 | npm run build
230 |
231 | # Start built version with pnpm
232 | pnpm start
233 |
234 | # Or with npm
235 | npm start
236 |
237 | # Test with pnpm (when available)
238 | pnpm test
239 |
240 | # Or with npm
241 | npm test
242 | ```
243 |
244 | ### Publishing
245 |
246 | To publish the package to npm:
247 |
248 | ```bash
249 | # Build the project
250 | pnpm build
251 |
252 | # Publish to npm (will automatically run prepublishOnly script)
253 | npm publish
254 | ```
255 |
256 | ## Contributing & License
257 |
258 | ### Contributing
259 | Contributions are welcome! Please feel free to submit a Pull Request.
260 |
261 | ### License
262 | MIT
263 |
264 | ### Attribution
265 | This project was inspired by and builds upon concepts from [vibedevtools](https://github.com/yinwm/vibedevtools) by [@yinwm](https://github.com/yinwm), a collection of development efficiency tools.
```
--------------------------------------------------------------------------------
/AGENTS.md:
--------------------------------------------------------------------------------
```markdown
1 | # Agent Development Guidelines
2 |
3 | ## Build & Test Commands
4 | - **Build**: `npm run build` - Compiles TypeScript to dist/
5 | - **Dev**: `npm run dev` - Runs with tsx for development
6 | - **Start**: `npm run start` - Runs compiled version from dist/
7 | - **Test**: `npx vitest` - Runs tests (vitest configured but no test scripts in package.json)
8 |
9 | ## Code Style & Conventions
10 | - **Language**: TypeScript with ES2022 target, ESNext modules
11 | - **Imports**: Use `.js` extensions for local imports (ES modules)
12 | - **Naming**: camelCase for functions/variables, snake_case for tool names
13 | - **Functions**: Export async functions, use descriptive names
14 | - **Types**: Use strict TypeScript, explicit types in function signatures
15 | - **Error Handling**: Use try/catch with descriptive error messages
16 | - **Logging**: Use `console.error()` with `[MCP]` prefix for debugging
17 | - **File Structure**: src/ for source, tools/ for MCP tools, utils/ for helpers
18 | - **Templates**: Store in templates/ directory, use template variables with `{variable}`
19 | - **Imports Style**: Group external imports first, then local imports with relative paths
20 |
21 | ## Architecture
22 | - **MCP Server**: Uses @modelcontextprotocol/sdk for tool definitions and handlers
23 | - **Tool Pattern**: Each tool in separate file with async function export
24 | - **Session Management**: Use nanoid for session IDs (12 char alphanumeric)
25 | - **Template System**: Read from templates/ with variable substitution
```
--------------------------------------------------------------------------------
/CLAUDE.md:
--------------------------------------------------------------------------------
```markdown
1 | # CLAUDE.md
2 |
3 | This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 |
5 | ## Development Commands
6 |
7 | ```bash
8 | # Development mode
9 | npm run dev
10 |
11 | # Build the project
12 | npm run build
13 |
14 | # Start built version
15 | npm start
16 |
17 | # Install dependencies (Node.js 18+ required)
18 | npm install
19 | ```
20 |
21 | ## Project Architecture
22 |
23 | This is an MCP (Model Context Protocol) server that implements a spec-driven development workflow. The architecture follows a tool-based approach where each workflow stage is implemented as a separate MCP tool.
24 |
25 | ### Core Components
26 |
27 | - **Entry Point** (`src/index.ts`): Starts the MCP server with stdio transport
28 | - **Server** (`src/server.ts`): Defines all 9 workflow tools and handles tool execution
29 | - **Workflow Tools** (`src/tools/`): Each file implements a specific workflow stage
30 | - **Utilities** (`src/utils/`): Shared workflow logic and templates
31 |
32 | ### Workflow Architecture
33 |
34 | The spec-driven development workflow consists of 5 sequential stages, each with specific tools:
35 |
36 | 1. **Goal Confirmation**: `spec_coding_workflow_start` → `spec_coding_goal_confirmed`
37 | 2. **Requirements Gathering**: `spec_coding_requirements_start` → `spec_coding_requirements_confirmed`
38 | 3. **Design Documentation**: `spec_coding_design_start` → `spec_coding_design_confirmed`
39 | 4. **Task Planning**: `spec_coding_tasks_start` → `spec_coding_tasks_confirmed`
40 | 5. **Task Execution**: `spec_coding_execute_start`
41 |
42 | Each stage generates documentation in `docs/specs/{feature_name}/` directory:
43 | - `requirements.md` (EARS format)
44 | - `design.md` (technical architecture)
45 | - `tasks.md` (implementation checklist)
46 |
47 | ### Tool Implementation Pattern
48 |
49 | All workflow tools follow a consistent pattern:
50 | - Accept `session_id` and `feature_name` parameters
51 | - Return structured text responses with guidance
52 | - Use templates from `src/utils/template.ts`
53 | - Track workflow state through step progression
54 |
55 | ### TypeScript Configuration
56 |
57 | - ES2022 target with ESNext modules
58 | - Strict mode enabled with comprehensive type checking
59 | - Output to `dist/` directory
60 | - Source maps and declarations generated
61 |
62 | ### Code Style Guidelines
63 |
64 | From `.cursor/rules/typescript.mdc`:
65 | - Prefer interfaces over types for object definitions
66 | - Use PascalCase for types, camelCase for variables
67 | - Explicit return types for public functions
68 | - Avoid JSDoc documentation
69 | - Use async/await over Promises
70 | - Implement proper error handling with custom error types
```
--------------------------------------------------------------------------------
/tsconfig.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "compilerOptions": {
3 | "target": "ES2022",
4 | "module": "ESNext",
5 | "moduleResolution": "node",
6 | "lib": ["ES2022"],
7 | "outDir": "./dist",
8 | "rootDir": "./src",
9 | "strict": true,
10 | "esModuleInterop": true,
11 | "skipLibCheck": true,
12 | "forceConsistentCasingInFileNames": true,
13 | "resolveJsonModule": true,
14 | "declaration": true,
15 | "declarationMap": true,
16 | "sourceMap": true,
17 | "allowSyntheticDefaultImports": true
18 | },
19 | "include": ["src/**/*"],
20 | "exclude": ["node_modules", "dist"]
21 | }
```
--------------------------------------------------------------------------------
/src/index.ts:
--------------------------------------------------------------------------------
```typescript
1 | #!/usr/bin/env node
2 | import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
3 | import { createServer } from './server.js';
4 |
5 | async function main() {
6 | console.error('[MCP] Starting spec-coding-mcp server...');
7 |
8 | const server = createServer();
9 | const transport = new StdioServerTransport();
10 |
11 | await server.connect(transport);
12 | console.error('[MCP] spec-coding-mcp server started successfully');
13 | }
14 |
15 | main().catch((error) => {
16 | console.error('[MCP] Fatal error:', error);
17 | process.exit(1);
18 | });
```
--------------------------------------------------------------------------------
/src/utils/template.ts:
--------------------------------------------------------------------------------
```typescript
1 | import { readFile } from 'fs/promises';
2 | import { join, dirname } from 'path';
3 | import { fileURLToPath } from 'url';
4 |
5 | const __dirname = dirname(fileURLToPath(import.meta.url));
6 |
7 | export async function readTemplate(
8 | templateName: string,
9 | variables: Record<string, string> = {}
10 | ): Promise<string> {
11 | // From src/utils go up two levels to the project root, then enter templates
12 | const templatePath = join(__dirname, '../../templates', templateName);
13 | console.error(`[MCP] Reading template: ${templatePath}`);
14 |
15 | let content = await readFile(templatePath, 'utf-8');
16 |
17 | // Replace variables
18 | Object.entries(variables).forEach(([key, value]) => {
19 | const regex = new RegExp(`\{${key}\}`, 'g');
20 | content = content.replace(regex, value);
21 | });
22 |
23 | return content;
24 | }
```
--------------------------------------------------------------------------------
/src/tools/design_confirmed.ts:
--------------------------------------------------------------------------------
```typescript
1 | export interface DesignConfirmedParams {
2 | session_id: string;
3 | feature_name: string;
4 | }
5 |
6 | export async function designConfirmed(
7 | params: DesignConfirmedParams
8 | ): Promise<string> {
9 | const { session_id, feature_name } = params;
10 | console.error(`[MCP] Design confirmed for feature: ${feature_name}`);
11 |
12 | return `# ✅ Design Document Completed
13 |
14 | ## Generated Design Document:
15 | 📄 "docs/specs/${feature_name}/design.md"
16 |
17 | The design document contains the complete technical architecture, component design, and implementation plan.
18 |
19 | ---
20 |
21 | ## Next Stage: Task Planning (4/5)
22 |
23 | ### Workflow Progress:
24 | - [x] 1. Goal Collection ✅
25 | - [x] 2. Requirements Gathering ✅
26 | - [x] 3. **Design Document** ✅
27 | - [ ] 4. **Task Planning** ← Next Stage
28 | - [ ] 5. Task Execution
29 |
30 | Now please call \`spec_coding_tasks_start\` to begin the task planning stage.
31 |
32 | **Session Information**:
33 | - Session ID: \`${session_id}\`
34 | - Feature Name: \`${feature_name}\`
35 | - Requirements: ✅ Completed
36 | - Design: ✅ Completed`;
37 | }
```
--------------------------------------------------------------------------------
/src/tools/goal.ts:
--------------------------------------------------------------------------------
```typescript
1 | export interface GoalConfirmedParams {
2 | session_id: string;
3 | feature_name: string;
4 | goal_summary: string;
5 | }
6 |
7 | export async function goalConfirmed(params: GoalConfirmedParams): Promise<string> {
8 | const { session_id, feature_name, goal_summary } = params;
9 | console.error(`[MCP] Goal confirmed for session ${session_id} with feature: ${feature_name}`);
10 |
11 | return `# ✅ Feature Goal Confirmed
12 |
13 | ## Confirmed Feature Goal:
14 | - **Feature Name**: \`${feature_name}\`
15 | - **Feature Description**: ${goal_summary}
16 | - **Project Directory**: \`docs/specs/${feature_name}/\`
17 |
18 | ---
19 |
20 | ## Next Stage: Requirements Gathering (2/5)
21 |
22 | ### Workflow Progress:
23 | - [x] 1. **Goal Collection** ✅
24 | - [ ] 2. **Requirements Gathering** ← Next Stage
25 | - [ ] 3. Design Documentation
26 | - [ ] 4. Task Planning
27 | - [ ] 5. Task Execution
28 |
29 | Now please call \`spec_coding_requirements_start\` to begin detailed requirements gathering.
30 |
31 | **Session Information**:
32 | - Session ID: \`${session_id}\`
33 | - Feature Name: \`${feature_name}\``;
34 | }
```
--------------------------------------------------------------------------------
/src/tools/requirements_confirmed.ts:
--------------------------------------------------------------------------------
```typescript
1 | export interface RequirementsConfirmedParams {
2 | session_id: string;
3 | feature_name: string;
4 | }
5 |
6 | export async function requirementsConfirmed(
7 | params: RequirementsConfirmedParams
8 | ): Promise<string> {
9 | const { session_id, feature_name } = params;
10 | console.error(`[MCP] Requirements confirmed for feature: ${feature_name}`);
11 |
12 | return `# ✅ Requirements Gathering Completed
13 |
14 | ## Generated Requirements Document:
15 | 📄 "docs/specs/${feature_name}/requirements.md"
16 |
17 | The requirements document contains complete user stories and EARS-format acceptance criteria.
18 |
19 | ---
20 |
21 | ## Next Stage: Design Document (3/5)
22 |
23 | ### Workflow Progress:
24 | - [x] 1. Goal Collection ✅
25 | - [x] 2. **Requirements Gathering** ✅
26 | - [ ] 3. **Design Document** ← Next Stage
27 | - [ ] 4. Task Planning
28 | - [ ] 5. Task Execution
29 |
30 | Now please call \`spec_coding_design_start\` to begin the technical design stage.
31 |
32 | **Session Information**:
33 | - Session ID: \`${session_id}\`
34 | - Feature Name: \`${feature_name}\`
35 | - Requirements: ✅ Completed`;
36 | }
```
--------------------------------------------------------------------------------
/src/tools/tasks_confirmed.ts:
--------------------------------------------------------------------------------
```typescript
1 | export interface TasksConfirmedParams {
2 | session_id: string;
3 | feature_name: string;
4 | }
5 |
6 | export async function tasksConfirmed(
7 | params: TasksConfirmedParams
8 | ): Promise<string> {
9 | const { session_id, feature_name } = params;
10 | console.error(`[MCP] Tasks confirmed for feature: ${feature_name}`);
11 |
12 | return `# ✅ Task Planning Completed
13 |
14 | ## Generated Tasks Document:
15 | 📄 "docs/specs/${feature_name}/tasks.md"
16 |
17 | The tasks document contains a detailed list of development tasks, each with clear descriptions, acceptance criteria, and execution order.
18 |
19 | ---
20 |
21 | ## Next Stage: Task Execution (5/5)
22 |
23 | ### Workflow Progress:
24 | - [x] 1. Goal Collection ✅
25 | - [x] 2. Requirements Gathering ✅
26 | - [x] 3. Design Document ✅
27 | - [x] 4. **Task Planning** ✅
28 | - [ ] 5. **Task Execution** ← Final Stage
29 |
30 | Now please call \`spec_coding_execute_start\` to begin the task execution stage.
31 |
32 | **Session Information**:
33 | - Session ID: \`${session_id}\`
34 | - Feature Name: \`${feature_name}\`
35 | - Requirements: ✅ Completed
36 | - Design: ✅ Completed
37 | - Tasks: ✅ Completed`;
38 | }
```
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "name": "spec-coding-mcp",
3 | "version": "1.0.1",
4 | "description": "MCP server for AI-powered IDE to follow spec-driven development",
5 | "main": "dist/index.js",
6 | "type": "module",
7 | "bin": {
8 | "spec-coding-mcp": "dist/index.js"
9 | },
10 | "scripts": {
11 | "build": "tsc",
12 | "dev": "tsx src/index.ts",
13 | "start": "node dist/index.js",
14 | "prepublishOnly": "npm run build"
15 | },
16 | "keywords": [
17 | "mcp",
18 | "spec-driven",
19 | "workflow",
20 | "ai",
21 | "development",
22 | "requirements",
23 | "design",
24 | "tasks"
25 | ],
26 | "author": "kevinlin",
27 | "license": "MIT",
28 | "repository": {
29 | "type": "git",
30 | "url": "git+https://github.com/kevinlin/spec-coding-mcp.git"
31 | },
32 | "homepage": "https://github.com/kevinlin/spec-coding-mcp#readme",
33 | "bugs": {
34 | "url": "https://github.com/kevinlin/spec-coding-mcp/issues"
35 | },
36 | "dependencies": {
37 | "@modelcontextprotocol/sdk": "^1.17.0",
38 | "nanoid": "^5.1.5"
39 | },
40 | "devDependencies": {
41 | "@types/node": "^22.13.10",
42 | "tsx": "^4.20.3",
43 | "typescript": "^5.8.3",
44 | "vitest": "^3.2.4"
45 | },
46 | "engines": {
47 | "node": ">=18.0.0"
48 | }
49 | }
50 |
```
--------------------------------------------------------------------------------
/src/tools/design.ts:
--------------------------------------------------------------------------------
```typescript
1 | import { readTemplate } from '../utils/template.js';
2 |
3 | export interface DesignStartParams {
4 | session_id: string;
5 | feature_name: string;
6 | }
7 |
8 | export async function designStart(
9 | params: DesignStartParams
10 | ): Promise<string> {
11 | const { session_id, feature_name } = params;
12 | console.error(`[MCP] Starting design phase for feature: ${feature_name}`);
13 |
14 | // Use gen-design.md template
15 | const template = await readTemplate('gen-design.md', {
16 | feature_name,
17 | session_id
18 | });
19 |
20 | return `# 📝 Design Documentation Stage (3/5)
21 |
22 | ## Feature: ${feature_name}
23 |
24 | ### Workflow Progress:
25 | - [x] 1. Goal Collection ✅
26 | - [x] 2. Requirements Gathering ✅
27 | - [x] 3. **Design Documentation** ← Current Stage
28 | - [ ] 4. Task Planning
29 | - [ ] 5. Task Execution
30 |
31 | ---
32 |
33 | ${template}
34 |
35 | ---
36 |
37 | **Important**:
38 | - Please create design document according to the above guidelines
39 | - **Only when you explicitly confirm the design is complete can you call** \`spec_coding_design_confirmed\` tool
40 | - **Never** call the next stage tool before the user **explicitly confirms the design**
41 |
42 | **Session Information**:
43 | - Session ID: \`${session_id}\`
44 | - Feature Name: \`${feature_name}\`
45 | - Requirements: \`docs/specs/${feature_name}/requirements.md\``;
46 | }
```
--------------------------------------------------------------------------------
/src/tools/requirements.ts:
--------------------------------------------------------------------------------
```typescript
1 | import { readTemplate } from '../utils/template.js';
2 |
3 | export interface RequirementsStartParams {
4 | session_id: string;
5 | feature_name: string;
6 | }
7 |
8 | export async function requirementsStart(
9 | params: RequirementsStartParams
10 | ): Promise<string> {
11 | const { session_id, feature_name } = params;
12 | console.error(`[MCP] Starting requirements collection for feature: ${feature_name}`);
13 |
14 | // Use gen-requirement.md template
15 | const template = await readTemplate('gen-requirement.md', {
16 | feature_name,
17 | session_id
18 | });
19 |
20 | return `# 📋 Requirements Gathering Stage (2/5)
21 |
22 | ## Feature: ${feature_name}
23 |
24 | ### Workflow Progress:
25 | - [x] 1. Goal Collection ✅
26 | - [x] 2. **Requirements Gathering** ← Current Stage
27 | - [ ] 3. Design Documentation
28 | - [ ] 4. Task Planning
29 | - [ ] 5. Task Execution
30 |
31 | ---
32 |
33 | ${template}
34 |
35 | ---
36 |
37 | **Important**:
38 | - Please generate requirements document according to the above guidelines
39 | - **Only when you explicitly confirm the requirements are complete can you call** \`spec_coding_requirements_confirmed\` tool
40 | - **Never** call the next stage tool before the user **explicitly confirms the requirements**
41 |
42 | **Session Information**:
43 | - Session ID: \`${session_id}\`
44 | - Feature Name: \`${feature_name}\``;
45 | }
```
--------------------------------------------------------------------------------
/src/tools/execute.ts:
--------------------------------------------------------------------------------
```typescript
1 | import { readTemplate } from '../utils/template.js';
2 |
3 | export interface ExecuteStartParams {
4 | session_id: string;
5 | feature_name: string;
6 | task_id?: string;
7 | }
8 |
9 | export async function executeStart(
10 | params: ExecuteStartParams
11 | ): Promise<string> {
12 | const { session_id, feature_name, task_id = 'next_uncompleted' } = params;
13 | console.error(`[MCP] Starting execution for feature: ${feature_name}, task: ${task_id}`);
14 |
15 | // 使用 execute-task.md 模板
16 | const template = await readTemplate('execute-task.md', {
17 | feature_name,
18 | session_id,
19 | task_id
20 | });
21 |
22 | return `# ⚙️ Task Execution Stage (5/5)
23 |
24 | ## Feature: ${feature_name}
25 |
26 | Congratulations! Now entering the final execution stage. Based on the completed requirements, design, and task planning, let's start executing development tasks one by one.
27 |
28 | ### Workflow Progress:
29 | - [x] 1. Goal Collection ✅
30 | - [x] 2. Requirements Gathering ✅
31 | - [x] 3. Design Documentation ✅
32 | - [x] 4. Task Planning ✅
33 | - [x] 5. **Task Execution** ← Current Stage
34 |
35 | ---
36 |
37 | ${template}
38 |
39 | ---
40 |
41 | **Session Information**:
42 | - Session ID: \`${session_id}\`
43 | - Feature Name: \`${feature_name}\`
44 | - Current Task: \`${task_id}\`
45 | - All Documents: ✅ Completed
46 |
47 | Now please start executing the development tasks!`;
48 | }
```
--------------------------------------------------------------------------------
/templates/ask-goal.md:
--------------------------------------------------------------------------------
```markdown
1 | ### 0. Goal Confirmation
2 |
3 | First, establish a clear understanding of the development goal through iterative dialogue with the user. This is the foundation for all subsequent work.
4 |
5 | Don't proceed to any other workflow stage until the goal is completely clear and confirmed by the user.
6 |
7 | **Constraints:**
8 |
9 | - The model MUST engage in thorough dialogue with the user to understand their development goals
10 | - The model MUST ask clarifying questions about:
11 | - What problem the feature solves
12 | - Who will use the feature
13 | - What the expected outcome should be
14 | - Any technical constraints or requirements
15 | - The model MUST NOT proceed to the next stage until the user explicitly confirms the goal
16 | - The model MUST summarize the understood goal and wait for user confirmation
17 | - The model MUST generate a suitable feature_name based on the confirmed goal (e.g., 'user-authentication', 'payment-integration')
18 | - The model SHOULD ask targeted questions to clarify ambiguous aspects
19 | - The model SHOULD suggest refinements if the goal seems too broad or unclear
20 | - The model MUST use the exact phrase "Goal confirmation complete" when ready to proceed
21 | - The model MUST NOT call any other tools until the user has explicitly approved the goal summary
```
--------------------------------------------------------------------------------
/src/tools/tasks.ts:
--------------------------------------------------------------------------------
```typescript
1 | import { readTemplate } from '../utils/template.js';
2 |
3 | export interface TasksStartParams {
4 | session_id: string;
5 | feature_name: string;
6 | }
7 |
8 | export async function tasksStart(
9 | params: TasksStartParams
10 | ): Promise<string> {
11 | const { session_id, feature_name } = params;
12 | console.error(`[MCP] Starting tasks planning for feature: ${feature_name}`);
13 |
14 | // Use gen-tasks.md template
15 | const template = await readTemplate('gen-tasks.md', {
16 | feature_name,
17 | session_id
18 | });
19 |
20 | return `# 📋 Task Planning Stage (4/5)
21 |
22 | ## Feature: ${feature_name}
23 |
24 | ### Workflow Progress:
25 | - [x] 1. Goal Collection ✅
26 | - [x] 2. Requirements Gathering ✅
27 | - [x] 3. Design Documentation ✅
28 | - [x] 4. **Task Planning** ← Current Stage
29 | - [ ] 5. Task Execution
30 |
31 | ---
32 |
33 | ${template}
34 |
35 | ---
36 |
37 | **Important**:
38 | - Please create task list according to the above guidelines
39 | - **Only when you explicitly confirm the task planning is complete can you call** \`spec_coding_tasks_confirmed\` tool
40 | - **Never** call the next stage tool before the user **explicitly confirms the tasks**
41 |
42 | **Session Information**:
43 | - Session ID: \`${session_id}\`
44 | - Feature Name: \`${feature_name}\`
45 | - Requirements: \`docs/specs/${feature_name}/requirements.md\`
46 | - Design: \`docs/specs/${feature_name}/design.md\``;
47 | }
```
--------------------------------------------------------------------------------
/src/tools/workflow.ts:
--------------------------------------------------------------------------------
```typescript
1 | import { customAlphabet } from 'nanoid';
2 | import { readTemplate } from '../utils/template.js';
3 |
4 | const generateSessionId = customAlphabet('1234567890abcdefghijklmnopqrstuvwxyz', 12);
5 |
6 | export async function workflowStart(): Promise<string> {
7 | const session_id = generateSessionId();
8 | console.error(`[MCP] Starting workflow with session_id: ${session_id}`);
9 |
10 | // Use ask-goal.md template
11 | const template = await readTemplate('ask-goal.md', {
12 | session_id
13 | });
14 |
15 | return `# 🚀 Spec-driven Development Workflow Started
16 |
17 | ## Current Stage: Goal Collection (1/5)
18 |
19 | Welcome to the Spec-driven development workflow! I'll help you complete the entire development process from requirements to code.
20 |
21 | ### Workflow Overview:
22 | - [ ] 1. **Goal Collection** ← Current Stage
23 | - [ ] 2. Requirements Gathering
24 | - [ ] 3. Design Documentation
25 | - [ ] 4. Task Planning
26 | - [ ] 5. Task Execution
27 |
28 | ---
29 |
30 | ${template}
31 |
32 | ---
33 |
34 | **Session Information**:
35 | - Session ID: \`${session_id}\`
36 |
37 | **Important**:
38 | - Please discuss the feature goals with me thoroughly until the goals are completely clear
39 | - **Only when you explicitly confirm the goals can you call** \`spec_coding_goal_confirmed\` tool
40 | - **Never** call the next stage tool before the user **explicitly confirms the goals**`;
41 | }
```
--------------------------------------------------------------------------------
/templates/execute-task.md:
--------------------------------------------------------------------------------
```markdown
1 | First you will
2 |
3 | requirements: 'docs/specs/{feature_name}/requirements.md'
4 |
5 | design: 'docs/specs/{feature_name}/design.md'
6 |
7 | tasks: 'docs/specs/{feature_name}/tasks.md'
8 |
9 | Find first unimplemented task in the task list in the docs/specs/{feature_name}/tasks.md file.
10 |
11 | Follow these instructions for user requests related to spec tasks. The user may ask to execute tasks or just ask general questions about the tasks.
12 |
13 | ## Executing Instructions
14 | - Before executing any tasks, ALWAYS ensure you have read the specs requirements.md, design.md and tasks.md files. Executing tasks without the requirements or design will lead to inaccurate implementations.
15 | - Look at the task details in the task list
16 | - If the requested task has sub-tasks, always start with the sub tasks
17 | - Only focus on ONE task at a time. Do not implement functionality for other tasks.
18 | - Verify your implementation against any requirements specified in the task or its details.
19 | - Once you complete the requested task, stop and let the user review. DO NOT just proceed to the next task in the list
20 | - If the user doesn't specify which task they want to work on, look at the task list for that spec and make a recommendation
21 | on the next task to execute.
22 |
23 | Remember, it is VERY IMPORTANT that you only execute one task at a time. Once you finish a task, stop. Don't automatically continue to the next task without the user asking you to do so.
24 |
25 | ## Task Questions
26 | The user may ask questions about tasks without wanting to execute them. Don't always start executing tasks in cases like this.
27 |
28 | For example, the user may want to know what the next task is for a particular feature. In this case, just provide the information and don't start any tasks.
29 |
30 | When you are done with a task, modify the docs/specs/{feature_name}/tasks.md file to mark the task as implemented.
```
--------------------------------------------------------------------------------
/templates/gen-requirement.md:
--------------------------------------------------------------------------------
```markdown
1 | ### 1. Requirement Gathering
2 |
3 | First, generate an initial set of requirements in EARS format based on the feature idea, then iterate with the user to refine them until they are complete and accurate.
4 |
5 | Don't focus on code exploration in this phase. Instead, just focus on writing requirements which will later be turned into
6 | a design.
7 |
8 | **Constraints:**
9 |
10 | - The model MUST create a 'docs/specs/{feature_name}/requirements.md' file if it doesn't already exist
11 | - The model MUST generate an initial version of the requirements document based on the user's rough idea WITHOUT asking sequential questions first
12 | - The model MUST format the initial requirements.md document with:
13 | - A clear introduction section that summarizes the feature
14 | - A hierarchical numbered list of requirements where each contains:
15 | - A user story in the format "As a [role], I want [feature], so that [benefit]"
16 | - A numbered list of acceptance criteria in EARS format (Easy Approach to Requirements Syntax)
17 | - Example format:
18 | [includes example format here]
19 | - The model SHOULD consider edge cases, user experience, technical constraints, and success criteria in the initial requirements
20 | - After updating the requirement document, the model MUST ask the user "Do the requirements look good? If so, we can move on to the design." using the 'userInput' tool.
21 | - The 'userInput' tool MUST be used with the exact string 'spec-requirements-review' as the reason
22 | - The model MUST make modifications to the requirements document if the user requests changes or does not explicitly approve
23 | - The model MUST ask for explicit approval after every iteration of edits to the requirements document
24 | - The model MUST NOT proceed to the design document until receiving clear approval (such as "yes", "approved", "looks good", etc.)
25 | - The model MUST continue the feedback-revision cycle until explicit approval is received
26 | - The model SHOULD suggest specific areas where the requirements might need clarification or expansion
27 | - The model MAY ask targeted questions about specific aspects of the requirements that need clarification
28 | - The model MAY suggest options when the user is unsure about a particular aspect
29 | - The model MUST proceed to the design phase after the user accepts the requirements
```
--------------------------------------------------------------------------------
/src/utils/workflow.ts:
--------------------------------------------------------------------------------
```typescript
1 | // Workflow step definitions
2 | export interface WorkflowStep {
3 | step_number: number;
4 | name: string;
5 | description: string;
6 | tool: string;
7 | deliverable: string;
8 | }
9 |
10 | export interface WorkflowOverview {
11 | total_steps: number;
12 | current_step: string; // Change to step name
13 | current_step_number: number; // Keep number for progress display
14 | steps: WorkflowStep[];
15 | }
16 |
17 | // Step name constants
18 | export const STEP_NAMES = {
19 | GOAL_CONFIRMATION: 'Goal Confirmation',
20 | REQUIREMENTS: 'Requirements Gathering',
21 | DESIGN: 'Design Documentation',
22 | TASKS: 'Task Planning',
23 | EXECUTION: 'Task Execution'
24 | } as const;
25 |
26 | // Workflow step constants
27 | export const WORKFLOW_STEPS: WorkflowStep[] = [
28 | {
29 | step_number: 1,
30 | name: STEP_NAMES.GOAL_CONFIRMATION,
31 | description: 'Clarify the feature development goal through conversation',
32 | tool: 'spec_coding_workflow_start → spec_coding_goal_confirmed',
33 | deliverable: 'Clear feature goal and feature_name'
34 | },
35 | {
36 | step_number: 2,
37 | name: STEP_NAMES.REQUIREMENTS,
38 | description: 'Generate requirements document in EARS format',
39 | tool: 'spec_coding_requirements_start → spec_coding_requirements_confirmed',
40 | deliverable: 'docs/specs/{feature_name}/requirements.md'
41 | },
42 | {
43 | step_number: 3,
44 | name: STEP_NAMES.DESIGN,
45 | description: 'Create technical design document based on requirements',
46 | tool: 'spec_coding_design_start → spec_coding_design_confirmed',
47 | deliverable: 'docs/specs/{feature_name}/design.md'
48 | },
49 | {
50 | step_number: 4,
51 | name: STEP_NAMES.TASKS,
52 | description: 'Generate executable development task list',
53 | tool: 'spec_coding_tasks_start → spec_coding_tasks_confirmed',
54 | deliverable: 'docs/specs/{feature_name}/tasks.md'
55 | },
56 | {
57 | step_number: 5,
58 | name: STEP_NAMES.EXECUTION,
59 | description: 'Execute development tasks one by one',
60 | tool: 'spec_coding_execute_start',
61 | deliverable: 'Actual code implementation'
62 | }
63 | ];
64 |
65 | // Get workflow overview helper function
66 | export function getWorkflowOverview(currentStepName: string): WorkflowOverview {
67 | const currentStep = WORKFLOW_STEPS.find(step => step.name === currentStepName);
68 | const stepNumber = currentStep?.step_number || 1;
69 |
70 | return {
71 | total_steps: WORKFLOW_STEPS.length,
72 | current_step: currentStepName,
73 | current_step_number: stepNumber,
74 | steps: WORKFLOW_STEPS
75 | };
76 | }
```
--------------------------------------------------------------------------------
/templates/gen-design.md:
--------------------------------------------------------------------------------
```markdown
1 | ### 2. Create Feature Design Document
2 |
3 | After the user approves the Requirements, you should develop a comprehensive design document based on the feature requirements, conducting necessary research during the design process.
4 | The design document should be based on the requirements document, so ensure it exists first.
5 |
6 | **Constraints:**
7 |
8 | - The model MUST create a 'docs/specs/{feature_name}/design.md' file if it doesn't already exist
9 | - The model MUST identify areas where research is needed based on the feature requirements
10 | - The model MUST conduct research and build up context in the conversation thread
11 | - The model SHOULD NOT create separate research files, but instead use the research as context for the design and implementation plan
12 | - The model MUST summarize key findings that will inform the feature design
13 | - The model SHOULD cite sources and include relevant links in the conversation
14 | - The model MUST create a detailed design document at 'docs/specs/{feature_name}/design.md'
15 | - The model MUST incorporate research findings directly into the design process
16 | - The model MUST include the following sections in the design document:
17 | - Overview
18 | - Architecture
19 | - Components and Interfaces
20 | - Data Models
21 | - Error Handling
22 | - Testing Strategy
23 | - The model SHOULD include diagrams or visual representations when appropriate (use Mermaid for diagrams if applicable)
24 | - The model MUST ensure the design addresses all feature requirements identified during the clarification process
25 | - The model SHOULD highlight design decisions and their rationales
26 | - The model MAY ask the user for input on specific technical decisions during the design process
27 | - After updating the design document, the model MUST ask the user "Does the design look good? If so, we can move on to the implementation plan." using the 'userInput' tool.
28 | - The 'userInput' tool MUST be used with the exact string 'spec-design-review' as the reason
29 | - The model MUST make modifications to the design document if the user requests changes or does not explicitly approve
30 | - The model MUST ask for explicit approval after every iteration of edits to the design document
31 | - The model MUST NOT proceed to the implementation plan until receiving clear approval (such as "yes", "approved", "looks good", etc.)
32 | - The model MUST continue the feedback-revision cycle until explicit approval is received
33 | - The model MUST incorporate all user feedback into the design document before proceeding
34 | - The model MUST offer to return to feature requirements clarification if gaps are identified during design
```
--------------------------------------------------------------------------------
/templates/gen-tasks.md:
--------------------------------------------------------------------------------
```markdown
1 | # Specification Implementation Plan Prompt
2 |
3 | **Workflow Stage:** Implementation Planning
4 |
5 | ```
6 | ### 3. Create Task List
7 |
8 | After the user approves the Design, create an actionable implementation plan with a checklist of coding tasks based on the requirements and design.
9 | The tasks document should be based on the design document, so ensure it exists first.
10 |
11 | requirements: 'docs/specs/{feature_name}/requirements.md'
12 |
13 | design: 'docs/specs/{feature_name}/design.md'
14 |
15 | **Constraints:**
16 |
17 | - The model MUST create a 'docs/specs/{feature_name}/tasks.md' file if it doesn't already exist
18 | - The model MUST return to the design step if the user indicates any changes are needed to the design
19 | - The model MUST return to the requirement step if the user indicates that we need additional requirements
20 | - The model MUST create an implementation plan at 'docs/specs/{feature_name}/tasks.md'
21 | - The model MUST use the following specific instructions when creating the implementation plan:
22 | ```
23 | Convert the feature design into a series of prompts for a code-generation LLM that will implement each step in a test-driven manner. Prioritize best practices, incremental progress, and early testing, ensuring no big jumps in complexity at any stage. Make sure that each prompt builds on the previous prompts, and ends with wiring things together. There should be no hanging or orphaned code that isn't integrated into a previous step. Focus ONLY on tasks that involve writing, modifying, or testing code.
24 | ```
25 | - The model MUST format the implementation plan as a numbered checkbox list with a maximum of two levels of hierarchy:
26 | - Top-level items (like epics) should be used only when needed
27 | - Sub-tasks should be numbered with decimal notation (e.g., 1.1, 1.2, 2.1)
28 | - Each item must be a checkbox
29 | - Simple structure is preferred
30 | - The model MUST ensure each task item includes:
31 | - A clear objective as the task description that involves writing, modifying, or testing code
32 | - Additional information as sub-bullets under the task
33 | - Specific references to requirements from the requirements document (referencing granular sub-requirements, not just user stories)
34 | - The model MUST ensure that the implementation plan is a series of discrete, manageable coding steps
35 | - The model MUST ensure each task references specific requirements from the requirement document
36 | - The model MUST NOT include excessive implementation details that are already covered in the design document
37 | - The model MUST assume that all context documents (feature requirements, design) will be available during implementation
38 | - The model MUST ensure each step builds incrementally on previous steps
39 | - The model SHOULD prioritize test-driven development where appropriate
40 | - The model MUST ensure the plan covers all aspects of the design that can be implemented through code
41 | - The model SHOULD sequence steps to validate core functionality early through code
42 | - The model MUST ensure that all requirements are covered by the implementation tasks
43 | - The model MUST offer to return to previous steps (requirements or design) if gaps are identified during implementation planning
44 | - The model MUST ONLY include tasks that can be performed by a coding agent (writing code, creating tests, etc.)
45 | - The model MUST NOT include tasks related to user testing, deployment, performance metrics gathering, or other non-coding activities
46 | - The model MUST focus on code implementation tasks that can be executed within the development environment
47 | - The model MUST ensure each task is actionable by a coding agent by following these guidelines:
48 | - Tasks should involve writing, modifying, or testing specific code components
49 | - Tasks should specify what files or components need to be created or modified
50 | - Tasks should be concrete enough that a coding agent can execute them without additional clarification
51 | - Tasks should focus on implementation details rather than high-level concepts
52 | - Tasks should be scoped to specific coding activities (e.g., "Implement X function" rather than "Support X feature")
53 | - The model MUST explicitly avoid including the following types of non-coding tasks in the implementation plan:
54 | - User acceptance testing or user feedback gathering
55 | - Deployment to production or staging environments
56 | - Performance metrics gathering or analysis
57 | - Running the application to test end to end flows. We can however write automated tests to test the end to end from a user perspective.
58 | - User training or documentation creation
59 | - Business process changes or organizational changes
60 | - Marketing or communication activities
61 | - Any task that cannot be completed through writing, modifying, or testing code
62 | - After updating the tasks document, the model MUST ask the user "Do the tasks look good?" using the 'userInput' tool.
63 | - The 'userInput' tool MUST be used with the exact string 'spec-tasks-review' as the reason
64 | - The model MUST make modifications to the tasks document if the user requests changes or does not explicitly approve.
65 | - The model MUST ask for explicit approval after every iteration of edits to the tasks document.
66 | - The model MUST NOT consider the workflow complete until receiving clear approval (such as "yes", "approved", "looks good", etc.).
67 | - The model MUST continue the feedback-revision cycle until explicit approval is received.
68 | - The model MUST stop once the task document has been approved.
69 |
70 | **This workflow is ONLY for creating design and planning artifacts. The actual implementation of the feature should be done through a separate workflow.**
71 |
72 | - The model MUST NOT attempt to implement the feature as part of this workflow
73 | - The model MUST clearly communicate to the user that this workflow is complete once the design and planning artifacts are created
74 | - The model MUST inform the user that they can begin executing tasks by opening the tasks.md file, and clicking "Start task" next to task items.
75 | ```
```
--------------------------------------------------------------------------------
/src/server.ts:
--------------------------------------------------------------------------------
```typescript
1 | import { Server } from '@modelcontextprotocol/sdk/server/index.js';
2 | import {
3 | CallToolRequestSchema,
4 | ListToolsRequestSchema,
5 | } from '@modelcontextprotocol/sdk/types.js';
6 | import { workflowStart } from './tools/workflow.js';
7 | import { goalConfirmed } from './tools/goal.js';
8 | import { requirementsStart } from './tools/requirements.js';
9 | import { requirementsConfirmed } from './tools/requirements_confirmed.js';
10 | import { designStart } from './tools/design.js';
11 | import { designConfirmed } from './tools/design_confirmed.js';
12 | import { tasksStart } from './tools/tasks.js';
13 | import { tasksConfirmed } from './tools/tasks_confirmed.js';
14 | import { executeStart } from './tools/execute.js';
15 |
16 | export function createServer() {
17 | const server = new Server(
18 | {
19 | name: 'spec-coding-mcp',
20 | version: '1.0.0'
21 | },
22 | {
23 | capabilities: { tools: {} }
24 | }
25 | );
26 |
27 | // Tool definitions
28 | const tools = [
29 | {
30 | name: 'spec_coding_workflow_start',
31 | description: 'Start the specs workflow and begin the goal collection phase',
32 | inputSchema: {
33 | type: 'object',
34 | properties: {},
35 | required: []
36 | }
37 | },
38 | {
39 | name: 'spec_coding_goal_confirmed',
40 | description: 'Confirm the completion of the feature goal, set the feature_name, and proceed to the requirements collection phase',
41 | inputSchema: {
42 | type: 'object',
43 | properties: {
44 | session_id: {
45 | type: 'string',
46 | description: 'Session identifier'
47 | },
48 | feature_name: {
49 | type: 'string',
50 | description: 'Feature name generated based on the goal (e.g., user-auth)'
51 | },
52 | goal_summary: {
53 | type: 'string',
54 | description: 'Brief description of the feature goal'
55 | }
56 | },
57 | required: ['session_id', 'feature_name', 'goal_summary']
58 | }
59 | },
60 | {
61 | name: 'spec_coding_requirements_start',
62 | description: 'Start the requirements collection phase and provide guidance for requirements gathering',
63 | inputSchema: {
64 | type: 'object',
65 | properties: {
66 | session_id: {
67 | type: 'string',
68 | description: 'Session identifier'
69 | },
70 | feature_name: {
71 | type: 'string',
72 | description: 'Feature name'
73 | }
74 | },
75 | required: ['session_id', 'feature_name']
76 | }
77 | },
78 | {
79 | name: 'spec_coding_requirements_confirmed',
80 | description: 'Confirm the completion of requirements collection and proceed to the design phase',
81 | inputSchema: {
82 | type: 'object',
83 | properties: {
84 | session_id: {
85 | type: 'string',
86 | description: 'Session identifier'
87 | },
88 | feature_name: {
89 | type: 'string',
90 | description: 'Feature name'
91 | }
92 | },
93 | required: ['session_id', 'feature_name']
94 | }
95 | },
96 | {
97 | name: 'spec_coding_design_start',
98 | description: 'Start the design documentation phase and provide guidance for creating design documents',
99 | inputSchema: {
100 | type: 'object',
101 | properties: {
102 | session_id: {
103 | type: 'string',
104 | description: 'Session identifier'
105 | },
106 | feature_name: {
107 | type: 'string',
108 | description: 'Feature name'
109 | }
110 | },
111 | required: ['session_id', 'feature_name']
112 | }
113 | },
114 | {
115 | name: 'spec_coding_design_confirmed',
116 | description: 'Confirm the completion of the design document and proceed to the task planning phase',
117 | inputSchema: {
118 | type: 'object',
119 | properties: {
120 | session_id: {
121 | type: 'string',
122 | description: 'Session identifier'
123 | },
124 | feature_name: {
125 | type: 'string',
126 | description: 'Feature name'
127 | }
128 | },
129 | required: ['session_id', 'feature_name']
130 | }
131 | },
132 | {
133 | name: 'spec_coding_tasks_start',
134 | description: 'Start the task planning phase and provide guidance for creating the task list',
135 | inputSchema: {
136 | type: 'object',
137 | properties: {
138 | session_id: {
139 | type: 'string',
140 | description: 'Session identifier'
141 | },
142 | feature_name: {
143 | type: 'string',
144 | description: 'Feature name'
145 | }
146 | },
147 | required: ['session_id', 'feature_name']
148 | }
149 | },
150 | {
151 | name: 'spec_coding_tasks_confirmed',
152 | description: 'Confirm the completion of task planning and proceed to the execution phase',
153 | inputSchema: {
154 | type: 'object',
155 | properties: {
156 | session_id: {
157 | type: 'string',
158 | description: 'Session identifier'
159 | },
160 | feature_name: {
161 | type: 'string',
162 | description: 'Feature name'
163 | }
164 | },
165 | required: ['session_id', 'feature_name']
166 | }
167 | },
168 | {
169 | name: 'spec_coding_execute_start',
170 | description: 'Start the task execution phase and provide guidance for task execution',
171 | inputSchema: {
172 | type: 'object',
173 | properties: {
174 | session_id: {
175 | type: 'string',
176 | description: 'Session identifier'
177 | },
178 | feature_name: {
179 | type: 'string',
180 | description: 'Feature name'
181 | },
182 | task_id: {
183 | type: 'string',
184 | description: 'Optional: Specify the task ID to execute; if not specified, the next unfinished task will be executed'
185 | }
186 | },
187 | required: ['session_id', 'feature_name']
188 | }
189 | }
190 | ];
191 |
192 | // Register the handler for listing tools
193 | server.setRequestHandler(ListToolsRequestSchema, async () => {
194 | console.error('[MCP] Handling list tools request');
195 | return { tools };
196 | });
197 |
198 | // Register the handler for tool calls
199 | server.setRequestHandler(CallToolRequestSchema, async (request) => {
200 | const { name, arguments: args } = request.params;
201 | console.error(`[MCP] Handling tool call: ${name}`, args);
202 |
203 | try {
204 | let result: any;
205 |
206 | switch (name) {
207 | case 'spec_coding_workflow_start':
208 | result = await workflowStart();
209 | break;
210 |
211 | case 'spec_coding_goal_confirmed':
212 | result = await goalConfirmed(args as any);
213 | break;
214 |
215 | case 'spec_coding_requirements_start':
216 | result = await requirementsStart(args as any);
217 | break;
218 |
219 | case 'spec_coding_requirements_confirmed':
220 | result = await requirementsConfirmed(args as any);
221 | break;
222 |
223 | case 'spec_coding_design_start':
224 | result = await designStart(args as any);
225 | break;
226 |
227 | case 'spec_coding_design_confirmed':
228 | result = await designConfirmed(args as any);
229 | break;
230 |
231 | case 'spec_coding_tasks_start':
232 | result = await tasksStart(args as any);
233 | break;
234 |
235 | case 'spec_coding_tasks_confirmed':
236 | result = await tasksConfirmed(args as any);
237 | break;
238 |
239 | case 'spec_coding_execute_start':
240 | result = await executeStart(args as any);
241 | break;
242 |
243 | default:
244 | throw new Error(`Unknown tool: ${name}`);
245 | }
246 |
247 | console.error(`[MCP] Tool ${name} completed successfully`);
248 |
249 | return {
250 | content: [{
251 | type: 'text',
252 | text: result
253 | }]
254 | };
255 | } catch (error: any) {
256 | console.error(`[MCP] Tool ${name} failed:`, error);
257 | return {
258 | content: [{
259 | type: 'text',
260 | text: `Error: ${error.message}`
261 | }],
262 | isError: true
263 | };
264 | }
265 | });
266 |
267 | return server;
268 | }
```