sdd-mcp-server 1.1.21 → 1.2.0

package/README.md

@@ -6,17 +6,16 @@
 
 A Model Context Protocol (MCP) server implementing Spec-Driven Development (SDD) workflows for AI-agent CLIs and IDEs like Claude Code, Cursor, and others.
 
-> **✅ v1.1.12 Update**: Fixed MCP server connection issues with Claude Code. Health check failures have been resolved with optimized startup performance.
+> **✅ v1.2.0 Update**: Complete kiro workflow alignment with empty project support. SDD tools now bootstrap from project descriptions without requiring existing files.
 
 ## 🚀 Quick Start
 
-### Option 1: Install with npx (Recommended)
+### Option 1: Install Globally (Recommended)
 ```bash
-# Run directly without installation
-npx sdd-mcp-server@latest
+# Install globally for reliable Claude Code integration
+npm install -g sdd-mcp-server@latest
 
-# Or install globally
-npm install -g sdd-mcp-server
+# Start the server
 sdd-mcp-server
 ```
 
@@ -58,14 +57,17 @@ docker-compose up -d
 ### Claude Code
 Add to your MCP settings using the command line:
 ```bash
+# First, install globally
+npm install -g sdd-mcp-server@latest
+
 # Add to local MCP configuration (recommended)
-claude mcp add sdd "npx -y sdd-mcp-server@latest" -s local
+claude mcp add sdd "sdd-mcp-server" -s local
 
 # Verify connection
 claude mcp list
 # Should show: sdd: ✓ Connected
 
-# For faster startup during development:
+# For development (faster startup):
 git clone https://github.com/yi-john-huang/sdd-mcp.git
 cd sdd-mcp
 claude mcp add sdd "$(pwd)/local-mcp-server.js" -s local
@@ -76,8 +78,8 @@ Manual configuration in `~/.claude.json`:
 {
   "mcpServers": {
     "sdd": {
-      "command": "npx",
-      "args": ["-y", "sdd-mcp-server@latest"],
+      "command": "sdd-mcp-server",
+      "args": [],
       "env": {}
     }
   }
@@ -109,46 +111,57 @@ Once connected to your AI client, you can use these MCP tools:
 | Tool | Description | Usage |
 |------|-------------|--------|
 | `sdd-init` | Initialize new SDD project | Creates .kiro directory structure |
-| `sdd-requirements` | Generate requirements doc | Creates requirements.md from project analysis |
-| `sdd-design` | Create design specifications | Generates design.md with architecture |
-| `sdd-tasks` | Generate task breakdown | Creates tasks.md with implementation plan |
+| `sdd-requirements` | Generate context-aware requirements | Analyzes package.json and structure to create EARS-formatted requirements |
+| `sdd-design` | Create project-specific design | Generates architecture docs based on actual tech stack and dependencies |
+| `sdd-tasks` | Generate implementation breakdown | Creates tasks derived from real project structure and technology choices |
 | `sdd-implement` | Implementation guidelines | Provides implementation steering |
 | `sdd-status` | Check workflow progress | Shows current phase and approvals |
 | `sdd-approve` | Approve workflow phases | Mark phases as approved for progression |
 | `sdd-quality-check` | Code quality analysis | Linus-style 5-layer code review |
 | `sdd-context-load` | Load project context | Restore project memory and state |
 | `sdd-template-render` | Render templates | Generate files from templates |
+| `sdd-steering` | Create/update steering docs | Analyzes project to generate product.md, tech.md, structure.md with real content |
+| `sdd-steering-custom` | Create custom steering docs | Add specialized guidance documents |
+| `sdd-validate-design` | Design quality validation | Interactive GO/NO-GO design review |
+| `sdd-validate-gap` | Implementation gap analysis | Analyze requirements vs codebase |
+| `sdd-spec-impl` | Execute tasks with TDD | Kent Beck's Red-Green-Refactor methodology |
 
 ## 💡 Basic Workflow
 
-1. **Initialize Project**
+1. **Initialize Project & Steering**
    ```
    Use sdd-init to create a new SDD project
+   Use sdd-steering to generate core steering documents
    ```
 
 2. **Generate Requirements**
    ```
-   Use sdd-requirements to analyze and document requirements
+   Use sdd-requirements to analyze package.json and create context-aware requirements
+   Use sdd-validate-gap to analyze implementation feasibility
    ```
 
 3. **Create Design**
    ```
-   Use sdd-design to generate technical architecture
+   Use sdd-design to generate architecture based on actual dependencies
+   Use sdd-validate-design for GO/NO-GO design review
    ```
 
 4. **Plan Tasks**
    ```
-   Use sdd-tasks to break down implementation work
+   Use sdd-tasks to create implementation breakdown from real project structure
    ```
 
-5. **Implement**
+5. **Implement with TDD**
    ```
-   Use sdd-implement for implementation guidance
+   Use sdd-spec-impl to execute tasks with TDD methodology
+   Use sdd-quality-check for code review and analysis
    ```
 
-6. **Quality Check**
+6. **Monitor & Manage**
    ```
-   Use sdd-quality-check for code review and analysis
+   Use sdd-status to check workflow progress
+   Use sdd-approve to approve workflow phases
+   Use sdd-context-load to restore project memory
    ```
 
 ## ⚙️ Configuration
@@ -168,16 +181,19 @@ export HOOK_TIMEOUT=10000
 
 ### Claude Code Integration Example
 ```bash
+# Install globally first
+npm install -g sdd-mcp-server@latest
+
 # Add to Claude Code with environment variables
-claude mcp add sdd "npx -y sdd-mcp-server@latest"
+claude mcp add sdd "sdd-mcp-server"
 
 # Manual configuration in ~/.mcp.json:
 {
   "servers": {
     "sdd": {
       "type": "stdio", 
-      "command": "npx",
-      "args": ["-y", "sdd-mcp-server@latest"],
+      "command": "sdd-mcp-server",
+      "args": [],
       "env": {
         "LOG_LEVEL": "info",
         "DEFAULT_LANG": "en"
@@ -190,9 +206,12 @@ claude mcp add sdd "npx -y sdd-mcp-server@latest"
 ## 🏗️ Key Features
 
 - **5-Phase SDD Workflow**: INIT → REQUIREMENTS → DESIGN → TASKS → IMPLEMENTATION
+- **Context-Aware Generation**: Analyzes package.json, dependencies, and project structure for real content
+- **EARS-Formatted Requirements**: Generate acceptance criteria based on actual npm scripts and dependencies
+- **Architecture Analysis**: Technology stack detection and pattern recognition from real codebase
 - **Quality Enforcement**: Linus-style 5-layer code review system
 - **Multi-Language Support**: 10 languages with cultural adaptation
-- **Template Engine**: Handlebars-based file generation
+- **Template Engine**: Handlebars-based file generation with project-specific data
 - **Plugin System**: Extensible architecture for custom workflows
 - **MCP Protocol**: Full compatibility with AI-agent CLIs and IDEs
 
@@ -245,20 +264,35 @@ npm cache clean --force
 npm install -g sdd-mcp-server
 ```
 
+**Issue: "Connection fails with npx"**
+
+⚠️ **Known Issue**: npx execution may have timing issues with Claude Code health checks.
+
+**Solution**: Use global installation instead:
+```bash
+# Don't use: npx -y sdd-mcp-server@latest
+# Instead, install globally:
+npm install -g sdd-mcp-server@latest
+claude mcp add sdd "sdd-mcp-server" -s local
+```
+
 **Issue: "MCP server not responding or Failed to connect"**
 
-*Fixed in v1.1.12*: The connection issues have been resolved with optimized startup performance.
+*Fixed in v1.1.21*: Use global installation instead of npx for reliable connections.
 
 ```bash
+# Install globally first
+npm install -g sdd-mcp-server@latest
+
 # Test server directly
-echo '{"jsonrpc": "2.0", "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}, "id": 1}' | npx -y sdd-mcp-server@latest
+echo '{"jsonrpc": "2.0", "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}, "id": 1}' | sdd-mcp-server
 
 # Check Claude MCP status
 claude mcp list
 
 # Re-add server to Claude MCP (forces refresh)
 claude mcp remove sdd -s local
-claude mcp add sdd "npx -y sdd-mcp-server@latest" -s local
+claude mcp add sdd "sdd-mcp-server" -s local
 
 # Alternative: Use local development version for faster startup
 git clone https://github.com/yi-john-huang/sdd-mcp.git
@@ -297,11 +331,14 @@ For detailed documentation on:
 
 **Ready to get started?**
 ```bash
+# Install globally first
+npm install -g sdd-mcp-server@latest
+
 # For Claude Code users:
-claude mcp add sdd "npx -y sdd-mcp-server@latest"
+claude mcp add sdd "sdd-mcp-server"
 
 # For direct usage:
-npx sdd-mcp-server@latest
+sdd-mcp-server
 ```
 
 Built for the AI development community 🤖✨

package/dist/adapters/cli/SDDToolAdapter.d.ts

@@ -3,6 +3,8 @@ import { ProjectService } from '../../application/services/ProjectService.js';
 import { WorkflowService } from '../../application/services/WorkflowService.js';
 import { TemplateService } from '../../application/services/TemplateService.js';
 import { QualityService } from '../../application/services/QualityService.js';
+import { SteeringDocumentService } from '../../application/services/SteeringDocumentService.js';
+import { CodebaseAnalysisService } from '../../application/services/CodebaseAnalysisService.js';
 import { LoggerPort } from '../../domain/ports.js';
 export interface SDDToolHandler {
     name: string;
@@ -14,8 +16,10 @@ export declare class SDDToolAdapter {
     private readonly workflowService;
     private readonly templateService;
     private readonly qualityService;
+    private readonly steeringService;
+    private readonly codebaseAnalysisService;
     private readonly logger;
-    constructor(projectService: ProjectService, workflowService: WorkflowService, templateService: TemplateService, qualityService: QualityService, logger: LoggerPort);
+    constructor(projectService: ProjectService, workflowService: WorkflowService, templateService: TemplateService, qualityService: QualityService, steeringService: SteeringDocumentService, codebaseAnalysisService: CodebaseAnalysisService, logger: LoggerPort);
     getSDDTools(): SDDToolHandler[];
     private handleProjectInit;
     private handleProjectStatus;
@@ -23,4 +27,21 @@ export declare class SDDToolAdapter {
     private handleDesign;
     private handleTasks;
     private handleQualityCheck;
+    private handleSteering;
+    private handleSteeringCustom;
+    private generateProductSteering;
+    private generateTechSteering;
+    private generateStructureSteering;
+    private extractFeatures;
+    private generateTargetUseCase;
+    private generateValueProposition;
+    private generateTargetUsers;
+    private generateTechStack;
+    private generateDependencyList;
+    private generateArchitecturePatterns;
+    private generateQualityStandards;
+    private generateDirectoryStructure;
+    private generateNamingConventions;
+    private generateModuleOrganization;
+    private generateWorkflow;
 }