spec-chain

Spec Chain

A specification chain management system with CLI and MCP (Model Control Protocol) server for AI-powered specification workflows.

Features

• 🔗 Specification Chain Management - Create and manage chains of specifications
• 🤖 AI-First Design - Generate prompts optimized for AI assistants
• 🔌 MCP Server - Integrate with Claude Desktop, Cursor, and other MCP-compatible tools
• 📝 Template System - Customizable command templates
• 🎯 Project Structure - Organized asset and specification management

Installation

# Global installation
npm install -g spec-chain

# Or use npx (no installation required)
npx spec-chain init

Quick Start

Using the CLI

# Initialize a project
spec-chain init

# Prime your AI assistant
spec-chain prime

# Run commands
spec-chain run "Create a user authentication spec"

# Validate structure
spec-chain validate

Using MCP Server

• Install spec-chain in your project:

  npm install spec-chain
  

• Add to your AI assistant's MCP config:

  {
    "mcpServers": {
      "spec-chain": {
        "command": "node",
        "args": ["./node_modules/spec-chain/mcp-server/server.js"]
      }
    }
  }
  

• Use MCP tools in your AI assistant with natural language:

  "Initialize a spec chain project"
  "Prime me with the spec chain context"
  "Run the spec chain command"
  

Usage

CLI Usage

Initialize a new project

spec-chain init

# Skip prompts with defaults (currently no prompts)
spec-chain init --yes

This creates a .spec-chain/ directory with:

• config.json - Project configuration
• assets/ - Project assets
  • ASSETS.md - Asset documentation
  • inspiration/ - Inspiration files
  • playbooks/ - Playbook templates
• chains/ - Chain templates
  • init-spec-chain.md - Initialization prompt
  • run-spec-chain.md - Run command prompt
  • validate-spec-chain.md - Validation prompt
  • prime.md - Context priming prompt
• specs/ - Specification files

Other Commands

# Prime AI with project context
spec-chain prime

# Run spec chain with arguments
spec-chain run [arguments...]

# Validate project structure
spec-chain validate

MCP Server

The Spec Chain MCP server provides programmatic access to all Spec Chain functionality through the Model Control Protocol, enabling integration with AI coding assistants like Claude Desktop, Cursor, and others.

Starting the MCP Server

# Start the MCP server
npm run mcp-server

# Start with debugging enabled
npm run inspector

Available MCP Tools

• spec_chain_suggest - Get suggestions for command parameters

  • Parameters: command (one of: init, run, validate, prime)
  • Returns examples and parameter descriptions

• spec_chain_init - Initialize a new Spec Chain project

  • Parameters: projectRoot (optional, defaults to current directory)

• spec_chain_run - Run spec chain commands with arguments

  • Parameters: projectRoot, arguments[]

• spec_chain_validate - Validate project structure

  • Parameters: projectRoot

• spec_chain_prime - Prime AI assistant with project context

  • Parameters: projectRoot

Connecting to Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "spec-chain": {
      "command": "node",
      "args": ["/path/to/spec-chain/mcp-server/server.js"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Connecting to Cursor

Add to your Cursor MCP configuration (.cursor/mcp.json):

{
  "mcpServers": {
    "spec-chain": {
      "command": "node",
      "args": ["./node_modules/spec-chain/mcp-server/server.js"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Environment Variables

Create a .env file in your project root:

# MCP Server Configuration
LOG_LEVEL=INFO  # Options: ERROR, WARN, INFO, DEBUG

# Future AI features (optional)
# OPENAI_API_KEY=your-api-key
# ANTHROPIC_API_KEY=your-api-key

MCP Tool Examples

Once connected, you can use the tools in your AI assistant with natural language:

// Get help with parameters
"What parameters can I use with spec chain init?"
"Show me examples for the run command"

// Initialize in current directory
"Initialize a spec chain project"

// Initialize in a specific directory
"Initialize a spec chain project in ./my-specs"

// Prime the AI with context (uses current directory)
"Prime me with the spec chain context"

// Run a spec chain command
"Run the spec chain command with arguments: create user authentication flow"

// Validate project structure
"Validate the spec chain project structure"

The tools understand natural language and default to the current directory. You can also be more specific:

// Specify a different directory
"Initialize a spec chain project in /path/to/my-project"

// Multiple arguments
"Run spec chain with these arguments: auth, user, oauth2"

Interactive Workflow

The MCP server supports an interactive workflow:

• Ask for suggestions: "What parameters should I use for init?"
• Get examples: The spec_chain_suggest tool returns examples and descriptions
• Execute with confidence: Use the suggested parameters in your command

Example conversation:

User: "I want to create a new spec chain project"
Assistant: I'll help you set up a new spec chain project. *Uses spec_chain_init*

The project has been initialized with the following structure:
- .spec-chain/config.json - Configuration file
- .spec-chain/assets/ - For inspiration and playbooks
- .spec-chain/chains/ - Command templates
- .spec-chain/specs/ - Your specifications

User: "What parameters can I use with the run command?"
Assistant: *Uses spec_chain_suggest with command="run"*

The run command accepts arguments that will be passed to your spec chain...

Each tool returns:

• Success/Error status - Whether the operation succeeded
• Message - Human-readable result message
• Prompt - The generated prompt to copy to your AI assistant (for run, validate, prime)
• Additional data - Tool-specific information (config, validation results, etc.)

Development

# Install dependencies
npm install

# Run tests
npm test

# Format code
npm run format

# Check formatting
npm run format:check

# Auto-format and create PR (slash command)
npm run format-and-commit

# Run MCP server locally
npm run mcp-server

# Debug MCP server
npm run inspector

Slash Commands

format-and-commit

Automated code formatting workflow that:

• 🔍 Checks code formatting with npm run format:check
• 🔧 Fixes formatting issues with npm run format
• 🌿 Creates a new branch for the changes
• 💾 Commits all formatting changes
• ⬆️ Pushes the branch to remote
• 🔄 Creates a pull request

# Multiple ways to run the formatting workflow:

# Via npm script (long form)
npm run format-and-commit

# Via npm script (short alias)
npm run fac

# Via spec-chain CLI (if globally installed)
spec-chain format-and-commit
spec-chain fac

# Via global binary (if globally installed)
format-and-commit

# Get help with any method
npm run format-and-commit -- --help
spec-chain fac --help
format-and-commit --help

Requirements:

• Clean working directory (no uncommitted changes)
• GitHub CLI (gh) installed and authenticated
• npm scripts: format and format:check

This command is perfect for maintaining code quality and automating the tedious process of formatting fixes.

Project Structure

spec-chain/
├── bin/              # CLI executable
├── index.js          # Main library entry point
├── .spec-chain/      # Package templates
│   ├── assets/       # Template assets
│   │   └── ASSETS.md
│   └── chains/       # Chain templates
├── mcp-server/       # MCP server implementation
│   ├── server.js     # Server entry point
│   └── src/
│       ├── index.js  # Server class
│       ├── logger.js # Logging utility
│       └── tools/    # MCP tool implementations
│           ├── init.js
│           ├── run.js
│           ├── validate.js
│           └── prime.js
└── package.json

Publishing

This project uses changesets for version management.

# Create a changeset
npm run changeset

# Version and publish (CI will handle this automatically)
npm run release

License

MIT