Session Collab MCP

A Model Context Protocol (MCP) server for Claude Code that prevents conflicts when multiple sessions work on the same codebase simultaneously.

Problem

When using parallel Claude Code sessions or the parallel-dev workflow:

• Session A is refactoring some code
• Session B doesn't know and thinks the code "has issues" - deletes or reverts it
• Session A's work disappears

Root cause: No synchronization mechanism for "work intent" between sessions.

Solution

Session Collab MCP provides a Work-in-Progress (WIP) Registry that allows sessions to:

1. Declare - Announce which files you're about to modify
2. Check - Verify no other session is working on the same files
3. Communicate - Send messages between sessions
4. Release - Free files when done

Installation

Option 1: Claude Code Plugin (Recommended)

Install as a Claude Code plugin for automatic MCP server setup, hooks, and skills:

# Add marketplace
/plugin marketplace add leaf76/session-collab-mcp

# Install plugin
/plugin install session-collab@session-collab-plugins

The plugin includes:

• MCP Server: Automatically configured
• Hooks: SessionStart and PreToolUse reminders
• Skills: collab-start for full initialization
• Commands: /session-collab:status and /session-collab:end

Option 2: MCP Server Only

Add to your ~/.claude.json:

{
  "mcpServers": {
    "session-collab": {
      "command": "npx",
      "args": ["-y", "session-collab-mcp@latest"]
    }
  }
}

Option 3: Global Installation

npm install -g session-collab-mcp

Features

Automatic Session Management

Once installed, Claude will:

1. Register a session when conversation starts
2. Check for conflicts before editing files
3. Warn you if another session is working on the same files
4. Clean up when the conversation ends

Symbol-Level Claims

Fine-grained conflict detection at the function/class level:

Session A claims: validateToken() in auth.ts
Session B wants: refreshToken() in auth.ts
Result: No conflict! Different symbols in same file.

LSP Integration

Works with Claude Code's LSP tools for:

• Accurate symbol validation (no typos in claims)
• Impact analysis (know which files reference your changes)
• Smart prioritization (focus on low-impact changes first)

Conflict Handling Modes

Configure behavior with collab_config:

| Mode | Behavior | |------|----------| | strict | Always ask user, never bypass | | smart (default) | Auto-proceed with safe content, ask for blocked | | bypass | Proceed despite conflicts (warn only) |

Auto-Release Options

| Option | Default | Description | |--------|---------|-------------| | auto_release_immediate | false | Auto-release claims after Edit/Write | | auto_release_stale | false | Auto-release claims exceeding threshold | | stale_threshold_hours | 2 | Hours before claim is considered stale | | auto_release_delay_minutes | 5 | Grace period for stale release |

MCP Tools Reference

Session Management

| Tool | Purpose | |------|---------| | collab_session_start | Register a new session | | collab_session_end | End session and release all claims | | collab_session_list | List active sessions | | collab_session_heartbeat | Update session heartbeat | | collab_status_update | Share current work status | | collab_config | Configure conflict handling mode |

Claims (File/Symbol Locking)

| Tool | Purpose | |------|---------| | collab_claim | Reserve files or symbols before modifying | | collab_check | Check if files/symbols are claimed by others | | collab_release | Release claimed files/symbols | | collab_auto_release | Auto-release claims after editing a file | | collab_claims_list | List all WIP claims |

Inter-Session Communication

| Tool | Purpose | |------|---------| | collab_message_send | Send message to other sessions | | collab_message_list | Read messages |

Architectural Decisions

| Tool | Purpose | |------|---------| | collab_decision_add | Record design decisions | | collab_decision_list | View recorded decisions |

LSP Integration (Advanced)

| Tool | Purpose | |------|---------| | collab_analyze_symbols | Analyze LSP symbols for conflict detection | | collab_validate_symbols | Validate symbol names before claiming | | collab_store_references | Store LSP reference data for impact tracking | | collab_impact_analysis | Analyze impact of modifying a symbol |

Usage Examples

Basic Workflow

# Session A starts working
collab_session_start(project_root="/my/project", name="feature-auth")
collab_claim(files=["src/auth.ts"], intent="Adding JWT support")

# Session B checks before editing
collab_check(files=["src/auth.ts"])
# Result: "src/auth.ts is being worked on by 'feature-auth' - Adding JWT support"

# Session A finishes
collab_release(claim_id="...", status="completed", summary="Added JWT validation")

Symbol-Level Claims

# Claim specific functions only
collab_claim(
  symbols=[{file: "src/auth.ts", symbols: ["validateToken", "refreshToken"]}],
  intent="Refactoring token validation"
)

# Other sessions can still work on other functions in the same file

Impact Analysis

# Before modifying a widely-used function
collab_impact_analysis(file="src/utils.ts", symbol="formatDate")
# Result: {
#   risk_level: "high",
#   reference_count: 15,
#   affected_files: ["src/api/...", "src/components/..."],
#   message: "HIGH RISK: This symbol is referenced in 15 locations"
# }

Data Storage

All data is stored locally in ~/.claude/session-collab/collab.db (SQLite).

• No remote server required
• No API token needed
• Works offline
• Uses WAL mode for multi-process safety

Development

Prerequisites

• Node.js 18+
• npm or yarn

Setup

npm install
npm run build

Scripts

npm run build        # Build with tsup
npm run start        # Start the MCP server
npm run start:dev    # Start in development mode
npm run typecheck    # Run TypeScript type checking
npm run lint         # Run ESLint
npm run test         # Run tests with Vitest

Project Structure

session-collab-mcp/
├── bin/                    # Executable entry point
├── migrations/             # SQLite migration files
│   ├── 0001_init.sql           # Core tables
│   ├── 0002_session_status.sql # Session status
│   ├── 0003_config.sql         # Session config
│   ├── 0004_symbols.sql        # Symbol-level claims
│   ├── 0005_references.sql     # Reference tracking
│   ├── 0006_composite_indexes.sql # Query optimization
│   ├── 0007_priority.sql       # Claim priority
│   ├── 0008_history.sql        # Audit history
│   ├── 0009_queue.sql          # Claim queue
│   ├── 0010_notifications.sql  # Notifications
│   └── 0011_working_memory.sql # Working memory & plan protection
├── plugin/                 # Claude Code Plugin
│   ├── .claude-plugin/
│   │   ├── plugin.json         # Plugin manifest
│   │   └── marketplace.json    # Marketplace config
│   ├── .mcp.json               # MCP server config
│   ├── hooks/
│   │   └── hooks.json          # Automated hooks
│   ├── skills/
│   │   └── collab-start/       # Session init skill
│   │       └── SKILL.md
│   ├── commands/
│   │   ├── status.md           # /session-collab:status
│   │   └── end.md              # /session-collab:end
│   └── README.md
├── src/
│   ├── cli.ts             # CLI entry point
│   ├── constants.ts       # Version and server instructions
│   ├── db/                # Database layer
│   │   ├── queries.ts     # SQL queries
│   │   ├── sqlite-adapter.ts
│   │   └── types.ts       # Type definitions
│   ├── mcp/               # MCP protocol implementation
│   │   ├── protocol.ts    # JSON-RPC handling
│   │   ├── server.ts      # Main MCP server
│   │   └── tools/         # Tool implementations
│   │       ├── session.ts # Session management
│   │       ├── claim.ts   # File/symbol claims
│   │       ├── message.ts # Inter-session messaging
│   │       ├── decision.ts# Decision logging
│   │       └── lsp.ts     # LSP integration
│   └── utils/
│       ├── crypto.ts      # Hash utilities
│       └── response.ts    # Shared response builders
└── package.json

Changelog

v0.8.0

• Add working memory system for context persistence (collab_memory_* tools)
• Add plan protection (collab_plan_register, collab_plan_update_status)
• Add file protection (collab_file_register, collab_file_check_protected)
• Memory categories: finding, decision, state, todo, important, context
• Pinned memories survive context compaction
• Plan lifecycle: draft → approved → in_progress → completed → archived

v0.7.1

• Add collab_auto_release tool for releasing claims after editing
• Add auto-release config options: auto_release_immediate, auto_release_stale
• Add cleanupStaleClaims() for automatic stale claim cleanup
• Add PostToolUse hook to remind auto-release after Edit/Write

v0.7.0

• Add priority system for claims (0-100 with levels: critical/high/normal/low)
• Add claim queue system (collab_queue_join, collab_queue_leave, collab_queue_list)
• Add notification system (collab_notifications_list, collab_notifications_mark_read)
• Add audit history tracking (collab_history_list)
• Add collab_claim_update_priority for escalating urgent work

v0.6.0

• Optimize database queries with composite indexes
• Extract shared utilities (crypto, response builders)
• Remove unused auth and token modules
• Use precompiled JS for 15x faster startup
• Fix GROUP_CONCAT delimiter for multi-value queries
• Add unified Zod validation across tools

v0.5.0

• Add reference tracking and impact analysis (Phase 3)
• Add symbol-level claims and LSP integration
• Fix SQLite WAL sync for multi-process MCP servers
• Add collab_config tool for conflict handling modes

License

MIT