session-collab-mcp 2.0.2 → 2.2.0

package/README.md

@@ -3,11 +3,11 @@
 [![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.
+A provider-agnostic Model Context Protocol (MCP) server that prevents conflicts when multiple agent sessions work on the same codebase simultaneously.
 
 ## Problem
 
-When using parallel Claude Code sessions or the parallel-dev workflow:
+When using parallel coding-agent sessions or multi-agent workflows:
 
 - Session A is refactoring some code
 - Session B doesn't know and thinks the code "has issues" - deletes or reverts it
@@ -25,29 +25,20 @@ Session Collab MCP provides a **Work-in-Progress (WIP) Registry** that allows se
 4. **Protect** - Guard critical files from accidental changes
 5. **Release** - Free files when done
 
-## Installation
+## Positioning
 
-### Option 1: Claude Code Plugin (Recommended)
+`session-collab-mcp` has two layers:
 
-Install as a Claude Code plugin for automatic MCP server setup, hooks, and skills:
+- **Core server**: provider-agnostic MCP server over stdio or HTTP JSON-RPC
+- **Optional integrations**: provider-specific packaging such as the Claude Code plugin in [`plugin/`](plugin/)
 
-```bash
-# Add marketplace
-/plugin marketplace add leaf76/session-collab-mcp
-
-# Install plugin
-/plugin install session-collab@session-collab-plugins
-```
+The core server should be the default mental model. Claude Code is one integration target, not the product boundary.
 
-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`
+## Installation
 
-### Option 2: MCP Server Only
+### Option 1: Generic MCP Client over stdio
 
-Add to your `~/.claude.json`:
+Use this with any MCP client that can launch a local stdio server:
 
 ```json
 {
@@ -60,7 +51,43 @@ Add to your `~/.claude.json`:
 }
 ```
 
-### Option 3: Global Installation
+The exact config wrapper depends on your MCP client, but the server contract is the same.
+
+### Option 2: HTTP Server + CLI
+
+Use this when your client prefers MCP over HTTP JSON-RPC or when you want a generic shell-friendly wrapper:
+
+```bash
+# Start HTTP server
+session-collab-http --host 127.0.0.1 --port 8765
+
+# CLI wrapper (convenience REST client)
+session-collab health
+session-collab tools
+session-collab call --name collab_session_start --args '{"project_root":"/repo","name":"demo"}'
+```
+
+For MCP-over-HTTP clients, use `POST /mcp` with JSON-RPC requests. The `/v1/*` endpoints are a convenience REST facade for lightweight automation and shell usage.
+
+### Option 3: Claude Code Plugin (Optional Integration)
+
+Install as a Claude Code plugin only if Claude Code is your MCP client and you want automatic server setup, hooks, and skills:
+
+```bash
+# 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, Stop, and PreCompact reminders
+- **Skills**: `collab-start` for full initialization
+- **Commands**: `/session-collab:status` and `/session-collab:end`
+
+### Option 4: Global Installation
 
 ```bash
 npm install -g session-collab-mcp
@@ -68,14 +95,15 @@ npm install -g session-collab-mcp
 
 ## Features
 
-### Automatic Session Management
+### Guided Session Workflow
 
-Once installed, Claude will:
+The MCP tools give you a stable collaboration workflow across providers:
 
-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
+1. Start a session with `collab_session_start`
+2. Check files with `collab_claim(action="check")`
+3. Reserve files with `collab_claim(action="create")`
+4. Save important context with `collab_memory_save`
+5. End the session with `collab_session_end`
 
 ### Working Memory
 
@@ -90,11 +118,11 @@ Context persistence that survives context compaction:
 
 ### File Protection
 
-Guard critical files from accidental changes:
+Guard important plan files or created files from accidental deletion:
 
-- Register protected files with reasons and priorities
-- Automatic conflict detection for protected files
-- Configurable protection levels
+- Register a protected plan with `collab_protect(action="register", type="plan", ...)`
+- Register a created file with `collab_protect(action="register", type="file", ...)`
+- Check protection status before deleting or replacing a file
 
 ### Conflict Handling Modes
 
@@ -117,7 +145,7 @@ Configure behavior with `collab_config`:
 
 ## MCP Tools Reference
 
-### Session Management (4 tools)
+### Session Management (5 tools)
 
 | Tool | Purpose |
 |------|---------|
@@ -125,12 +153,13 @@ Configure behavior with `collab_config`:
 | `collab_session_end` | End session and release all claims |
 | `collab_session_list` | List active sessions |
 | `collab_config` | Configure session behavior |
+| `collab_status` | Get session status summary |
 
 ### Claims (1 unified tool)
 
 | Tool | Actions |
 |------|---------|
-| `collab_claim` | `create`, `check`, `release`, `list` |
+| `collab_claim` | `create`, `check`, `release`, `list` (check: `exclude_self` defaults to true) |
 
 ### Working Memory (3 tools)
 
@@ -152,6 +181,34 @@ Configure behavior with `collab_config`:
 |------|---------|
 | `collab_status` | Unified session status |
 
+### HTTP API (v1)
+
+`/v1/*` endpoints map 1:1 to MCP tools and return JSON responses with `trace_id` on failures:
+
+- `POST /v1/sessions/start` → `collab_session_start`
+- `POST /v1/sessions/end` → `collab_session_end`
+- `GET /v1/sessions` → `collab_session_list`
+- `POST /v1/config` → `collab_config`
+- `GET /v1/status` → `collab_status`
+- `POST /v1/claims` → `collab_claim` (create)
+- `POST /v1/claims/check` → `collab_claim` (check)
+- `POST /v1/claims/release` → `collab_claim` (release)
+- `GET /v1/claims` → `collab_claim` (list)
+- `POST /v1/memory/save` → `collab_memory_save`
+- `POST /v1/memory/recall` → `collab_memory_recall`
+- `POST /v1/memory/clear` → `collab_memory_clear`
+- `POST /v1/protect/register` → `collab_protect` (register)
+- `POST /v1/protect/check` → `collab_protect` (check)
+- `GET /v1/protect/list` → `collab_protect` (list)
+- `POST /v1/tools/call` / `GET /v1/tools` (generic access)
+
+### MCP over HTTP
+
+- `POST /mcp` accepts JSON-RPC `initialize`, `tools/list`, and `tools/call` requests
+- `GET /mcp` currently returns a clear "stream not supported" response instead of pretending to be full Streamable HTTP SSE
+- Localhost binds enforce Host and Origin validation
+- Non-local binds require both `SESSION_COLLAB_HTTP_TOKEN` and an allowed-host list via `SESSION_COLLAB_ALLOWED_HOSTS` or repeated `--allowed-host`
+
 ## Usage Examples
 
 ### Basic Workflow
@@ -159,14 +216,17 @@ Configure behavior with `collab_config`:
 ```bash
 # Session A starts working
 collab_session_start(project_root="/my/project", name="feature-auth")
-collab_claim(action="create", files=["src/auth.ts"], intent="Adding JWT support")
+collab_claim(session_id="session-a", action="create", files=["src/auth.ts"], intent="Adding JWT support")
 
 # Session B checks before editing
-collab_claim(action="check", files=["src/auth.ts"])
+collab_claim(session_id="session-b", action="check", files=["src/auth.ts"])
 # Result: "CONFLICT: src/auth.ts is claimed by 'feature-auth'"
 
+# If you want to include your own claims in the check
+collab_claim(session_id="session-a", action="check", files=["src/auth.ts"], exclude_self=false)
+
 # Session A finishes
-collab_claim(action="release", claim_id="...")
+collab_claim(session_id="session-a", action="release", claim_id="...")
 ```
 
 ### Working Memory
@@ -174,6 +234,7 @@ collab_claim(action="release", claim_id="...")
 ```bash
 # Save a finding
 collab_memory_save(
+  session_id="abc123",
   category="finding",
   key="auth_bug_root_cause",
   content="Missing token validation in refresh flow",
@@ -181,26 +242,29 @@ collab_memory_save(
 )
 
 # Recall active memories
-collab_memory_recall(active=true, priority_threshold=70)
+collab_memory_recall(session_id="abc123", active=true)
 ```
 
 ### File Protection
 
 ```bash
-# Protect critical file
+# Protect a plan document
 collab_protect(
   action="register",
-  file_path="src/core/auth.ts",
-  reason="Core authentication logic",
-  priority=95
+  session_id="abc123",
+  type="plan",
+  file_path="docs/feature-plan.md",
+  title="Feature plan",
+  content_summary="Steps, risks, and rollout notes"
 )
 
 # Check before editing
 collab_protect(
   action="check",
-  file_paths=["src/core/auth.ts"]
+  session_id="abc123",
+  file_path="docs/feature-plan.md"
 )
-# Result: "BLOCKED: File is protected - Core authentication logic"
+# Result: "Protected (plan). Confirm before deleting."
 ```
 
 ### Status Monitoring
@@ -211,7 +275,7 @@ collab_status(session_id="abc123")
 # Result: {
 #   session: { id: "abc123", name: "feature-auth", status: "active" },
 #   claims: [...],
-#   active_memories: 5,
+#   other_sessions: 1,
 #   message: "Session active. 2 claim(s), 5 memories."
 # }
 ```
@@ -222,7 +286,7 @@ Version 2.0 introduces breaking changes with a simplified API. See [MIGRATION.md
 
 ### Key Changes
 
-- **Tool Consolidation**: 50+ tools → 9 core tools
+- **Tool Consolidation**: 50+ tools → 10 core tools
 - **Action-Based Interface**: Single tools with multiple actions
 - **Simplified Responses**: Cleaner, flatter response formats
 - **Removed Features**: LSP integration, messaging, notifications, queuing
@@ -232,7 +296,8 @@ Version 2.0 introduces breaking changes with a simplified API. See [MIGRATION.md
 All data is stored locally in `~/.claude/session-collab/collab.db` (SQLite).
 
 - No remote server required
-- No API token needed
+- Localhost HTTP usage works without an API token
+- Non-local HTTP binds require `SESSION_COLLAB_HTTP_TOKEN`
 - Works offline
 - Uses WAL mode for multi-process safety
 
@@ -250,6 +315,16 @@ npm install
 npm run build
 ```
 
+### Legacy Build (Optional)
+
+Legacy schemas/queries are kept out of the default bundle. To include a legacy entry for compatibility:
+
+```bash
+SESSION_COLLAB_INCLUDE_LEGACY=true npm run build
+```
+
+Maintenance note: legacy exports are for backward compatibility only and are not exposed in the v2 tool list.
+
 ### Scripts
 
 ```bash
@@ -261,13 +336,25 @@ npm run lint         # Run ESLint
 npm run test         # Run tests with Vitest
 ```
 
+### HTTP Integration Tests
+
+HTTP integration tests require a local listen port. Enable them with:
+
+```bash
+SESSION_COLLAB_HTTP_TESTS=true npx vitest run src/http/__tests__/server-integration.test.ts
+```
+
+### Historical Notes
+
+The changelog entries below document historical milestones, including tools and workflows that were removed before the current v2 API. Treat the tool tables and examples above as the source of truth for the current public surface.
+
 ### Project Structure
 
 ```
 session-collab-mcp/
 ├── bin/                    # Executable entry point
 ├── migrations/             # SQLite migration files
-├── plugin/                 # Claude Code Plugin
+├── plugin/                 # Optional Claude Code integration
 ├── src/
 │   ├── cli.ts             # CLI entry point
 │   ├── constants.ts       # Version and server instructions
@@ -285,9 +372,17 @@ session-collab-mcp/
 
 ## Changelog
 
+### v2.1.0
+
+- Add HTTP server + CLI wrapper for universal AI CLI usage
+- Add HTTP API endpoints and utils tests
+- Add legacy entry for deprecated schemas/queries (optional build)
+- Improve claim conflict accuracy and release summaries
+- Expand test coverage across MCP tools and DB flows
+
 ### v2.0.0 (Breaking)
 
-- **Major Simplification**: Reduced from 50+ tools to 9 core tools
+- **Major Simplification**: Reduced from 50+ tools to 10 core tools
 - **Action-Based Design**: Unified tools with action parameters
 - **Removed Features**: LSP integration, messaging, notifications, queuing, decision tracking
 - **Improved Performance**: Faster startup and reduced complexity

package/bin/session-collab

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const cli = join(__dirname, '..', 'dist', 'http', 'client-cli.js');
+
+import(cli).catch((err) => {
+  console.error('Failed to start:', err.message);
+  process.exit(1);
+});

package/bin/session-collab-http

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const cli = join(__dirname, '..', 'dist', 'http', 'cli.js');
+
+import(cli).catch((err) => {
+  console.error('Failed to start:', err.message);
+  process.exit(1);
+});