<<<<<<< HEAD

Hommy Specs MCP

English | 中文

A Model Context Protocol (MCP) server that provides structured software development specification generation services. This server replicates Kiro's spec mode functionality, enabling automatic generation of requirements documents, system design diagrams, and task lists based on feature descriptions.

Features

• 🔧 Requirements Generation: Automatically generate structured requirements documents with user stories and EARS format acceptance criteria
• 🏗️ System Design: Create comprehensive design documents with architecture diagrams, data models, and API specifications
• 📋 Task Planning: Generate detailed, prioritized task lists following test-driven development principles
• 🔌 MCP Integration: Seamlessly integrate with any MCP-compatible client (Claude Desktop, Cursor, etc.)
• 📦 Easy Installation: Run directly with npx - no complex setup required
• 🚀 CI/CD Ready: Built-in GitHub Actions support for automated testing and npm publishing

Quick Start

Using npx (Recommended)

npx hommy-specs-mcp

Installation

npm install -g hommy-specs-mcp

MCP Client Configuration

Add to your MCP client configuration (e.g., cursor or trae、augment):

{
  "mcpServers": {
    "hommy-specs-mcp": {
      "command": "npx",
      "args": ["hommy-specs-mcp"],
      "env": {}
    }
  }
}

Available Tools

create-requirements

Generate structured requirements documents from feature descriptions.

Parameters:

• featureDescription (required): Description of the feature to be developed
• context (optional): Project context and background information
• constraints (optional): Array of constraints and limitations

Example:

{
  "featureDescription": "User authentication system with email login and OAuth support",
  "context": "Web application backend API",
  "constraints": ["Must support JWT tokens", "Password encryption required"]
}

create-design

Generate system design documents based on requirements.

Parameters:

• requirements (required): Requirements document content
• includeArchitecture (optional): Whether to include architecture diagrams (default: true)
• includeDiagrams (optional): Whether to generate Mermaid diagrams (default: true)

create-tasks

Generate implementation task lists from design documents.

Parameters:

• design (required): Design document content
• testDriven (optional): Use test-driven development approach (default: true)
• maxTaskComplexity (optional): Maximum task complexity level (simple/medium/complex)

validate-spec

Validate specification documents for completeness and consistency.

Parameters:

• specContent (required): Specification document content to validate
• specType (required): Type of specification (requirements/design/tasks)

Development

Prerequisites

• Node.js >= 18.0.0
• npm or yarn

Setup

git clone https://github.com/JochenYang/hommy-specs-mcp.git
cd hommy-specs-mcp
npm install

Development Scripts

# Start development server
npm run dev

# Build the project
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

Testing

The project includes comprehensive testing:

• Unit Tests: Test individual components and functions
• Integration Tests: Test MCP protocol communication
• End-to-End Tests: Test complete spec generation workflows

# Run all tests
npm test

# Run specific test types
npm run test:unit
npm run test:integration
npm run test:e2e

# Watch mode for development
npm run test:watch

Architecture

The server is built with a modular architecture:

• MCP Server Core: Handles protocol communication and tool registration
• Spec Generator Engine: Core business logic for document generation
• Document Templates: Standardized templates for different document types
• Validation Layer: Input validation and error handling
• Transport Layer: Support for multiple transport protocols (Stdio, HTTP)

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some 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.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Roadmap

• [ ] Advanced template customization
• [ ] Multiple output formats (PDF, HTML)
• [ ] Integration with popular project management tools
• [ ] AI-powered requirement analysis
• [ ] Multi-language support

Built with ❤️ using TypeScript and the Model Context Protocol SDK.

hommy-specs-mcp

61588270b18cf618d5530bf44ea8a2f1e9b9426b