cordlesssteve/mitosis-mcp-server

Mitosis MCP Server

An MCP server for spawning new Claude Code sessions with context transfer capabilities.

Overview

The Mitosis MCP server enables seamless handoff between Claude Code sessions by:

• Extracting current session context (directory, project type, recent files)
• Generating handoff briefs with working summary and next steps
• Spawning new Windows Terminal tabs ready for Claude Code

Features

• Session Context Extraction: Automatically gathers current working directory, project type, and recent files
• Handoff Brief Generation: Creates structured briefs for context transfer between sessions
• Windows Terminal Integration: Spawns new tabs with proper naming convention
• Complete Workflow: End-to-end handoff from context extraction to new session spawn

Installation

npm install
npm run build

Configuration

Add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "mitosis": {
      "command": "node",
      "args": ["./dist/src/index.js"],
      "env": {}
    }
  }
}

Available Tools

perform_handoff ⭐ MAIN TOOL

Primary tool for session handoff. Performs complete workflow: extracts context, generates handoff files, and spawns new Windows Terminal tab with Claude automatically started. The new session displays context summary on startup.

Usage:

• Basic handoff: perform_handoff
• Enhanced handoff: First call provide_intelligent_context, then perform_handoff

Returns: Complete handoff result with brief and spawn status

provide_intelligent_context 🧠 ENHANCED HANDOFF

Call BEFORE perform_handoff for intelligent context transfer. Allows current Claude instance to provide rich conversation context including summary, progress, challenges, and decisions. Enables near-seamless conversation continuation.

Parameters:

• conversationSummary (required): Comprehensive summary of the conversation
• currentObjective (required): Main goal or task being worked on
• recentProgress: Recent accomplishments and progress made
• technicalDetails: Important technical information and implementation details
• challengesEncountered: Problems, bugs, or obstacles encountered
• solutionsExplored: Approaches and strategies that have been tried
• nextSteps: Specific next actions that should be taken
• importantDecisions: Key decisions made during the conversation
• codeChangesExplained: Explanations of what code changes were made and why
• contextualNotes: Additional context and background for continuation

Returns: Confirmation that context was captured for next handoff

spawn_claude_session

Spawns new Windows Terminal session with automatic Claude startup. Creates handoff files if briefing provided. Usually called by perform_handoff.

Parameters:

• directory (optional): Target directory for new session (defaults to current directory)
• briefing (optional): HandoffBrief for context transfer

Returns: SpawnResult with success status and session details

extract_session_context

Extracts current session context for handoff. Gathers working directory, project type, recent files, git changes, and any intelligent context. Usually called automatically by perform_handoff.

Returns: SessionContext object with current environment details

generate_handoff_brief

Generates handoff briefing documents (.claude-handoff.json and .claude-handoff.md) from session context. Enhanced with intelligent context if available. Usually used automatically by perform_handoff.

Parameters:

• context: SessionContext object from extract_session_context

Returns: HandoffBrief with project summary, current context, and transition details

Usage Examples

Basic Session Spawn

// Spawn new session in current directory
await spawn_claude_session()

// Spawn in specific directory  
await spawn_claude_session({ directory: "/path/to/project" })

Complete Handoff Workflow

// Full context transfer workflow
const result = await perform_handoff()

Manual Context Transfer

// Extract current context
const context = await extract_session_context()

// Generate handoff brief
const brief = await generate_handoff_brief(context)

// Spawn with context
await spawn_claude_session({ 
  directory: "/target/directory",
  briefing: brief 
})

How It Works

The Working Solution

After extensive troubleshooting, the core spawn functionality uses a simple, reliable approach:

const command = `wt.exe new-tab --title "${tabName}"`;

This minimal command creates a new Windows Terminal tab without complex WSL integration, environment setup, or multiple fallback methods. Auto-starting Claude proved unreliable, so manual startup is required.

What We Learned

• Simplicity wins: Complex WSL wrapping wasn't needed
• Process management: Old MCP processes can run stale compiled code
• Testing approaches: Direct JSON-RPC testing revealed server functionality when MCP tools failed
• Compilation importance: Always rebuild (npm run build) and restart processes after changes

Troubleshooting

If spawn fails:

1. Check Windows Terminal availability: wt.exe --help
2. Verify MCP server connection: claude mcp list
3. Test directly: echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "spawn_claude_session", "arguments": {"directory": "/path"}}}' | node dist/src/index.js
4. Kill old processes: ps aux | grep mitosis then kill [PID]
5. Rebuild: npm run build

Project Structure

src/
├── index.ts                    # MCP server entry point
├── managers/
│   └── SessionHandoffManager.ts # Core handoff logic
└── types/
    └── index.ts               # Type definitions

Development

# Install dependencies
npm install

# Build project
npm run build

# Test directly (bypass MCP)
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "spawn_claude_session", "arguments": {}}}' | node dist/src/index.js

License

MIT