Labsco
iamhenry logo

GenSpec MCP Server

from iamhenry

Converts a USER-STORIES.md file into README, ROADMAP, and SYSTEM-ARCHITECTURE documents for the GenSpec workflow.

🔥🔥🔥✓ VerifiedFreeAdvanced setup
#automation#git

GenSpec MCP Server

A Model Context Protocol (MCP) server that converts user stories into structured documentation including README, ROADMAP, and SYSTEM-ARCHITECTURE documents through a guided approval workflow.

Overview

GenSpec MCP Server streamlines the documentation creation process by taking user stories as input and generating three key documentation artifacts:

  • README.md - Project overview and setup instructions
  • ROADMAP.md - Development roadmap and milestones
  • SYSTEM-ARCHITECTURE.md - Technical architecture documentation

The server uses a continuation workflow where each phase can be approved or edited before proceeding to the next phase, ensuring high-quality documentation output.

Features

  • MCP Integration - Works seamlessly with Claude Desktop, VS Code with MCP extension, and Cursor
  • Template-Based Generation - Uses predefined templates for consistent documentation structure
  • Approval Workflow - Generate → Present → Approve/Edit cycle for each document
  • Phase Dependencies - ROADMAP requires README, SYSTEM-ARCHITECTURE requires both
  • Multiple Entry Points - Start from any phase or run the complete workflow
  • Resource Access - Exposes templates via MCP resource protocol

MCP Client Integration

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "genspec": {
      "command": "npx",
      "args": ["genspec-mcp"]
    }
  }
}

VS Code with MCP Extension

  1. Install the MCP extension for VS Code
  2. Add to your VS Code settings or MCP configuration:
{
  "mcp.servers": {
    "genspec": {
      "command": "npx",
      "args": ["genspec-mcp"]
    }
  }
}

Cursor

Add to your Cursor MCP configuration:

{
  "mcpServers": {
    "genspec": {
      "command": "npx",
      "args": ["genspec-mcp"]
    }
  }
}

File Structure

genspec-mcp/
├── dist/                   # Compiled JavaScript files
├── src/                    # TypeScript source files
│   ├── index.ts           # MCP server entry point
│   ├── server.ts          # GenSpecServer implementation
│   ├── types.ts           # Type definitions and constants
│   └── utils/             # Utility modules (Track B, C, D)
├── templates/              # Generation templates
│   ├── 1-generate-readme.md
│   ├── 2-generate-roadmap.md
│   └── 3-generate-system-architecture.md
├── _ai/docs/              # Generated documentation output
├── package.json           # Package configuration
├── tsconfig.json          # TypeScript configuration
└── README.md              # This file

Generated Output

All generated documents are saved to the _ai/docs/ directory:

  • _ai/docs/README.md - Generated project README
  • _ai/docs/ROADMAP.md - Generated development roadmap
  • _ai/docs/SYSTEM-ARCHITECTURE.md - Generated system architecture

Development

Building

npm run build

Development Mode

npm run dev

Running Tests

npm test

Dependencies

Production Dependencies

  • @modelcontextprotocol/sdk - MCP protocol implementation
  • typescript - TypeScript compiler and runtime
  • tsx - TypeScript execution engine

Development Dependencies

  • @types/node - Node.js type definitions

Architecture

The GenSpec MCP server follows a modular architecture with five main tracks:

Core Components

  • GenSpecServer (src/server.ts) - Main MCP server implementation
  • Type System (src/types.ts) - Type definitions and constants
  • Template System (src/utils/templates.ts) - Template loading and management
  • Document Generation (src/utils/llm.ts) - Generation interface and context building
  • Validation System (src/utils/validation.ts) - Input validation and prerequisite checking
  • Approval System (src/utils/approval.ts) - Approval detection and edit feedback
  • Phase Management (src/utils/phases.ts) - Workflow execution and coordination

MCP Protocol Support

  • Prompts - Command-style prompts that invoke tools
  • Resources - Template access via template:// URI scheme
  • Tools - Document generation workflow tools

Workflow Management

  • Phase Dependencies - Ensures proper generation order
  • Continuation Logic - Seamless transitions between phases
  • Single-Workflow Concurrency - Prevents conflicting workflows per workspace
  • Approval Cycles - Up to 5 edit cycles per phase before abort