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

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.

• 🏗️ 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

npm install -g handoff-mcp

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

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"]
    }
  }
}

// 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'
  }
});

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'
});

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

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 is stored locally in SQLite:

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

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

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

# 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

# Run all tests
npm test

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

# Test coverage
npm run test:coverage

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

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

• 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

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

MIT License - see LICENSE file for details.

Built with the Model Context Protocol SDK by Anthropic.

Made with ❤️ for the AI-assisted development community