# Clone the repository
git clone https://github.com/jonburchel/mcp-session-coordinator.git
cd mcp-session-coordinator

# Install dependencies
npm install

# Build
npm run build

{
  "mcpServers": {
    "session-coordinator": {
      "command": "node",
      "args": ["F:/home/mcp-session-coordinator/dist/index.js"],
      "env": {}
    }
  }
}

{
  "mcpServers": {
    "session-coordinator": {
      "command": "node",
      "args": ["/path/to/mcp-session-coordinator/dist/index.js"]
    }
  }
}

1. Register your session
   → session_register(name="feature-auth", project="my-app", branch="feature/auth")
   ← { session_id: "abc-123", status: "registered" }

2. Before editing a file, acquire a lock
   → lock_acquire(session_id="abc-123", file_path="src/auth.ts")
   ← { granted: true, lock_type: "exclusive" }

3. Announce your intent
   → intent_announce(session_id="abc-123", intent_type="file_edit", target="src/auth.ts")
   ← { intent_id: "int-456", status: "announced" }

4. After editing, release the lock
   → lock_release(session_id="abc-123", file_path="src/auth.ts")
   ← { released: true }

5. Before committing, check for conflicts
   → conflict_check(session_id="abc-123", intent_type="git_commit")
   ← { conflicts: [], safe_to_proceed: true }

6. When finished, deregister
   → session_deregister(session_id="abc-123")
   ← { status: "deregistered", locks_released: 0 }

Session A registers:
  → session_register(name="auth-implementation", project="my-app", branch="feature/auth")
  ← { session_id: "session-A" }

Session B registers:
  → session_register(name="profile-page", project="my-app", branch="feature/profile")
  ← { session_id: "session-B" }

Session A locks the user model:
  → lock_acquire(session_id="session-A", file_path="src/models/user.ts", lock_type="exclusive")
  ← { granted: true }

Session B tries to edit the same file:
  → lock_acquire(session_id="session-B", file_path="src/models/user.ts", lock_type="exclusive")
  ← { granted: false, held_by: "session-A", holder_name: "auth-implementation" }

Session B sends a message to Session A:
  → message_send(
      from_session="session-B",
      to_session="session-A",
      channel="coordination",
      content="I need to add a 'bio' field to the User model. Can you include it in your changes?"
    )

Session A sees the message and responds:
  → message_send(
      from_session="session-A",
      to_session="session-B",
      channel="coordination",
      content="Done! Added 'bio: string' to the User interface. Releasing lock now."
    )

Session A releases the lock:
  → lock_release(session_id="session-A", file_path="src/models/user.ts")

Session B can now proceed:
  → lock_acquire(session_id="session-B", file_path="src/models/user.ts", lock_type="shared")
  ← { granted: true }

Session A discovers something:
  → context_share(
      session_id="session-A",
      context_type="discovery",
      project="my-app",
      content="The auth module uses JWT tokens (not sessions). Tokens are stored in
               httpOnly cookies, not localStorage. See src/auth/jwt.ts for the implementation."
    )

Later, Session B queries for relevant context:
  → context_query(project="my-app", context_type="discovery")
  ← [
      {
        content: "The auth module uses JWT tokens (not sessions)...",
        shared_by: "auth-implementation",
        context_type: "discovery"
      }
    ]

Session B can also search by keyword:
  → context_query(project="my-app", keyword="auth")
  ← [ ...matching context entries... ]

Session A is about to rebase:
  → intent_announce(
      session_id="session-A",
      intent_type="git_rebase",
      target="feature/auth",
      description="Rebasing feature/auth onto latest main"
    )

Session B checks before pushing:
  → conflict_check(session_id="session-B", intent_type="git_push")
  ← {
      conflicts: [{
        type: "git_operation",
        description: "Session 'auth-implementation' is currently rebasing branch feature/auth",
        severity: "high"
      }],
      safe_to_proceed: false
    }

Session B waits. Session A finishes and clears the intent:
  → intent_clear(session_id="session-A", intent_id="int-789")

┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│  AI Session  │  │  AI Session  │  │  AI Session  │
│  (Copilot)   │  │  (Copilot)   │  │  (Claude)    │
└──────┬───────┘  └──────┬───────┘  └──────┬───────┘
       │                 │                 │
       │     MCP Protocol (stdio)          │
       │                 │                 │
       ▼                 ▼                 ▼
┌─────────────────────────────────────────────────┐
│           MCP Session Coordinator               │
│                                                 │
│  ┌───────────┐ ┌──────────┐ ┌───────────────┐  │
│  │  Session   │ │   Lock   │ │    Intent     │  │
│  │  Manager   │ │  Manager │ │   Broadcaster │  │
│  └───────────┘ └──────────┘ └───────────────┘  │
│  ┌───────────┐ ┌──────────┐ ┌───────────────┐  │
│  │  Message   │ │ Conflict │ │    Context    │  │
│  │  Router    │ │ Detector │ │    Store      │  │
│  └───────────┘ └──────────┘ └───────────────┘  │
│                                                 │
│  ┌─────────────────────────────────────────┐    │
│  │         SQLite (WAL mode)               │    │
│  │    ~/.mcp-session-coordinator/db        │    │
│  └─────────────────────────────────────────┘    │
└─────────────────────────────────────────────────┘