Lilith bdcf098634 chore(shared): 🔧 Hello! I'm a mock assistant responding to your message.

2026-01-05 12:55:52 -08:00

16 KiB

Raw Permalink Blame History

Stream Workflow Manager MCP Server

DEPRECATED: This package is deprecated. The worktree workflow methodology is no longer maintained. This code remains for reference only.

AI-powered worktree workflow automation for egirl-platform.

Version: 0.2.0 Status: DEPRECATED

🤖 Automated Releases: This package uses conventional commits for automatic versioning. Push commits with feat: or fix: prefixes to trigger releases. See COMMIT_CONVENTION.md

Overview

Stream Workflow Manager is a Model Context Protocol (MCP) server that automates git worktree workflows for Claude Code agents. It enforces safe development practices, provides AI-powered conflict resolution, and manages parallel development streams.

Key Features

Worktree Enforcement: Automatically blocks file modifications in main directory, guides agents to create isolated worktrees
Stream Lifecycle Management: Creates, tracks, and archives development streams with progress monitoring
AI-Powered Merge Resolution: Uses Claude to intelligently resolve merge conflicts with context-aware strategies
Concurrency Control: Prevents merge conflicts through atomic operations and locking
Validation Pipeline: Runs TypeScript, build, and lint checks after conflict resolution
Post-Compaction Recovery: Maintains active stream context that survives Claude Code context compaction

Post-Compaction Recovery (v0.3.0+)

When Claude Code compacts context (during long sessions or after breaks), agents may lose awareness of which worktree they should be working in. This can cause the agent to accidentally work in the main directory.

The Problem

After compaction, agents might:

Forget they were working in a worktree
Start making changes in the main directory
Cause merge conflicts or lost work

The Solution

The MCP server tracks multiple active streams that persist across compaction:

// After starting a stream, context is automatically saved
await mcp__stream-workflow__start_stream({ ... });
// Stream is now tracked as active

// Multiple streams can be active simultaneously!
await mcp__stream-workflow__start_stream({ title: "Feature A", ... });
await mcp__stream-workflow__start_stream({ title: "Feature B", ... });

// After compaction or session resume, recover context:
await mcp__stream-workflow__get_active_context();
// Returns: list of ALL active streams if in main, or current stream if in worktree

Multi-Stream Support

The system supports multiple simultaneous active streams:

Each start_stream call adds to the active streams list
get_active_context lists ALL active streams when called from main
Streams sorted by "last accessed" to help identify most relevant
complete_stream removes only that specific stream from tracking

When to Use

Scenario	Tool to Call
After "let's continue" or session resume	`get_active_context`
After context compaction message	`get_active_context`
Before making file modifications	`verify_location`
Unsure which stream you're working on	`get_active_context`

Example Response - Multiple Streams

When in main directory with multiple active streams:

⚠️ IN MAIN DIRECTORY - SELECT A STREAM

Current Directory: /path/to/main
Status: DO NOT MODIFY FILES HERE

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ACTIVE STREAMS (3)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  1. stream-1502-api-refactor ← MOST RECENT
     Path: /path/to/worktrees/stream-1502-api-refactor
     Last: 12/14/2025, 3:45:00 PM

  2. stream-1501-auth-system
     Path: /path/to/worktrees/stream-1501-auth-system
     Last: 12/14/2025, 2:30:00 PM

  3. stream-1500-ui-updates
     Path: /path/to/worktrees/stream-1500-ui-updates
     Last: 12/14/2025, 10:15:00 AM

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ACTION REQUIRED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

To continue on most recent stream:
  cd /path/to/worktrees/stream-1502-api-refactor

Or navigate to any stream listed above.

Installation

Prerequisites

Node.js 18+ and pnpm
Claude Code CLI
Git worktrees enabled
Anthropic API key

Setup

Install dependencies:

cd .claude/mcp-servers/stream-workflow-manager
pnpm install

Configure MCP server:

Add to .claude/mcp-servers.json:

{
  "stream-workflow-manager": {
    "command": "node",
    "args": [".claude/mcp-servers/stream-workflow-manager/dist/server.js"],
    "env": {
      "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}",
      "PROJECT_ROOT": "/path/to/your/project",
      "WORKTREE_ROOT": "/path/to/worktrees"
    }
  }
}

Build the server:

pnpm build

Restart Claude Code:

Exit and restart Claude Code to load the MCP server.

Available Tools

Tool	Description	Status
`get_active_context`	CRITICAL: Recovers working context after compaction/session resume	✅ NEW
`start_stream`	Initialize new stream with metadata in main, create worktree	✅ Implemented
`verify_location`	Checks if current directory is a worktree, blocks operations in main	✅ Implemented
`create_stream`	Creates new worktree + branch + stream tracking file	✅ Implemented
`update_stream_status`	Updates stream progress in STREAM_STATUS_DASHBOARD.md	✅ Implemented
`get_stream_info`	Retrieves stream metadata and current status	✅ Implemented
`list_streams`	Lists all active/completed streams by category	✅ Implemented
`complete_phase`	Marks stream phase as complete, updates progress	✅ Implemented
`prepare_merge`	Merges main into worktree with AI conflict resolution	✅ Implemented
`complete_merge`	Fast-forwards main branch (with locking)	✅ Implemented
`complete_stream`	Archives stream to history, cleanup worktree	✅ Implemented
`validate_stream`	Checks stream health, detects configuration issues	✅ Implemented
`sync_dashboard`	Reconciles dashboard with actual worktree state	✅ Implemented

Usage Examples

Full Stream Lifecycle

// Step 1: Initialize new stream (from main directory)
const initResult = await mcp__stream-workflow__start_stream({
  category: "feature",
  description: "Implement user authentication",
  scope: "Add JWT authentication middleware and login endpoint"
});

// Result: Creates metadata in main, creates worktree at stream-001
// Location: <WORKTREE_ROOT>/stream-001 (XDG-compliant path from config)

// Step 2: Work in the worktree...
// (make changes, commit to branch)

// Step 3: Merge main into worktree (AI resolves conflicts)
const prepareResult = await mcp__stream-workflow__prepare_merge({
  streamId: "stream-001"
});

// Step 4: Fast-forward main (clean merge, no conflicts)
const completeResult = await mcp__stream-workflow__complete_merge({
  streamId: "stream-001"
});

// Step 5: Archive stream and cleanup
const archiveResult = await mcp__stream-workflow__complete_stream({
  streamId: "stream-001",
  outcome: "merged",
  summary: "Authentication implemented and tested"
});

Creating a New Stream (Alternative Method)

// Legacy method (if start_stream unavailable)
const result = await mcp__stream-workflow__create_stream({
  category: "feature",
  description: "Implement user authentication"
});

// Result: Creates worktree, branch, and stream tracking file
// Location: <WORKTREE_ROOT>/stream-001 (XDG-compliant path from config)

Merging Changes

// Phase 1: Merge main into worktree (AI resolves conflicts)
const prepareResult = await mcp__stream-workflow__prepare_merge({
  streamId: "stream-001"
});

// Phase 2: Fast-forward main (clean merge, no conflicts)
const completeResult = await mcp__stream-workflow__complete_merge({
  streamId: "stream-001"
});

Completing a Stream

// Archive stream and cleanup
const result = await mcp__stream-workflow__complete_stream({
  streamId: "stream-001",
  outcome: "merged",
  summary: "Authentication implemented and tested"
});

Architecture

stream-workflow-manager/
├── src/
│   ├── server.ts              # MCP server entry point
│   ├── config.ts              # Configuration
│   ├── types.ts               # TypeScript interfaces
│   ├── conflict-resolver.ts   # AI conflict resolution engine
│   │
│   ├── tools/                 # MCP tool implementations
│   │   ├── start-stream.ts    # Initialize stream lifecycle
│   │   ├── prepare-merge.ts
│   │   ├── complete-merge.ts
│   │   └── ...
│   │
│   ├── strategies/            # Conflict resolution strategies
│   │   ├── code-merge.ts      # TypeScript/JavaScript
│   │   ├── config-merge.ts    # JSON/YAML
│   │   └── docs-merge.ts      # Markdown
│   │
│   └── validators/            # Post-merge validation
│       ├── typescript.ts
│       ├── build.ts
│       └── lint.ts
│
├── prompts/
│   └── conflict-resolution.txt    # AI prompts
│
└── docs/
    ├── ARCHITECTURE.md        # System design
    ├── EXTENDING.md           # Extension guide
    └── ERROR_CATALOG.md       # Error reference

Configuration

Environment Variables

Variable	Required	Description
`ANTHROPIC_API_KEY`	Yes	API key for Claude AI conflict resolution
`PROJECT_ROOT`	Yes	Path to main project directory
`WORKTREE_ROOT`	Yes	Path to worktrees parent directory
`DEVELOPER_MODE`	No	Enable self-modification features (see below)

DEVELOPER_MODE Configuration

For regular users: Omit this setting. It defaults to false (user mode).

For MCP developers: Enable self-modification features using either:

Global configuration (recommended for creators):
- Create ~/.claude/mcp-config.json:
```
{
  "developerMode": true
}
```
- Applies to all projects automatically
- See mcp-config.json.example for full template

Per-project configuration (for specific projects):

Add to .claude/mcp-servers.json:

{
  "stream-workflow-manager": {
    "env": {
      "DEVELOPER_MODE": "true"
    }
  }
}

Configuration hierarchy (highest priority first):

Per-project environment variable (.claude/mcp-servers.json)
Global config file (~/.claude/mcp-config.json)
Default: false (user mode)

What changes when enabled:

MCP tool responses include self-improvement instructions
Agents receive extension points and update workflows
Error messages include fix instructions for the MCP server itself

See DEVELOPMENT.md for complete developer guide.

Optional Features

The MCP server supports optional features that can be enabled globally or per-project:

Screenshot Generation (opt-in):

Automatically generates screenshots during prepare_merge
Prevents pre-push hooks from creating uncommitted files in main
Requires: pnpm screenshots:quick command in your project

Enable globally in ~/.claude/mcp-config.json:

{
  "streamWorkflow": {
    "enableScreenshots": true
  }
}

Or per-project via environment variable (see setup script).

See docs/OPTIONAL_FEATURES.md for complete details.

Advanced Configuration

Edit src/config.ts to customize:

File size limits for conflict resolution
Timeout settings for AI operations
AI model and token limits
Path configurations

Troubleshooting

Server Not Starting

Symptoms: MCP tools not available in Claude Code

Solutions:

Check .claude/mcp-servers.json configuration
Verify ANTHROPIC_API_KEY is set
Check server logs: ~/.claude/logs/mcp-stream-workflow.log
Rebuild server: pnpm build
Restart Claude Code

Tools Not Found After Update

Symptoms: "Tool not found" errors after modifying server

Cause: MCP server caches old code

Solution:

# Find and kill the server process
ps aux | grep stream-workflow-manager
kill <PID>

# Restart Claude Code (will auto-restart server)

Conflict Resolution Failures

Symptoms: AI conflict resolution fails or produces invalid code

Solutions:

Check file size (default limit: 100KB)
Review prompts/conflict-resolution.txt for your file type
Increase timeout in src/config.ts
Check API key has sufficient quota
Review error in logs for specific failure reason

Merge Lock Timeout

Symptoms: "Merge lock timeout" error

Cause: Previous merge operation didn't release lock