session-collab-mcp 0.4.7 → 0.5.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,254 @@
+# Session Collab MCP
+
+[![npm version](https://img.shields.io/npm/v/session-collab-mcp.svg)](https://www.npmjs.com/package/session-collab-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+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
+
+### Zero-Config Setup
+
+Add to your `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "session-collab": {
+      "command": "npx",
+      "args": ["-y", "session-collab-mcp@latest"]
+    }
+  }
+}
+```
+
+That's it! The MCP server includes built-in instructions that Claude follows automatically.
+
+### Manual Installation
+
+```bash
+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) |
+
+## 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_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
+
+```bash
+npm install
+npm run build
+```
+
+### Scripts
+
+```bash
+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_auth.sql           # Auth tables
+│   ├── 0002_session_status.sql # Session status
+│   ├── 0003_config.sql         # Session config
+│   ├── 0004_symbols.sql   # Symbol-level claims
+│   └── 0005_references.sql # Reference tracking
+├── src/
+│   ├── cli.ts             # CLI entry point
+│   ├── constants.ts       # Version and constants
+│   ├── db/                # Database layer
+│   │   ├── queries.ts     # SQL queries
+│   │   └── sqlite-adapter.ts
+│   ├── 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/
+└── package.json
+```
+
+## Changelog
+
+### 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

package/migrations/0004_symbols.sql

@@ -0,0 +1,18 @@
+-- Symbol-level claim tracking for fine-grained conflict detection
+-- Allows claiming specific functions/classes instead of entire files
+
+CREATE TABLE IF NOT EXISTS claim_symbols (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    claim_id TEXT NOT NULL,
+    file_path TEXT NOT NULL,
+    symbol_name TEXT NOT NULL,
+    symbol_type TEXT DEFAULT 'function' CHECK (symbol_type IN ('function', 'class', 'method', 'variable', 'block', 'other')),
+    created_at TEXT DEFAULT (datetime('now')),
+    FOREIGN KEY (claim_id) REFERENCES claims(id) ON DELETE CASCADE,
+    UNIQUE(claim_id, file_path, symbol_name)
+);
+
+CREATE INDEX IF NOT EXISTS idx_claim_symbols_path ON claim_symbols(file_path);
+CREATE INDEX IF NOT EXISTS idx_claim_symbols_name ON claim_symbols(symbol_name);
+CREATE INDEX IF NOT EXISTS idx_claim_symbols_claim ON claim_symbols(claim_id);
+CREATE INDEX IF NOT EXISTS idx_claim_symbols_lookup ON claim_symbols(file_path, symbol_name);

package/migrations/0005_references.sql

@@ -0,0 +1,19 @@
+-- Symbol reference tracking for impact analysis
+-- Stores which symbols are referenced by which files
+
+CREATE TABLE IF NOT EXISTS symbol_references (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    source_file TEXT NOT NULL,
+    source_symbol TEXT NOT NULL,
+    ref_file TEXT NOT NULL,
+    ref_line INTEGER,
+    ref_context TEXT,
+    session_id TEXT NOT NULL,
+    created_at TEXT DEFAULT (datetime('now')),
+    FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE,
+    UNIQUE(source_file, source_symbol, ref_file, ref_line)
+);
+
+CREATE INDEX IF NOT EXISTS idx_symbol_refs_source ON symbol_references(source_file, source_symbol);
+CREATE INDEX IF NOT EXISTS idx_symbol_refs_ref_file ON symbol_references(ref_file);
+CREATE INDEX IF NOT EXISTS idx_symbol_refs_session ON symbol_references(session_id);

package/migrations/0006_composite_indexes.sql

@@ -0,0 +1,14 @@
+-- Add composite indexes for common query patterns
+-- These indexes optimize queries that filter on multiple columns
+
+-- Sessions: frequently query active sessions with heartbeat check
+-- Used in cleanupStaleSessions and session list queries
+CREATE INDEX IF NOT EXISTS idx_sessions_status_heartbeat ON sessions(status, last_heartbeat);
+
+-- Claims: frequently query active claims for a session
+-- Used in checkConflicts and listClaims
+CREATE INDEX IF NOT EXISTS idx_claims_status_session ON claims(status, session_id);
+
+-- Claim files: composite for efficient conflict checking
+-- Used in checkConflicts with JOIN on claims
+CREATE INDEX IF NOT EXISTS idx_claim_files_path_claim ON claim_files(file_path, claim_id);

package/package.json

@@ -1,7 +1,16 @@
 {
   "name": "session-collab-mcp",
-  "version": "0.4.7",
+  "version": "0.5.2",
   "description": "MCP server for Claude Code session collaboration - prevents conflicts between parallel sessions",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "claude",
+    "claude-code",
+    "collaboration",
+    "session",
+    "conflict-prevention"
+  ],
   "type": "module",
   "bin": {
     "session-collab-mcp": "./bin/session-collab-mcp"

package/src/cli.ts

@@ -19,6 +19,9 @@ function loadMigrations(): string[] {
     readFileSync(join(migrationsDir, '0001_init.sql'), 'utf-8'),
     readFileSync(join(migrationsDir, '0002_auth.sql'), 'utf-8'),
     readFileSync(join(migrationsDir, '0003_config.sql'), 'utf-8'),
+    readFileSync(join(migrationsDir, '0004_symbols.sql'), 'utf-8'),
+    readFileSync(join(migrationsDir, '0005_references.sql'), 'utf-8'),
+    readFileSync(join(migrationsDir, '0006_composite_indexes.sql'), 'utf-8'),
   ];
 }
 

package/src/constants.ts

@@ -32,44 +32,179 @@ This MCP server coordinates multiple Claude Code sessions working on the same co
 
 2. **Before editing any file**: Call \`collab_check\` with the file path to verify no conflicts
 
-3. **If conflicts detected** (DEFAULT: coordinate):
-   - Show warning to user with options:
-     a) **Coordinate** (default): Send message to other session via \`collab_message_send\`, wait for response
-     b) **Bypass**: Proceed anyway (warn about potential conflicts)
-     c) **Request release**: Ask owner to release if claim seems stale
-   - NEVER auto-release another session's claim without explicit user permission
+3. **Follow the \`recommendation\` from collab_check automatically**:
+   - \`proceed_all\`: All files/symbols safe. Edit them without asking user.
+   - \`proceed_safe_only\`: Some content blocked. Edit ONLY safe files/symbols, skip blocked. No need to ask user.
+   - \`abort\`: All content blocked. Inform user and suggest coordination.
 
-4. **For significant changes**: Call \`collab_claim\` before starting work on files
+4. **For significant changes**: Call \`collab_claim\` before starting work
 
-5. **When done with files**: Call \`collab_release\` with YOUR session_id to free them
+5. **When done**: Call \`collab_release\` with YOUR session_id to free them
 
 6. **On conversation end**: Call \`collab_session_end\` to clean up
 
+## Symbol-Level Claims (Fine-Grained)
+
+Use symbol-level claims when modifying specific functions/classes, allowing other sessions to work on different parts of the same file.
+
+**Claim specific symbols:**
+\`\`\`json
+{
+  "symbols": [
+    { "file": "src/auth.ts", "symbols": ["validateToken", "refreshToken"] }
+  ],
+  "intent": "Refactoring token validation"
+}
+\`\`\`
+
+**Check specific symbols:**
+\`\`\`json
+{
+  "files": ["src/auth.ts"],
+  "symbols": [
+    { "file": "src/auth.ts", "symbols": ["validateToken"] }
+  ]
+}
+\`\`\`
+
+**Conflict levels:**
+- \`file\`: Whole file is claimed (no symbols specified)
+- \`symbol\`: Only specific functions/classes are claimed
+
+**Example scenario:**
+- Session A claims \`validateToken\` in auth.ts
+- Session B wants to modify \`refreshToken\` in auth.ts
+- → No conflict! Session B can proceed.
+
+## Auto-Decision Rules
+
+When \`collab_check\` returns:
+- \`can_edit: true\` → Proceed with safe content automatically
+- \`can_edit: false\` → Stop and inform user about blocked content
+
+For symbol-level checks, use \`symbol_status.safe\` and \`symbol_status.blocked\`.
+
 ## Permission Rules
 
 - You can ONLY release claims that belong to YOUR session
 - To release another session's claim, you must ask the user and they must explicitly confirm
 - Use \`force=true\` in \`collab_release\` only after user explicitly confirms
-- When user chooses "coordinate", send a message first and suggest waiting
 
 ## Conflict Handling Modes
 
 Configure your session behavior with \`collab_config\`:
 
 - **"strict"**: Always ask user, never bypass or auto-release
-- **"smart"** (default): Ask user, but suggest auto-release for stale claims (>2hr old)
+- **"smart"** (default): Auto-proceed with safe content, ask for blocked
 - **"bypass"**: Proceed despite conflicts (just warn, don't block)
 
-Config options:
-- \`mode\`: strict | smart | bypass
-- \`allow_release_others\`: Allow releasing other sessions' claims (default: false)
-- \`auto_release_stale\`: Auto-release stale claims (default: false)
-- \`stale_threshold_hours\`: Hours before claim is stale (default: 2)
+## LSP Integration (Advanced)
+
+For precise symbol validation and impact analysis, use LSP tools:
+
+### Workflow with LSP
+
+1. **Get symbols from LSP**: Use \`LSP.documentSymbol\` to get actual symbols in a file
+2. **Validate before claiming**: Use \`collab_validate_symbols\` to verify symbol names
+3. **Analyze conflicts with context**: Use \`collab_analyze_symbols\` for enhanced conflict detection
+
+### collab_validate_symbols
+
+Validate symbol names exist before claiming:
+
+\`\`\`
+1. Claude: LSP.documentSymbol("src/auth.ts")
+2. Claude: collab_validate_symbols({
+     file: "src/auth.ts",
+     symbols: ["validateToken", "refreshTokne"],  // typo!
+     lsp_symbols: [/* LSP output */]
+   })
+3. Response: { invalid_symbols: ["refreshTokne"], suggestions: { "refreshTokne": ["refreshToken"] } }
+\`\`\`
+
+### collab_analyze_symbols
+
+Enhanced conflict detection with LSP data:
+
+\`\`\`
+1. Claude: LSP.documentSymbol("src/auth.ts")
+2. Claude: LSP.findReferences("validateToken")
+3. Claude: collab_analyze_symbols({
+     session_id: "...",
+     files: [{ file: "src/auth.ts", symbols: [/* LSP symbols */] }],
+     references: [{ symbol: "validateToken", file: "src/auth.ts", references: [...] }]
+   })
+4. Response: {
+     can_edit: true,
+     recommendation: "proceed_safe_only",
+     symbols: [
+       { name: "validateToken", conflict_status: "blocked", impact: { references_count: 5, affected_files: [...] } },
+       { name: "refreshToken", conflict_status: "safe" }
+     ]
+   }
+\`\`\`
+
+### Benefits of LSP Integration
+
+- **Accurate symbol names**: No typos in claims
+- **Impact awareness**: Know which files will be affected by changes
+- **Smart prioritization**: Focus on low-impact changes first
+
+## Reference Tracking & Impact Analysis
+
+Store and query symbol references for smart conflict detection:
+
+### collab_store_references
+
+Persist LSP reference data for future impact queries:
+
+\`\`\`
+1. Claude: LSP.findReferences("validateToken")
+2. Claude: collab_store_references({
+     session_id: "...",
+     references: [{
+       source_file: "src/auth.ts",
+       source_symbol: "validateToken",
+       references: [
+         { file: "src/api/users.ts", line: 15 },
+         { file: "src/api/orders.ts", line: 23 }
+       ]
+     }]
+   })
+\`\`\`
+
+### collab_impact_analysis
+
+Check if modifying a symbol would affect files claimed by others:
+
+\`\`\`
+Claude: collab_impact_analysis({
+  session_id: "...",
+  file: "src/auth.ts",
+  symbol: "validateToken"
+})
+
+Response: {
+  risk_level: "high",
+  reference_count: 3,
+  affected_files: ["src/api/users.ts", "src/api/orders.ts"],
+  affected_claims: [{ session_name: "other-session", intent: "..." }],
+  message: "HIGH RISK: 1 active claim on referencing files"
+}
+\`\`\`
+
+### Risk Levels
+
+- **high**: Other sessions have claims on files that reference this symbol
+- **medium**: Many references (>10) but no active claims conflict
+- **low**: Few references, no conflicts
 
 ## Best Practices
 
-- Claim files early, release when done
-- Use descriptive intents when claiming (e.g., "Refactoring auth module")
-- Check for messages periodically with \`collab_message_list\`
-- Record architectural decisions with \`collab_decision_add\`
+- **Prefer symbol-level claims** for focused changes (single function/class)
+- **Use file-level claims** for large refactors affecting many symbols
+- **Use LSP validation** when unsure about symbol names
+- **Check references** before modifying widely-used symbols
+- Claim early, release when done
+- Use descriptive intents (e.g., "Refactoring validateToken for JWT support")
 `.trim();