handoff-mcp

Handoff MCP Server

Strategic-to-tactical workflow orchestration for AI-assisted development. Bridge the gap between high-level planning and hands-on implementation.

  

Overview

Handoff MCP is a Model Context Protocol server that helps AI assistants manage complex development workflows by creating clear handoffs between strategic planning and tactical implementation. It provides project management, task tracking, and intelligent scaffolding capabilities.

Key Features

• 🏗️ Project Management - Organize work into projects with tags and metadata
• 📋 Handoff System - Create structured handoffs from strategy to implementation
• 🚀 Smart Scaffolding - Generate project structures from templates
• 💾 Local Storage - SQLite database for fast, offline-first operation
• 🤖 NLP Analysis - Intelligent requirement parsing and classification
• 📊 Analytics - Track project progress and success metrics

Installation

Via npm (recommended)

npm install -g handoff-mcp

From source

git clone https://github.com/coladapo/handoff-mcp.git
cd handoff-mcp
npm install
npm run build

Configuration

Add to your Claude Desktop configuration file:

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

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

For local development:

{
  "mcpServers": {
    "handoff": {
      "command": "node",
      "args": ["/absolute/path/to/handoff-mcp/dist/index.js"]
    }
  }
}

Usage Examples

Creating a Project

// Using the MCP tool in Claude
await use_tool('create_project', {
  name: 'E-commerce Platform',
  description: 'Modern e-commerce site with React and Node.js',
  tags: ['web', 'fullstack', 'production'],
  default_project_info: {
    language: 'TypeScript',
    framework: 'React + Express',
    build_command: 'npm run build',
    test_command: 'npm test'
  }
});

Creating a Handoff

await use_tool('create_handoff', {
  project_id: 'proj_123',
  title: 'Implement user authentication',
  strategic_context: 'Need secure user authentication for the platform with JWT tokens and OAuth support',
  tactical_requirements: [
    'Create login/signup endpoints',
    'Implement JWT token generation',
    'Add OAuth2 providers (Google, GitHub)',
    'Create middleware for route protection'
  ],
  acceptance_criteria: [
    'Users can register with email/password',
    'JWT tokens expire after 24 hours',
    'OAuth login works with Google',
    'Protected routes return 401 when unauthorized'
  ],
  priority: 'high'
});

Generating Scaffolding

await use_tool('generate_scaffold', {
  template_name: 'express',
  project_name: 'auth-service',
  target_path: './services/auth',
  variables: {
    port: 3001,
    database: 'PostgreSQL',
    authentication: true
  }
});

Available Tools

Project Management

| Tool | Description | |------|-------------| | create_project | Create a new project with metadata | | list_projects | List all projects with filtering | | get_project | Get detailed project information | | archive_project | Archive completed projects | | get_project_stats | Get project analytics and metrics |

Handoff Management

| Tool | Description | |------|-------------| | create_handoff | Create a strategic-to-tactical handoff | | get_handoff | Retrieve handoff details | | list_handoffs | List handoffs with filtering | | update_handoff_status | Update handoff progress | | add_handoff_note | Add notes to a handoff | | verify_handoff | Verify completion criteria | | generate_implementation_brief | Generate detailed implementation plan |

Scaffolding

| Tool | Description | |------|-------------| | list_templates | List available project templates | | preview_scaffold | Preview files before generation | | generate_scaffold | Generate project structure | | analyze_requirements | NLP analysis of requirements |

Project Templates

Handoff MCP includes several built-in templates:

• express - Node.js Express API server
• fastapi - Python FastAPI backend
• react - React frontend application
• mcp-server - MCP server boilerplate

Data Storage

Data is stored locally in SQLite:

• Location: ~/.puo-memo/cursor_handoffs.db
• Backup: Automatic daily backups
• Privacy: All data stays on your machine

Architecture

handoff-mcp/
├── src/
│   ├── index.ts           # MCP server entry point
│   ├── storage.ts          # SQLite database layer
│   ├── types.ts            # TypeScript interfaces
│   └── scaffolding/        # Template engine
│       └── ScaffoldingEngine.ts
├── templates/              # Project templates
│   ├── express/
│   ├── fastapi/
│   ├── react/
│   └── mcp-server/
└── tests/                  # Test suite

Development

Prerequisites

• Node.js 18+
• npm or yarn
• TypeScript 5.5+

Setup

# Clone repository
git clone https://github.com/coladapo/handoff-mcp.git
cd handoff-mcp

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Development mode
npm run dev

Testing

# Run all tests
npm test

# Run specific test suite
npm run test:storage
npm run test:scaffolding

# Test coverage
npm run test:coverage

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Areas for Contribution

• Additional project templates
• Enhanced NLP capabilities
• Cloud storage adapters
• Integration with more AI assistants
• Improved analytics and reporting

Roadmap

• [ ] Cloud sync support (Supabase/PostgreSQL)
• [ ] Team collaboration features
• [ ] Web dashboard for project overview
• [ ] GitHub integration
• [ ] Custom template creation UI
• [ ] Real-time progress tracking
• [ ] Export/import functionality

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Wiki

License

MIT License - see LICENSE file for details.

Acknowledgments

Built with the Model Context Protocol SDK by Anthropic.

---

Made with ❤️ for the AI-assisted development community