Thinking in Kiro - Development Flow MCP Server

A comprehensive development flow management system built on the Model Context Protocol (MCP) that provides structured project lifecycle management, from initial requirements gathering to final completion.

Table of Contents

• Overview
• Features
• Quick Start
• Installation
• Configuration
• Usage
• Architecture
• API Reference
• Development
• Contributing
• Troubleshooting
• FAQ
• License

Overview

Thinking in Kiro is an intelligent development flow server that guides projects through a systematic development process. It provides tools for requirement analysis, design documentation, task management, and project completion tracking, all while maintaining persistent state and generating comprehensive documentation.

Features

🔄 Structured Development Flow

• 8-Phase Development Process: From initialization to completion
• State Persistence: Automatic project state saving and restoration
• Phase Validation: Ensures proper progression through development stages
• Rollback Support: Ability to restore from backups

📋 Project Management

• Requirement Analysis: Structured requirement gathering and validation
• Design Documentation: Technical architecture and implementation planning
• Task Breakdown: Automatic task generation from design specifications
• Progress Tracking: Real-time project status and completion monitoring

📄 Document Generation

• Template System: Customizable document templates
• Auto-generation: Requirements, design, todo, and completion documents
• Variable Substitution: Dynamic content based on project state
• Conditional Logic: Smart template rendering with loops and conditions

🔍 Advanced Features

• Project Search: Find projects by criteria (phase, name, date)
• Statistics: Comprehensive project analytics
• Backup System: Automatic state backups with retention policies
• Logging: Detailed operation logging with multiple levels
• Type Safety: Full TypeScript implementation with comprehensive types

Architecture

Core Components

DevelopmentFlowServer

The main MCP server that handles all development flow operations:

• Manages the 8-phase development workflow
• Handles client requests and responses
• Coordinates between StateManager and DocumentGenerator
• Provides comprehensive error handling and validation

StateManager

Persistent state management for projects:

• JSON-based project storage
• Automatic backup creation and cleanup
• Project indexing and search capabilities
• Data integrity validation

DocumentGenerator

Template-based document generation system:

• Customizable templates for each development phase
• Variable substitution and conditional rendering
• Support for loops, conditions, and mathematical operations
• Automatic file generation and organization

Development Phases

1. INIT - Project initialization and setup
2. REQUIREMENT - Requirements gathering and analysis
3. CONFIRMATION - User confirmation of requirements
4. DESIGN - Technical design and architecture
5. TODO - Task breakdown and planning
6. TASK_COMPLETE - Individual task completion
7. STATUS - Project status monitoring
8. FINISH - Project completion and documentation

Quick Start

The fastest way to get started is using npx:

npx @stirstir/thinking-in-kiro

This command will:

1. Download and run the latest version
2. Start the MCP server on stdio
3. Display available tools and capabilities

Then, configure your MCP client to connect to the server (see Configuration section).

Installation

Method 1: Global Installation (Recommended)

For permanent use, install globally:

npm install -g @stirstir/thinking-in-kiro

Then run:

thinking-in-kiro

Method 2: Local Project Installation

For project-specific use:

npm install @stirstir/thinking-in-kiro

Then run:

npx thinking-in-kiro

Method 3: Direct from Source

For development or latest features:

git clone https://github.com/stirstir-labs/thinking-in-kiro.git
cd thinking-in-kiro
npm install
npm run build
npm start

Configuration

Add the server to your MCP client's configuration file.

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "thinking-in-kiro": {
      "command": "npx",
      "args": ["-y", "@stirstir/thinking-in-kiro"]
    }
  }
}

VS Code Configuration

Add to your VS Code settings.json:

{
  "mcp.servers": {
    "thinking-in-kiro": {
      "command": "npx",
      "args": ["-y", "@stirstir/thinking-in-kiro"]
    }
  }
}

Global Installation Configuration

If you installed globally, use:

{
  "mcpServers": {
    "thinking-in-kiro": {
      "command": "@stirstir/thinking-in-kiro"
    }
  }
}

Usage

Starting the Server

# Development mode with auto-reload
npm run dev

# Production mode
npm start

# Custom configuration
BASE_DIR=/custom/path npm start

MCP Client Integration

The server exposes the following MCP tools:

development_flow

Main tool for managing development workflow:

// Initialize a new project
const result = await client.callTool('development_flow', {
  action: 'init',
  projectName: 'My New Project',
  description: 'A sample project for demonstration'
});

// Add requirements
const reqResult = await client.callTool('development_flow', {
  action: 'requirement',
  projectName: 'My New Project',
  requirements: [
    'User authentication system',
    'Data persistence layer',
    'RESTful API endpoints'
  ]
});

// Generate design documentation
const designResult = await client.callTool('development_flow', {
  action: 'design',
  projectName: 'My New Project'
});

Project Lifecycle Example

// 1. Initialize project
await client.callTool('development_flow', {
  action: 'init',
  projectName: 'E-commerce Platform',
  description: 'Modern e-commerce solution with React and Node.js'
});

// 2. Define requirements
await client.callTool('development_flow', {
  action: 'requirement',
  projectName: 'E-commerce Platform',
  requirements: [
    'User registration and authentication',
    'Product catalog management',
    'Shopping cart functionality',
    'Payment processing integration',
    'Order management system'
  ],
  functionalRequirements: [
    'Users can browse products by category',
    'Users can add items to cart',
    'Users can checkout and pay securely'
  ],
  technicalRequirements: [
    'React frontend with TypeScript',
    'Node.js backend with Express',
    'PostgreSQL database',
    'Stripe payment integration'
  ]
});

// 3. Confirm requirements
await client.callTool('development_flow', {
  action: 'confirmation',
  projectName: 'E-commerce Platform',
  confirmed: true
});

// 4. Generate design
await client.callTool('development_flow', {
  action: 'design',
  projectName: 'E-commerce Platform'
});

// 5. Create task list
await client.callTool('development_flow', {
  action: 'todo',
  projectName: 'E-commerce Platform'
});

// 6. Complete tasks
await client.callTool('development_flow', {
  action: 'task_complete',
  projectName: 'E-commerce Platform',
  taskId: 'task_001'
});

// 7. Check status
await client.callTool('development_flow', {
  action: 'status',
  projectName: 'E-commerce Platform'
});

// 8. Finish project
await client.callTool('development_flow', {
  action: 'finish',
  projectName: 'E-commerce Platform'
});

Environment Variables

# Base directory for all operations (default: current directory)
BASE_DIR=/path/to/projects

# Enable debug logging
DEBUG=true

# Custom templates directory
TEMPLATES_DIR=/path/to/templates

# Maximum number of projects to maintain
MAX_PROJECTS=100

# Enable automatic backups
AUTO_BACKUP=true

Custom Templates

Create custom document templates in the templates directory:

<!-- templates/custom-requirement.md -->
# {{projectName}} - Requirements

## Project Description
{{description}}

## Requirements
{{#each requirements}}
- {{this}}
{{/each}}

## Functional Requirements
{{#each functionalRequirements}}
- {{this}}
{{/each}}

## Technical Requirements
{{#each technicalRequirements}}
- {{this}}
{{/each}}

API Reference

DevelopmentFlowInput Interface

interface DevelopmentFlowInput {
  action: DevelopmentPhase;
  projectName?: string;
  description?: string;
  requirements?: string[];
  functionalRequirements?: string[];
  technicalRequirements?: string[];
  acceptanceCriteria?: string[];
  confirmed?: boolean;
  taskId?: string;
  force?: boolean;
}

DevelopmentFlowResult Interface

interface DevelopmentFlowResult {
  success: boolean;
  message: string;
  data?: any;
  projectId?: string;
  phase?: DevelopmentPhase;
  nextSteps?: string[];
  generatedFiles?: string[];
}

File Structure

thinking-in-kiro/
├── src/
│   ├── index.ts                 # Main entry point
│   ├── server/
│   │   ├── DevelopmentFlowServer.ts  # Core MCP server
│   │   ├── StateManager.ts           # State persistence
│   │   └── DocumentGenerator.ts      # Document generation
│   ├── types/
│   │   └── index.ts             # TypeScript type definitions
│   └── utils/
│       └── index.ts             # Utility functions
├── templates/                   # Document templates
├── .dev/                       # Development process files
├── states/                     # Project state storage
└── projects/                   # Generated project files

Development

Building

# Build TypeScript
npm run build

# Watch mode for development
npm run dev

# Type checking
npm run type-check

Testing

# Run tests
npm test

# Test with coverage
npm run test:coverage

# Integration tests
npm run test:integration

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-feature
3. Make your changes and add tests
4. Ensure all tests pass: npm test
5. Commit your changes: git commit -am 'Add new feature'
6. Push to the branch: git push origin feature/new-feature
7. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For questions, issues, or contributions, please:

• Open an issue on GitHub
• Check the documentation
• Review existing issues and discussions

Prerequisites

• Node.js: Version 18 or higher
• npm: Version 8 or higher (comes with Node.js)
• MCP Client: Such as Claude Desktop, VS Code with MCP extension, or any MCP-compatible application

Usage Examples

Starting a New Development Project

1. Initialize Development Flow:

   Use the development_flow tool with action: 'init'

2. Follow the Structured Process:

   • Requirement analysis
   • Technical design
   • Task planning
   • Sequential execution

Typical Workflow

1. Project Initialization: Create a new development flow
2. Requirement Gathering: Analyze and document requirements
3. Design Phase: Create technical solution design
4. Task Planning: Break down implementation into actionable tasks
5. Execution: Complete tasks sequentially with progress tracking
6. Documentation: Generate completion reports

Troubleshooting

Common Issues

Server Won't Start

• Ensure Node.js 18+ is installed: node --version
• Check if port is available
• Verify installation: npm list -g @stirstir/thinking-in-kiro

MCP Client Can't Connect

• Verify configuration file syntax
• Check that the command path is correct
• Ensure the server is running: test with npx @stirstir/thinking-in-kiro

Permission Errors

• On macOS/Linux, you might need: sudo npm install -g @stirstir/thinking-in-kiro
• Or use a Node version manager like nvm

Tools Not Available

• Restart your MCP client after configuration changes
• Check server logs for initialization errors
• Verify the server version matches your expectations

Getting Help

• Check the FAQ section
• Review server logs for error messages
• Ensure your MCP client supports the required protocol version
• Test with a minimal configuration first

FAQ

Q: What is the Model Context Protocol (MCP)? A: MCP is a protocol that allows AI assistants to securely connect to external tools and data sources.

Q: Do I need to restart my MCP client after installing? A: Yes, most MCP clients require a restart to recognize new server configurations.

Q: Can I use this with multiple projects? A: Yes, each project can have its own development flow instance.

Q: Is this compatible with all MCP clients? A: It's designed to work with any MCP-compatible client, but has been tested primarily with Claude Desktop and VS Code.

Q: How do I update to the latest version? A: Run npm update -g @stirstir/thinking-in-kiro for global installations, or npm update @stirstir/thinking-in-kiro for local installations.

Contributing

Development Setup

1. Clone the repository:

   git clone https://github.com/stirstir-labs/thinking-in-kiro.git
   cd thinking-in-kiro

2. Install dependencies:

   npm install

3. Run in development mode:

   npm run dev

4. Build for production:

   npm run build

Contributing Guidelines

1. Fork the repository and create a feature branch
2. Follow the existing code style (TypeScript, ESLint, Prettier)
3. Write tests for new functionality
4. Update documentation as needed
5. Submit a pull request with a clear description

Code Style

• TypeScript: Use strict type checking
• ESLint: Follow the configured linting rules
• Prettier: Use for code formatting
• Naming: Use camelCase for variables, PascalCase for classes
• Comments: Document complex logic and public APIs

License

MIT License - see the LICENSE file for details.

Inspired by: The sequential thinking MCP server and structured development methodologies.