MCP SpecGen

MCP SpecGen is a Model Context Protocol (MCP) server that generates software specifications in Markdown format using the EARS (Easy Approach to Requirements Syntax) methodology for AI-powered software development. It enables AI assistants to create and manage comprehensive software specifications using three core documents: requirements.md, design.md, and tasks.md, all following structured EARS patterns.

🚀 Quick Start

No installation required! Configure in your MCP-compatible AI editor:

{
  "mcpServers": {
    "mcp-specgen": {
      "command": "npx",
      "args": ["@d0whc3r/mcp-specgen"]
    }
  }
}

Supported AI Editors:

• Claude Desktop
• Cursor
• Other MCP-compatible editors

Benefits of using npx:

• ✅ No installation required
• ✅ Always gets the latest version
• ✅ No global package conflicts
• ✅ Works immediately

🚀 Features

• EARS Methodology: Generate specifications using Easy Approach to Requirements Syntax
• Markdown Specification Generation: Create comprehensive software specifications in Markdown format using three core documents
• Document Generation: Generate requirements.md, design.md, and tasks.md documents with structured EARS patterns
• Task Management: Generate and manage implementation tasks
• AI Integration: Seamless integration with Claude Desktop, Cursor, and other AI editors
• Security: Secure file access with path validation and input sanitization
• Code Coverage: Comprehensive test coverage with Codecov integration
• Documentation: Comprehensive documentation hosted on GitHub Pages

📖 Documentation

📚 Full Documentation - Complete guides, architecture, and usage examples

⚙️ Configuration

For AI Editors

Add the following configuration to your MCP settings:

Claude Desktop (~/.config/claude/desktop-config.json):

{
  "mcpServers": {
    "mcp-specgen": {
      "command": "npx",
      "args": ["@d0whc3r/mcp-specgen"]
    }
  }
}

Cursor (Settings → Extensions → MCP):

{
  "mcpServers": {
    "mcp-specgen": {
      "command": "npx",
      "args": ["@d0whc3r/mcp-specgen"]
    }
  }
}

Other MCP-compatible editors: Use the same configuration pattern

Note: This package is designed to be used with npx and does not require global installation. The npx approach ensures you always get the latest version and avoids conflicts with other global packages.

🎯 Usage

1. Configure your MCP-compatible AI editor with the settings above

2. Start using the prompts:

   • Ask your AI assistant to "Generate requirements for a user registration system"
   • Use "Generate design from requirements" to create design documents
   • Request "Generate tasks from requirements" to create implementation tasks

📚 Available Prompts

Document Generation

• generate-requirements: Creates requirements.md documents using EARS methodology
• generate-design-from-requirements: Generates design.md documents using EARS patterns
• generate-tasks: Generates tasks.md documents using EARS methodology

Task Management

• execute-task: Executes development tasks
• list-pending-tasks: Shows pending tasks
• mark-task-completed: Marks tasks as completed

🎯 EARS Methodology

MCP SpecGen uses the EARS (Easy Approach to Requirements Syntax) methodology to generate clear, testable specifications:

• Ubiquitous: "The [system] shall [function]"
• Event-driven: "When [trigger], the [system] shall [function]"
• State-driven: "While [state], the [system] shall [function]"
• Unwanted behavior: "If [condition], then the [system] shall [function]"
• Optional: "Where [condition], the [system] shall [function]"

🔧 Development

Prerequisites

• Node.js 22.0.0 or higher
• npm

Setup (For Contributors)

# Clone the repository
git clone https://github.com/d0whc3r/mcp-specgen.git
cd mcp-specgen

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

Note: For end users, this package should be used with npx @d0whc3r/mcp-specgen - no installation required!

Available Scripts

• npm run build: Build the project
• npm run build:analyze: Build with bundle analysis (Codecov)
• npm test: Run tests
• npm run test:coverage: Run tests with coverage
• npm run lint: Run ESLint
• npm run lint:fix: Fix ESLint issues
• npm run format: Format code with Prettier
• npm run type-check: Run TypeScript type checking

📊 Bundle Analysis

This project uses @codecov/vite-plugin for bundle analysis and optimization insights. The plugin automatically:

• Analyzes bundle size and composition
• Provides optimization recommendations
• Tracks bundle changes over time
• Integrates with Codecov for detailed reporting

Bundle analysis runs automatically during CI/CD builds and can be triggered manually with npm run build:analyze.

📖 Documentation

• Architecture: Detailed system architecture and components
• Usage Guide: Comprehensive usage instructions and examples

🔒 Security

• File Path Validation: All file access is restricted to the current working directory
• Input Validation: Zod schemas validate all input parameters
• Error Handling: Graceful error handling prevents information leakage
• Template Sanitization: Templates are processed safely without code execution

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Model Context Protocol for the MCP specification
• Anthropic for Claude and the MCP ecosystem

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: docs/ directory