Phazzie/SeamsLikeIt

SDD MCP Server

An MCP (Model Context Protocol) server that implements Seam-Driven Development (SDD) methodology, enabling domain experts to build enterprise-quality applications through AI-assisted development.

🚀 Transform plain English requirements into working software architecture in minutes!

What is SDD?

Software-Defined Development treats component communication pathways (seams) as first-class architectural citizens. By defining clear contracts before implementation, SDD eliminates integration issues and enables reliable AI-assisted development.

Key Principles

1. Seams First, Implementation Second - Define how components communicate before building them
2. ContractResult Pattern - All cross-component calls return standardized results
3. Fail-Fast Validation - Catch errors at component boundaries
4. Blueprint-Driven Development - Detailed implementation guidance in every stub

Prerequisites

• Node.js 18+
• OpenAI API key (uses gpt-4o-mini model)
• Claude Desktop or Claude CLI

Installation

From npm (coming soon)

npm install -g sdd-mcp-server

From source

git clone https://github.com/Phazzie/SeamsLikeIt.git
cd SeamsLikeIt
npm install
npm run build

Configuration

Create a .env file in the project root:

OPENAI_API_KEY=your-openai-api-key
AI_MODEL=gpt-4o-mini-2024-07-18

Usage

With Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "sdd": {
      "command": "sdd-mcp-server"
    }
  }
}

Available Tools

1. sdd_analyze_requirements

Transform plain English requirements into SDD-compliant component and seam definitions.

// Example usage in Claude:
Use sdd_analyze_requirements with:
- requirements: "Build an online bookstore with inventory management"
- domain: "ecommerce"

2. sdd_generate_contracts

Convert seam definitions into TypeScript interfaces with ContractResult patterns.

// Takes the project output from analyze_requirements
Use sdd_generate_contracts with the project object

3. sdd_create_stubs

Generate implementation files with detailed blueprints for AI or developers to follow.

// Takes the project with contracts
Use sdd_create_stubs with the project object

4. sdd_validate_integration

Test that components can communicate properly through their defined seams.

// Validates the complete project
Use sdd_validate_integration with the project object

5. sdd_orchestrate_simple

Run the complete SDD workflow from requirements to ready-to-implement project.

// One-step project generation
Use sdd_orchestrate_simple with:
- requirements: "Your project description"
- domain: "healthcare|ecommerce|fintech" (optional)
- outputPath: "/path/to/save/project" (optional)

6. sdd_analyze_for_regeneration 🆕

Identify components that should be regenerated rather than debugged (SDD refactoring).

Use sdd_analyze_for_regeneration with:
- project: <your SDD project>
- issues: ["Integration failing", "Performance degraded"]
- codeSmells: ["Complex callbacks", "Unclear errors"]

7. sdd_regenerate_component 🆕

Regenerate a component from its contracts - the SDD way to refactor!

Use sdd_regenerate_component with:
- project: <your SDD project>
- componentId: "user-service"
- reason: "Complex integration issues"
- improvements: ["Add retry logic", "Simplify error handling"]

Domain-Specific Intelligence

The server includes specialized patterns for:

Healthcare

• HIPAA compliance patterns
• Patient data security
• Clinical workflow templates
• Audit trail requirements

E-commerce

• Payment processing patterns
• Inventory management
• Shopping cart workflows
• PCI compliance

Fintech

• Financial precision (bigint for money)
• Transaction patterns
• KYC/AML compliance
• Regulatory reporting

Example Workflow

1. Start with Requirements

I need a patient appointment scheduling system that integrates with our EHR

2. Analyze Requirements

The tool identifies:

• Components: Patient Service, Appointment Service, EHR Integration
• Seams: Book Appointment, Check Availability, Update Medical Record

3. Generate Contracts

Creates TypeScript interfaces:

export interface BookAppointmentInput {
  patientId: PatientId;
  providerId: ProviderId;
  requestedTime: Date;
  visitType: 'routine' | 'urgent' | 'followup';
}

export interface BookAppointmentContract {
  bookAppointment(input: BookAppointmentInput): Promise<ContractResult<Appointment>>;
}

4. Create Stubs

Generates implementation blueprints:

async bookAppointment(input: BookAppointmentInput): Promise<ContractResult<Appointment>> {
  // BLUEPRINT: Book patient appointment with provider
  // 
  // STEP 1: Validate patient and provider exist
  // STEP 2: Check provider availability at requested time
  // STEP 3: Verify patient insurance coverage
  // STEP 4: Create appointment record
  // STEP 5: Send confirmation to patient
  // STEP 6: Update provider calendar
  //
  // ERROR SCENARIOS:
  // - Provider not available: Return SCHEDULING_CONFLICT
  // - Insurance not verified: Return INSURANCE_PENDING
  
  throw new NotImplementedError('Follow blueprint above');
}

5. Implement with AI

Give the stub to AI: "Implement this following the blueprint exactly"

Development

Building

npm run build

Testing

npm test

Running locally

npm run dev

Architecture

src/
├── index.ts           # MCP server setup
├── tools/             # Tool implementations
│   ├── analyze-requirements.ts
│   ├── generate-contracts.ts
│   ├── create-stubs.ts
│   ├── validate-integration.ts
│   └── orchestrate-simple.ts
├── types/             # TypeScript type definitions
├── prompts/           # AI prompting templates
├── domain-modules/    # Domain-specific patterns
└── utils/             # Shared utilities

Cost Information

Using OpenAI's gpt-4o-mini model, typical costs per operation:

• Analyze Requirements: ~$0.0006
• Generate Contracts: ~$0.0005
• Create Stubs: ~$0.0008
• Full Workflow: ~$0.0025

Features

• 🎯 Domain Intelligence: Built-in patterns for healthcare, e-commerce, fintech, SaaS
• 🔍 Multi-Pass Analysis: 95%+ seam detection accuracy
• 🛡️ Type Safety: Full TypeScript with ContractResult pattern
• 📊 Cost Tracking: Monitor AI usage costs per operation
• 🔄 Regeneration Philosophy: Broken? Regenerate from blueprint instead of debugging
• 🚀 SDD Refactoring: Analyze and regenerate components instead of traditional debugging
• 🧠 Advanced AI Prompting: Reasoning traces, self-validation, mental models

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

License

MIT License - see LICENSE file for details

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Built with ❤️ using Seam-Driven Development principles