wassden

A powerful MCP-based Spec-Driven Development (SDD) toolkit that transforms any LLM into a comprehensive development agent with structured specification generation and validation capabilities.

"Spec-first development made intelligent and systematic"

🎯 Core Philosophy

wassden is designed as an intelligent prompt orchestrator for SDD workflows. It doesn't generate documents itself—instead, it:

🧠 Provides expert-crafted prompts that guide AI agents to create high-quality specifications
🤝 Enables seamless agent collaboration through standardized SDD workflows
✅ Validates generated documents to ensure consistency and completeness
📋 Maintains project coherence across the entire development lifecycle

The tool acts as your SDD methodology expert, ensuring AI agents follow best practices while you focus on the creative aspects of development.

✨ Key Features

🎯 Spec-Driven Development: Complete Requirements → Design → Tasks → Code workflow
🔄 Intelligent Validation: Automated quality checks with actionable feedback and 100% traceability enforcement
📊 Traceability Management: Complete REQ↔DESIGN↔TASK + TR↔TEST-SCENARIO mapping with mandatory 100% coverage validation
🚀 Progressive Prompting: Step-by-step guidance for high-quality deliverables
🛠️ MCP Integration: Seamless integration with Claude Code and other MCP clients via FastMCP
🧪 Robust Testing: 118 comprehensive tests with automated MCP integration and consistently fast response times (<0.01ms avg)

🎪 Demonstrations

Demo videos showcasing the development workflow will be added to this section soon.
Detailed usage examples will be provided in the videos—please stay tuned!

🚀 Quick Start

Installation

# Direct install from GitHub (recommended)
uvx --from git+https://github.com/tokusumi/wassden-mcp wassden

# Or development installation
git clone https://github.com/tokusumi/wassden-mcp
cd wassden-py
uv pip install -e .

MCP Integration

Transport Options

wassden supports multiple transport protocols for maximum compatibility:

stdio (default): Standard input/output for Claude Code
sse: Server-Sent Events for HTTP-based communication
streamable-http: Streamable HTTP for web-based clients

Claude Code Setup (Recommended)

Install uv (if not already installed)
# On macOS and Linux curl -LsSf https://astral.sh/uv/install.sh | sh # On Windows powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" # Via pip pip install uv
Add to Claude Code settingsEdit ~/.claude/settings.json:Using stdio transport (recommended for Claude Code)
{ "mcpServers": { "wassden": { "command": "uvx", "args": [ "--from", "git+https://github.com/tokusumi/wassden-mcp", "wassden", "start-mcp-server", "--transport", "stdio" ], "env": {} } } }
Restart Claude Code
- Complete application restart required
- wassden tools will appear in tool palette
Verify connection
# Manual verification uvx --from git+https://github.com/tokusumi/wassden-mcp wassden check-completeness --userInput "test project"

IDE Compatibility

wassden provides flexible transport options for MCP-compatible environments:

Claude Code: Full support via stdio transport (recommended)

The transport flexibility ensures wassden can be integrated into any MCP-compatible development environment.

Alternative Installation Methods

1. Development Installation

git clone https://github.com/tokusumi/wassden-mcp
cd wassden-py
uv sync

Then use uv run in settings:

{
  "mcpServers": {
    "wassden": {
      "command": "uv",
      "args": ["run", "wassden", "start-mcp-server", "--transport", "stdio"],
      "cwd": "/path/to/wassden-py",
      "env": {}
    }
  }
}

2. Claude Code CLI For quick setup with Claude Code CLI:

claude mcp add wassden "uvx --from git+https://github.com/tokusumi/wassden-mcp wassden start-mcp-server --transport stdio"

Basic Usage

Complete Project Analysis & Requirements Generation
uvx --from git+https://github.com/tokusumi/wassden-mcp wassden check-completeness --userInput "Your project description"
This command analyzes your input for completeness and:
- If information is missing: Returns clarifying questions
- If information is sufficient: Provides structured prompts for the agent to generate EARS format requirements.md
Agent-Driven Document CreationThe agent uses wassden's prompts to create specifications:
- Requirements: Agent generates specs/requirements.md using wassden's EARS-formatted prompts
- Design: Agent creates specs/design.md following wassden's architectural guidance
- Tasks: Agent produces specs/tasks.md with wassden's WBS structure
Quality Assurance Through Validationwassden validates the agent-generated documents:
uvx --from git+https://github.com/tokusumi/wassden-mcp wassden validate-requirements specs/requirements.md uvx --from git+https://github.com/tokusumi/wassden-mcp wassden validate-design specs/design.md uvx --from git+https://github.com/tokusumi/wassden-mcp wassden validate-tasks specs/tasks.md
Task-Specific Implementation ReviewGenerate structured review prompts for each TASK-ID implementation:
uvx --from git+https://github.com/tokusumi/wassden-mcp wassden generate-review-prompt TASK-01-01
This provides agents with:
- Quality guardrails preventing test tampering and TODO shortcuts
- Project-specific quality checks (linting, formatting, testing)
- Requirements traceability validation against REQ/TR specifications
- Pass/fail criteria with actionable feedback for fixes

🛠️ Available Tools

📝 Prompt Generation Tools

These tools provide structured prompts for AI agents to create specifications

Tool	Purpose	Input	Agent Output
`check-completeness`	Analyze input & provide requirements prompt	User description	Questions or structured requirements prompt
`prompt-requirements`	Generate specialized requirements prompt	Project details	EARS-formatted requirements prompt
`prompt-design`	Generate design document prompt	Requirements path	Architectural design prompt
`prompt-tasks`	Generate WBS tasks prompt	Design path	Task breakdown prompt
`prompt-code`	Generate implementation prompt	All spec paths	Implementation guide prompt
`generate-review-prompt`	Generate TASK-specific review prompt	Task ID + spec paths	Quality review prompt with guardrails

✅ Validation Tools

These tools validate agent-generated documents for quality and consistency

Tool	Purpose	Input	Output
`validate-requirements`	Validate requirements quality	Requirements path	Validation report
`validate-design`	Validate design structure	Design path	Validation report
`validate-tasks`	Validate task dependencies	Tasks path	Validation report

📋 Validation Standards: wassden enforces 100% traceability - all requirements must be referenced in design and tasks. See Validation Documentation for detailed requirements and examples.

📊 Traceability & Analysis Tools

These tools provide project insights, dependency tracking, and change impact analysis

Tool	Purpose	Input	Output
`get-traceability`	Complete traceability matrix generation	Spec paths (optional)	Full REQ↔DESIGN↔TASK mapping
`analyze-changes`	Impact analysis for spec changes	Changed file + description	Dependency impact & update guide

🔗 Traceability Features

wassden provides comprehensive traceability management that ensures full project coherence:

📋 Complete Mapping: Automated REQ↔DESIGN↔TASK + TR↔TEST-SCENARIO relationship tracking
🔍 Impact Analysis: Identifies dependencies when specifications change
📝 Update Guidance: Generates specific prompts for updating affected documents
✅ Coverage Validation: Ensures 100% traceability compliance for all requirements and test scenarios

💡 Pro Tip: Use analyze-changes after modifying any spec file to identify all dependent documents that need updates. The tool provides step-by-step guidance for maintaining project consistency.

📁 Project Structure

wassden-py/
├── wassden/
│   ├── handlers/           # Tool implementation handlers
│   │   ├── completeness.py
│   │   ├── requirements.py
│   │   ├── design.py
│   │   ├── tasks.py
│   │   ├── code_analysis.py
│   │   └── traceability.py
│   ├── lib/               # Core functionality
│   │   ├── validate.py
│   │   ├── traceability.py
│   │   ├── fs_utils.py
│   │   └── prompts.py
│   ├── tools/             # MCP tool definitions
│   │   └── definitions.py
│   ├── server.py          # FastMCP server
│   └── cli.py             # CLI interface
├── specs/                 # Generated specifications
│   ├── requirements.md
│   ├── design.md
│   └── tasks.md
├── tests/                 # Comprehensive test suite
│   ├── unit/
│   ├── integration/
│   └── e2e/
└── pyproject.toml         # Project configuration

🧩 Language & Framework Support

Primary: Python 3.12+
MCP Framework: FastMCP for high-performance MCP server implementation
CLI: Typer for modern command-line interface with enhanced type safety
Testing: pytest + pytest-asyncio with 118 comprehensive tests (100% passing)
Performance: 198,406+ req/sec throughput, <0.01ms avg response time
Code Quality: ruff + mypy for linting and type checking
Standards: EARS format, WBS structure, 100% Traceability matrices

🎯 Use Cases

For Development Teams

Requirement Analysis: Systematic requirements gathering with gap analysis
Design Documentation: Structured design with automatic traceability
Project Planning: WBS generation with dependency management
Quality Assurance: Built-in validation and feedback loops

For AI Agents

Structured Prompting: Progressive prompts for complex development tasks
Context Preservation: Maintains context across development phases
Error Recovery: Validation-driven error detection and correction
Change Management: Impact analysis for specification changes

For Technical Writers

Documentation Generation: Automated prompt generation for technical documentation
Consistency Checking: Format and structure validation
Cross-reference Management: Automatic traceability link generation

🔧 Configuration

Default Paths

{
    "requirementsPath": "specs/requirements.md",
    "designPath": "specs/design.md",
    "tasksPath": "specs/tasks.md"
}

Validation Rules

EARS Format: Requirements must follow "システムは...すること" pattern
REQ-ID Format: Sequential numbering (REQ-01, REQ-02, ...)
TR-ID Format: Test requirements numbering (TR-01, TR-02, ...)
100% Traceability: All requirements (REQ + TR) must be referenced in design and tasks
Test Coverage: All test scenarios must be referenced in tasks via DC field
Design Coverage: All design components must be referenced in tasks
Dependencies: Task dependencies checked for circular references

📖 Detailed Documentation:

Specification Format Standards - Complete format guide for requirements, design, and tasks documents
Traceability Management - Complete guide to dependency tracking and change impact analysis
Requirements Validation - EARS format and ID validation
Traceability Requirements - REQ↔DESIGN↔TASK mapping rules
Tasks Validation - DAG requirements and coverage rules
CLI Reference - Command usage and troubleshooting

⚡ Performance Metrics

wassden-py delivers exceptional performance for production AI agent deployments:

Response Times

Average Response: <0.01ms ⚡️
P95 Response: <0.01ms
Min Response: <0.01ms
Sub-millisecond: Consistent ultra-fast responses

Throughput & Scalability

Peak Throughput: 198,406+ requests/second 🚀
Concurrent Load: 50+ agents simultaneously
Sustained Performance: 150,000+ req/sec under load
Memory Efficiency: Minimal Python overhead

Reliability

Test Coverage: 118 comprehensive tests (100% passing)
Automated Integration: Full MCP server testing
Error Recovery: 100% graceful error handling
Memory Leaks: Zero detected (active optimization)
Agent Compatibility: Claude Code, Cursor, VS Code verified

🧪 Development & Testing

Pre-commit Hooks

This project uses pre-commit hooks to ensure code quality. The hooks automatically run make check before each commit.

# Install pre-commit hooks
uv add --dev pre-commit
pre-commit install

Development Commands

# Install development dependencies
uv sync

# Quality checks (recommended)
make check                # Run format, lint, typecheck, and test with coverage
make ci                   # CI checks without modifying files

# Run CLI commands locally
uv run wassden --help                                     # Show available commands
uv run wassden check-completeness --userInput "test"      # Test CLI functionality

# Run MCP server with different transports (development)
uv run wassden start-mcp-server --transport stdio                                       # Start with stdio (default)
uv run wassden start-mcp-server --transport sse --host 127.0.0.1 --port 3001           # Start with SSE
uv run wassden start-mcp-server --transport streamable-http --host 0.0.0.0 --port 3001 # Start with streamable-http

# Or using production method with uvx
uvx --from git+https://github.com/tokusumi/wassden-mcp wassden start-mcp-server --transport stdio

# For detailed CLI options and troubleshooting, see docs/cli.md

Continuous Integration

All pull requests and pushes to main are automatically validated through GitHub Actions CI, which runs:

Code formatting (ruff format)
Linting (ruff check)
Type checking (mypy)
Full test suite with coverage reporting

🤝 Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Run quality checks (make check)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

MIT License – see LICENSE file for details.

🙏 Acknowledgments

Model Context Protocol: Enabling seamless AI-tool integration
FastMCP: High-performance MCP server framework for Python
Claude Code: Primary development and testing environment
Spec-Driven Development: Methodology inspiration and best practices

Built with ❤️ for the AI-driven development community

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

A Spec-Driven Development toolkit that transforms LLMs into development agents by providing expert-crafted prompts for generating structured specifications and validating documents across the Requirements → Design → Tasks → Code workflow.

Related MCP Servers

Mentor MCP Server
cyanheads
A
security
A
license
A
quality
Provides LLM Agents with AI-powered mentorship for code review, design critique, writing feedback, and brainstorming using the Deepseek API, enabling enhanced output in various development and strategic planning tasks.
Last updated -
5
31
TypeScript
Apache 2.0
WebEvalAgent MCP Serverofficial
Operative-Sh
A
security
A
license
A
quality
Unleashes LLM-powered agents to autonomously execute and debug web apps directly in your code editor, with features like webapp navigation, network traffic capture, and console error collection.
Last updated -
2
1,143
Python
Apache 2.0
Serena MCP Server
lin2000wl
A
security
A
license
A
quality
A coding agent toolkit that transforms LLMs into coding assistants capable of working directly on your codebase with semantic code retrieval and editing tools, providing IDE-like capabilities without requiring API subscriptions.
Last updated -
33
Python
MIT License
Spec-Driven Development MCP Server
formulahendry
A
security
A
license
A
quality
Facilitates spec-driven development workflows by providing structured prompts for generating requirements in EARS format, design documents, and implementation code following a systematic approach.
Last updated -
62
278
TypeScript
MIT License

View all related MCP servers