session-collab-mcp: Instructions file for Claude Code

AGENTS.md - Session Collab MCP

Generated: 2026-01-03 | Branch: master

Overview

TypeScript MCP server. 10 tools (v2 action-based). Local SQLite WIP registry for same-machine multi-session claims — not a remote lock.

Structure

src/
├── cli.ts              # Entry: stdio JSON-RPC server
├── constants.ts        # Version + short server instructions
├── hooks/              # Claude Code PreToolUse claim guard
├── db/
│   ├── db-path.ts      # SESSION_COLLAB_DB + modern/legacy paths
│   ├── queries.ts      # SQL (still monolithic; split later)
│   ├── sqlite-adapter.ts
│   ├── types.ts        # All type definitions
│   └── __tests__/      # In-memory SQLite tests
├── mcp/
│   ├── protocol.ts     # JSON-RPC types
│   ├── schemas.ts      # Zod validation (all inputs)
│   ├── server.ts       # Tool routing by prefix
│   └── tools/          # 4 files, 10 MCP tools ← see tools/AGENTS.md
├── utils/
│   ├── crypto.ts       # generateId()
│   └── response.ts     # errorResponse(), successResponse()
├── migrations/         # 12 SQL files, versioned schema
└── plugin/             # Claude Code plugin (hooks, skills, commands)

Where to Look

Task	Location
Add MCP tool	src/mcp/tools/ + register in server.ts
Add schema	src/mcp/schemas.ts (Zod)
Add DB query	src/db/queries.ts
Add type	src/db/types.ts
Error codes	src/utils/response.ts → ERROR_CODES
Test pattern	src/db/__tests__/test-helper.ts

Commands

npm run build        # tsup (bundles all except better-sqlite3)
npm run typecheck    # tsc --noEmit (strict, noUnusedLocals)
npm run lint         # eslint
npm run test         # vitest

# Single test
npx vitest run src/db/__tests__/queries.test.ts
npx vitest run -t "should create a new session"

Conventions

Imports (ESM, .js required)

import type { DatabaseAdapter } from '../db/sqlite-adapter.js';  // Types first
import { createClaim } from '../db/queries.js';                   // Values second