session-collab-mcp 0.3.0

package/src/mcp/tools/session.ts

@@ -0,0 +1,322 @@
+// Session management tools
+
+import type { D1Database } from '@cloudflare/workers-types';
+import type { McpTool, McpToolResult } from '../protocol';
+import { createToolResult } from '../protocol';
+import {
+  createSession,
+  getSession,
+  listSessions,
+  updateSessionHeartbeat,
+  updateSessionStatus,
+  endSession,
+  cleanupStaleSessions,
+  listClaims,
+} from '../../db/queries';
+import type { TodoItem } from '../../db/types';
+
+export const sessionTools: McpTool[] = [
+  {
+    name: 'collab_session_start',
+    description:
+      'Register a new collaboration session. Call this when starting work to enable coordination with other sessions.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+          description: "Optional session name, e.g., 'frontend-refactor'",
+        },
+        project_root: {
+          type: 'string',
+          description: 'Project root directory path',
+        },
+        machine_id: {
+          type: 'string',
+          description: 'Optional machine identifier for multi-machine setups',
+        },
+      },
+      required: ['project_root'],
+    },
+  },
+  {
+    name: 'collab_session_end',
+    description: 'End a session and release all its claims.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: {
+          type: 'string',
+          description: 'Session ID to end',
+        },
+        release_claims: {
+          type: 'string',
+          enum: ['complete', 'abandon'],
+          description: 'How to handle unreleased claims: complete (mark as done) or abandon',
+        },
+      },
+      required: ['session_id'],
+    },
+  },
+  {
+    name: 'collab_session_list',
+    description: 'List all active sessions. Use to see who else is working.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        include_inactive: {
+          type: 'boolean',
+          description: 'Include inactive/terminated sessions',
+        },
+        project_root: {
+          type: 'string',
+          description: 'Filter by project root',
+        },
+      },
+    },
+  },
+  {
+    name: 'collab_session_heartbeat',
+    description: 'Update session heartbeat to indicate the session is still active.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: {
+          type: 'string',
+          description: 'Session ID to update',
+        },
+        current_task: {
+          type: 'string',
+          description: 'Optional: Current task being worked on',
+        },
+        todos: {
+          type: 'array',
+          description: 'Optional: Current todo list to sync',
+          items: {
+            type: 'object',
+            properties: {
+              content: { type: 'string' },
+              status: { type: 'string', enum: ['pending', 'in_progress', 'completed'] },
+            },
+          },
+        },
+      },
+      required: ['session_id'],
+    },
+  },
+  {
+    name: 'collab_status_update',
+    description: 'Update session work status. Use this to share what you are currently working on with other sessions.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: {
+          type: 'string',
+          description: 'Your session ID',
+        },
+        current_task: {
+          type: 'string',
+          description: 'Description of current task (e.g., "Refactoring auth module")',
+        },
+        todos: {
+          type: 'array',
+          description: 'Your current todo list',
+          items: {
+            type: 'object',
+            properties: {
+              content: { type: 'string', description: 'Task description' },
+              status: { type: 'string', enum: ['pending', 'in_progress', 'completed'] },
+            },
+            required: ['content', 'status'],
+          },
+        },
+      },
+      required: ['session_id'],
+    },
+  },
+];
+
+export async function handleSessionTool(
+  db: D1Database,
+  name: string,
+  args: Record<string, unknown>,
+  userId?: string
+): Promise<McpToolResult> {
+  switch (name) {
+    case 'collab_session_start': {
+      // Cleanup stale sessions first
+      await cleanupStaleSessions(db, 30);
+
+      const session = await createSession(db, {
+        name: args.name as string | undefined,
+        project_root: args.project_root as string,
+        machine_id: args.machine_id as string | undefined,
+        user_id: userId,
+      });
+
+      const activeSessions = await listSessions(db, { project_root: args.project_root as string, user_id: userId });
+
+      return createToolResult(
+        JSON.stringify(
+          {
+            session_id: session.id,
+            name: session.name,
+            message: `Session registered. ${activeSessions.length} active session(s) in this project.`,
+            active_sessions: activeSessions.map((s) => ({
+              id: s.id,
+              name: s.name,
+              last_heartbeat: s.last_heartbeat,
+            })),
+          },
+          null,
+          2
+        )
+      );
+    }
+
+    case 'collab_session_end': {
+      const sessionId = args.session_id as string;
+      const releaseClaims = (args.release_claims as 'complete' | 'abandon') ?? 'abandon';
+
+      const session = await getSession(db, sessionId);
+      if (!session) {
+        return createToolResult(
+          JSON.stringify({ error: 'SESSION_NOT_FOUND', message: 'Session not found' }),
+          true
+        );
+      }
+
+      await endSession(db, sessionId, releaseClaims);
+
+      return createToolResult(
+        JSON.stringify({
+          success: true,
+          message: `Session ended. All claims marked as ${releaseClaims === 'complete' ? 'completed' : 'abandoned'}.`,
+        })
+      );
+    }
+
+    case 'collab_session_list': {
+      // Do not filter by user_id - collaboration tool should show all sessions
+      const sessions = await listSessions(db, {
+        include_inactive: args.include_inactive as boolean,
+        project_root: args.project_root as string | undefined,
+      });
+
+      // Get active claims count for each session and include status info
+      const sessionsWithDetails = await Promise.all(
+        sessions.map(async (session) => {
+          const claims = await listClaims(db, { session_id: session.id, status: 'active' });
+
+          // Parse progress and todos if present
+          let progress = null;
+          let todos = null;
+          try {
+            if (session.progress) progress = JSON.parse(session.progress);
+            if (session.todos) todos = JSON.parse(session.todos);
+          } catch {
+            // Ignore parse errors
+          }
+
+          return {
+            id: session.id,
+            name: session.name,
+            project_root: session.project_root,
+            status: session.status,
+            active_claims: claims.length,
+            last_heartbeat: session.last_heartbeat,
+            current_task: session.current_task,
+            progress,
+            todos,
+          };
+        })
+      );
+
+      return createToolResult(
+        JSON.stringify(
+          {
+            sessions: sessionsWithDetails,
+            total: sessionsWithDetails.length,
+          },
+          null,
+          2
+        )
+      );
+    }
+
+    case 'collab_session_heartbeat': {
+      const sessionId = args.session_id as string;
+      const currentTask = args.current_task as string | undefined;
+      const todos = args.todos as TodoItem[] | undefined;
+
+      const updated = await updateSessionHeartbeat(db, sessionId, {
+        current_task: currentTask,
+        todos,
+      });
+
+      if (!updated) {
+        return createToolResult(
+          JSON.stringify({
+            error: 'SESSION_NOT_FOUND',
+            message: 'Session not found or inactive. Please start a new session.',
+          }),
+          true
+        );
+      }
+
+      return createToolResult(
+        JSON.stringify({
+          success: true,
+          message: 'Heartbeat updated',
+          status_synced: !!(currentTask || todos),
+        })
+      );
+    }
+
+    case 'collab_status_update': {
+      const sessionId = args.session_id as string;
+      const currentTask = args.current_task as string | undefined;
+      const todos = args.todos as TodoItem[] | undefined;
+
+      // Validate session exists
+      const session = await getSession(db, sessionId);
+      if (!session || session.status !== 'active') {
+        return createToolResult(
+          JSON.stringify({
+            error: 'SESSION_INVALID',
+            message: 'Session not found or inactive.',
+          }),
+          true
+        );
+      }
+
+      await updateSessionStatus(db, sessionId, {
+        current_task: currentTask,
+        todos,
+      });
+
+      // Calculate progress for response
+      let progress = null;
+      if (todos && todos.length > 0) {
+        const completed = todos.filter((t) => t.status === 'completed').length;
+        progress = {
+          completed,
+          total: todos.length,
+          percentage: Math.round((completed / todos.length) * 100),
+        };
+      }
+
+      return createToolResult(
+        JSON.stringify({
+          success: true,
+          message: 'Status updated successfully.',
+          current_task: currentTask ?? null,
+          progress,
+        })
+      );
+    }
+
+    default:
+      return createToolResult(`Unknown session tool: ${name}`, true);
+  }
+}

package/src/tokens/generator.ts

@@ -0,0 +1,33 @@
+// API Token generator
+
+import { generateRandomBytes, bytesToHex } from '../utils/crypto';
+
+const TOKEN_PREFIX = 'mcp_';
+const TOKEN_RANDOM_BYTES = 24; // 192 bits of randomness
+
+/**
+ * Generate a new API token
+ * Format: mcp_<48 hex characters>
+ * Total length: 52 characters
+ */
+export function generateApiToken(): string {
+  const randomBytes = generateRandomBytes(TOKEN_RANDOM_BYTES);
+  const randomHex = bytesToHex(randomBytes);
+  return `${TOKEN_PREFIX}${randomHex}`;
+}
+
+/**
+ * Get token prefix for display
+ * Shows first 12 characters (mcp_ + 8 hex chars)
+ */
+export function getTokenPrefix(token: string): string {
+  return token.substring(0, 12);
+}
+
+/**
+ * Validate token format
+ */
+export function isValidTokenFormat(token: string): boolean {
+  // Must start with mcp_ and have 48 hex characters after
+  return /^mcp_[a-f0-9]{48}$/.test(token);
+}

package/src/tokens/handlers.ts

@@ -0,0 +1,113 @@
+// Token management API handlers
+
+import type { D1Database } from '@cloudflare/workers-types';
+import { z } from 'zod';
+import { generateApiToken } from './generator';
+import { createApiToken, listApiTokens, revokeApiToken } from '../db/auth-queries';
+import type { AuthContext } from '../auth/types';
+
+// Request schemas
+const CreateTokenRequestSchema = z.object({
+  name: z.string().min(1, 'Name is required').max(100, 'Name too long'),
+  scopes: z.array(z.string()).default(['mcp']),
+  expires_in_days: z.number().int().min(1).max(365).optional(),
+});
+
+interface HandlerContext {
+  db: D1Database;
+  request: Request;
+}
+
+// CORS headers
+const corsHeaders = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
+  'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+};
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json', ...corsHeaders },
+  });
+}
+
+function errorResponse(error: string, code: string, status: number, details?: { field: string; message: string }[]): Response {
+  return jsonResponse({ error, code, details }, status);
+}
+
+/**
+ * POST /tokens
+ * Create a new API token
+ */
+export async function handleCreateToken(ctx: HandlerContext, authContext: AuthContext): Promise<Response> {
+  const body = await ctx.request.json();
+  const parsed = CreateTokenRequestSchema.safeParse(body);
+
+  if (!parsed.success) {
+    const details = parsed.error.issues.map((i) => ({
+      field: i.path.join('.'),
+      message: i.message,
+    }));
+    return errorResponse('Validation failed', 'ERR_VALIDATION', 422, details);
+  }
+
+  const { name, scopes, expires_in_days } = parsed.data;
+
+  // Generate token
+  const rawToken = generateApiToken();
+
+  // Store token
+  const { token } = await createApiToken(ctx.db, {
+    user_id: authContext.userId,
+    name,
+    token: rawToken,
+    scopes,
+    expires_in_days,
+  });
+
+  // Response includes the raw token (only shown once)
+  const response = {
+    token: {
+      id: token.id,
+      name: token.name,
+      token: rawToken, // Only time raw token is returned
+      token_prefix: token.token_prefix,
+      scopes: JSON.parse(token.scopes),
+      expires_at: token.expires_at,
+      created_at: token.created_at,
+    },
+    warning: 'This token will only be shown once. Store it securely.',
+  };
+
+  return jsonResponse(response, 201);
+}
+
+/**
+ * GET /tokens
+ * List all tokens for the authenticated user
+ */
+export async function handleListTokens(ctx: HandlerContext, authContext: AuthContext): Promise<Response> {
+  const tokens = await listApiTokens(ctx.db, authContext.userId);
+
+  const response = {
+    tokens,
+    total: tokens.length,
+  };
+
+  return jsonResponse(response);
+}
+
+/**
+ * DELETE /tokens/:id
+ * Revoke a token
+ */
+export async function handleRevokeToken(ctx: HandlerContext, authContext: AuthContext, tokenId: string): Promise<Response> {
+  const success = await revokeApiToken(ctx.db, tokenId, authContext.userId);
+
+  if (!success) {
+    return errorResponse('Token not found', 'ERR_NOT_FOUND', 404);
+  }
+
+  return jsonResponse({ message: 'Token revoked successfully' });
+}

package/src/utils/crypto.ts

@@ -0,0 +1,82 @@
+// Cryptographic utilities using Web Crypto API
+
+/**
+ * Generate a cryptographically secure random string
+ */
+export function generateRandomBytes(length: number): Uint8Array {
+  return crypto.getRandomValues(new Uint8Array(length));
+}
+
+/**
+ * Convert bytes to hex string
+ */
+export function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+}
+
+/**
+ * Convert hex string to bytes
+ */
+export function hexToBytes(hex: string): Uint8Array {
+  const matches = hex.match(/.{2}/g);
+  if (!matches) {
+    throw new Error('Invalid hex string');
+  }
+  return new Uint8Array(matches.map((b) => parseInt(b, 16)));
+}
+
+/**
+ * Base64 URL-safe encoding (for JWT)
+ */
+export function base64UrlEncode(data: string | ArrayBuffer): string {
+  let base64: string;
+  if (typeof data === 'string') {
+    base64 = btoa(data);
+  } else {
+    base64 = btoa(String.fromCharCode(...new Uint8Array(data)));
+  }
+  return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+/**
+ * Base64 URL-safe decoding (for JWT)
+ */
+export function base64UrlDecode(str: string): string {
+  let base64 = str.replace(/-/g, '+').replace(/_/g, '/');
+  const padding = (4 - (base64.length % 4)) % 4;
+  base64 += '='.repeat(padding);
+  return atob(base64);
+}
+
+/**
+ * SHA-256 hash
+ */
+export async function sha256(data: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const hashBuffer = await crypto.subtle.digest('SHA-256', encoder.encode(data));
+  return bytesToHex(new Uint8Array(hashBuffer));
+}
+
+/**
+ * Constant-time string comparison to prevent timing attacks
+ */
+export function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) {
+    // Compare against itself to maintain constant time even when lengths differ
+    b = a;
+  }
+  let result = a.length === b.length ? 0 : 1;
+  for (let i = 0; i < a.length; i++) {
+    result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return result === 0;
+}
+
+/**
+ * Generate UUID v4
+ */
+export function generateId(): string {
+  return crypto.randomUUID();
+}