@bitsbound/mcp-server 1.0.5 → 1.0.7

package/server/Bitsbound_Kings_McpServer_Backend_Server.ts

@@ -0,0 +1,1441 @@
+#!/usr/bin/env node
+
+////////////////////////////////////////
+// # GOLDEN RULE!!!! HONOR ABOVE ALL!!!!
+////////////////////////////////////////
+// NO NEW FILES!!!!!!!!!
+////////////////////////////////////////
+
+/*
+░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+*/
+// ##                                                                                                               REQUIREMENTS 'R'
+/*
+░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+*/
+
+
+/*
+§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§
+*/
+// ###                                                                                                         DEFINITIONS, VALIDATIONS, AND TRANSFORMATIONS 'R_DVT'
+/*
+§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§
+*/
+
+
+/*
+######################################################################################################################################################################################################
+*/
+// ####                                                                                                    GLOBAL 'R_DVT_G' - Imports & Configuration
+/*
+######################################################################################################################################################################################################
+*/
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+  ErrorCode,
+  McpError
+} from '@modelcontextprotocol/sdk/types.js';
+
+import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
+import { randomUUID, createHmac, createHash, timingSafeEqual } from 'node:crypto';
+import { Buffer } from 'node:buffer';
+import { MongoClient, type Db } from 'mongodb';
+
+// T: Import serverLogger early for MongoDB connection logging
+import { serverLogger } from '../logger/Bitsbound_Kings_McpServer_Backend_Logger.js';
+
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+// MongoDB Connection 'R_DVT_G_D_MongoDB' - Per-customer API key validation
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+// D: MongoDB connection singleton
+let mongoClient: MongoClient | null = null;
+let mongoDb: Db | null = null;
+
+// T: Get or create MongoDB connection
+async function getMongoDb(): Promise<Db | null> {
+  if (mongoDb) return mongoDb;
+
+  const uri = process.env.MONGODB_URI;
+  if (!uri) {
+    serverLogger.warn('MONGODB_URI not configured - per-customer API key validation disabled');
+    return null;
+  }
+
+  try {
+    mongoClient = new MongoClient(uri);
+    await mongoClient.connect();
+    mongoDb = mongoClient.db('bitsbound_admin');
+    serverLogger.info('MongoDB connected for API key validation');
+    return mongoDb;
+  } catch (error) {
+    serverLogger.error('MongoDB connection failed', { error: String(error) });
+    return null;
+  }
+}
+
+// T: Validate customer API key against MongoDB 'bitsbound_admin.api_keys' collection
+// Keys are stored with SHA-256 hash for security
+async function validateApiKeyFromMongoDB(apiKey: string): Promise<{ valid: boolean; customerId?: string }> {
+  const db = await getMongoDb();
+  if (!db) {
+    // Fallback: accept any key if MongoDB not configured (for backward compatibility)
+    return { valid: true };
+  }
+
+  // T: Hash the provided API key to match stored format
+  const keyHash = createHash('sha256').update(apiKey).digest('hex');
+
+  try {
+    const apiKeyDoc = await db.collection('api_keys').findOne({
+      keyHash,
+      status: 'active'
+    });
+
+    if (apiKeyDoc) {
+      serverLogger.info('API key validated via MongoDB', {
+        customerId: apiKeyDoc.customerId,
+        keyPrefix: apiKey.substring(0, 10) + '...'
+      });
+      return { valid: true, customerId: apiKeyDoc.customerId };
+    }
+
+    serverLogger.warn('API key not found or inactive', { keyPrefix: apiKey.substring(0, 10) + '...' });
+    return { valid: false };
+  } catch (error) {
+    serverLogger.error('MongoDB API key lookup failed', { error: String(error) });
+    // Fallback on error - don't break existing customers
+    return { valid: true };
+  }
+}
+
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+// OAuth 2.1 Configuration 'R_DVT_G_D_OAuth' - Premium authentication for claude.ai Custom Connectors
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+// D: OAuth 2.1 constants
+const OAUTH_ISSUER = process.env.OAUTH_ISSUER || 'https://bitsbound-mcp-server.onrender.com';
+const JWT_SECRET = process.env.JWT_SECRET || process.env.BITSBOUND_API_KEY || 'bitsbound-mcp-secret';
+const TOKEN_EXPIRY_SECONDS = 3600; // 1 hour
+
+// D: OAuth client registry (client_id -> client_secret mapping)
+// In production, client_secret should be the BitsBound API key
+interface OAuthClient {
+  clientSecret: string;  // The BitsBound API key
+  name: string;
+  scopes: string[];
+}
+
+// D: Registered OAuth clients - production clients use their API key as client_secret
+const oauthClients: Map<string, OAuthClient> = new Map([
+  // Default client for BitsBound - client_secret = API key
+  ['bitsbound-mcp', {
+    clientSecret: process.env.BITSBOUND_API_KEY || '',
+    name: 'BitsBound MCP Client',
+    scopes: ['mcp:read', 'mcp:write', 'contract:analyze']
+  }]
+]);
+
+// D: JWT Payload structure
+interface JWTPayload {
+  iss: string;      // Issuer
+  sub: string;      // Subject (client_id)
+  aud: string;      // Audience
+  exp: number;      // Expiration timestamp
+  iat: number;      // Issued at timestamp
+  jti: string;      // JWT ID (unique identifier)
+  scope: string;    // OAuth scopes
+  bitsbound_api_key?: string;  // Customer's BitsBound API key (encrypted in token)
+}
+
+// D: Active tokens for revocation support (jti -> expiry timestamp)
+const activeTokens: Map<string, number> = new Map();
+
+// D: Authorization codes for OAuth 2.1 Authorization Code flow with PKCE
+interface AuthorizationCode {
+  clientId: string;
+  redirectUri: string;
+  codeChallenge: string;
+  codeChallengeMethod: string;
+  scopes: string[];
+  expiresAt: number;
+}
+
+// D: Authorization code registry (code -> AuthorizationCode)
+const authorizationCodes: Map<string, AuthorizationCode> = new Map();
+
+// D: Authorization code expiry (10 minutes - per OAuth 2.1 spec)
+const AUTH_CODE_EXPIRY_SECONDS = 600;
+
+// T: Base64URL encode (RFC 7515)
+function base64UrlEncode(data: string | Buffer): string {
+  const buffer = typeof data === 'string' ? Buffer.from(data) : data;
+  return buffer.toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+}
+
+// T: Base64URL decode (RFC 7515)
+function base64UrlDecode(data: string): string {
+  const padded = data + '='.repeat((4 - data.length % 4) % 4);
+  return Buffer.from(padded.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString();
+}
+
+// T: Generate HMAC-SHA256 signature for JWT
+function signJwt(header: string, payload: string): string {
+  const data = `${header}.${payload}`;
+  const signature = createHmac('sha256', JWT_SECRET)
+    .update(data)
+    .digest();
+  return base64UrlEncode(signature);
+}
+
+// T: Generate a JWT access token
+function generateAccessToken(clientId: string, scopes: string[], bitsboundApiKey?: string): string {
+  const now = Math.floor(Date.now() / 1000);
+  const jti = randomUUID();
+
+  const header = {
+    alg: 'HS256',
+    typ: 'JWT'
+  };
+
+  const payload: JWTPayload = {
+    iss: OAUTH_ISSUER,
+    sub: clientId,
+    aud: `${OAUTH_ISSUER}/mcp`,
+    exp: now + TOKEN_EXPIRY_SECONDS,
+    iat: now,
+    jti,
+    scope: scopes.join(' '),
+    // T: Include customer's BitsBound API key in token (JWT is signed, so it's tamper-proof)
+    ...(bitsboundApiKey && { bitsbound_api_key: bitsboundApiKey })
+  };
+
+  const encodedHeader = base64UrlEncode(JSON.stringify(header));
+  const encodedPayload = base64UrlEncode(JSON.stringify(payload));
+  const signature = signJwt(encodedHeader, encodedPayload);
+
+  // T: Register token for revocation support
+  activeTokens.set(jti, payload.exp);
+
+  // T: Cleanup expired tokens periodically
+  cleanupExpiredTokens();
+
+  return `${encodedHeader}.${encodedPayload}.${signature}`;
+}
+
+// T: Verify JWT and return payload (or null if invalid)
+function verifyAccessToken(token: string): JWTPayload | null {
+  try {
+    const parts = token.split('.');
+    if (parts.length !== 3) return null;
+
+    const [encodedHeader, encodedPayload, providedSignature] = parts;
+
+    // V: Verify signature
+    const expectedSignature = signJwt(encodedHeader, encodedPayload);
+    const providedBuffer = Buffer.from(providedSignature);
+    const expectedBuffer = Buffer.from(expectedSignature);
+
+    if (providedBuffer.length !== expectedBuffer.length) return null;
+    if (!timingSafeEqual(providedBuffer, expectedBuffer)) return null;
+
+    // V: Parse and validate payload
+    const payload: JWTPayload = JSON.parse(base64UrlDecode(encodedPayload));
+
+    // V: Check expiration
+    const now = Math.floor(Date.now() / 1000);
+    if (payload.exp <= now) {
+      activeTokens.delete(payload.jti);
+      return null;
+    }
+
+    // V: Check if token was revoked
+    if (!activeTokens.has(payload.jti)) {
+      return null;
+    }
+
+    // V: Verify issuer
+    if (payload.iss !== OAUTH_ISSUER) return null;
+
+    return payload;
+  } catch {
+    return null;
+  }
+}
+
+// T: Clean up expired tokens from registry
+function cleanupExpiredTokens(): void {
+  const now = Math.floor(Date.now() / 1000);
+  for (const [jti, exp] of activeTokens) {
+    if (exp <= now) {
+      activeTokens.delete(jti);
+    }
+  }
+}
+
+// T: Validate client credentials (client_id + client_secret)
+// Per-Customer OAuth: client_secret IS the customer's BitsBound API key (sk_live_xxx)
+// Validates against MongoDB bitsbound_admin.api_keys collection
+async function validateClientCredentials(clientId: string, clientSecret: string): Promise<OAuthClient | null> {
+  // V: For 'bitsbound-mcp' client, the client_secret is the customer's API key
+  if (clientId === 'bitsbound-mcp') {
+    // T: Validate customer's API key against MongoDB
+    if (clientSecret && clientSecret.startsWith('sk_live_')) {
+      const validation = await validateApiKeyFromMongoDB(clientSecret);
+      if (validation.valid) {
+        serverLogger.info('Per-customer OAuth: API key validated', {
+          customerId: validation.customerId,
+          keyPrefix: clientSecret.substring(0, 10) + '...'
+        });
+        return {
+          clientSecret,
+          name: `BitsBound Customer ${validation.customerId || 'unknown'}`,
+          scopes: ['mcp:read', 'mcp:write', 'contract:analyze']
+        };
+      }
+      // Key not valid in MongoDB
+      serverLogger.warn('Per-customer OAuth: API key rejected', {
+        keyPrefix: clientSecret.substring(0, 10) + '...'
+      });
+      return null;
+    }
+  }
+
+  // T: Fallback to static client registry
+  const client = oauthClients.get(clientId);
+  if (!client) return null;
+
+  // V: Timing-safe comparison for client_secret
+  const providedBuffer = Buffer.from(clientSecret);
+  const expectedBuffer = Buffer.from(client.clientSecret);
+
+  // V: Handle empty secrets (env var not set)
+  if (expectedBuffer.length === 0) {
+    // Fall back to using provided secret as API key (for flexibility)
+    return { ...client, clientSecret };
+  }
+
+  if (providedBuffer.length !== expectedBuffer.length) return null;
+  if (!timingSafeEqual(providedBuffer, expectedBuffer)) return null;
+
+  return client;
+}
+
+// T: Verify PKCE code_verifier against stored code_challenge (RFC 7636)
+function verifyPkce(codeVerifier: string, codeChallenge: string, method: string): boolean {
+  if (method === 'plain') {
+    // Plain method: code_challenge === code_verifier
+    return codeVerifier === codeChallenge;
+  } else if (method === 'S256') {
+    // S256 method: code_challenge === BASE64URL(SHA256(code_verifier))
+    const sha256 = createHash('sha256').update(codeVerifier).digest();
+    const computedChallenge = base64UrlEncode(sha256);
+    return computedChallenge === codeChallenge;
+  }
+  return false;
+}
+
+// T: Generate authorization code
+function generateAuthorizationCode(
+  clientId: string,
+  redirectUri: string,
+  codeChallenge: string,
+  codeChallengeMethod: string,
+  scopes: string[]
+): string {
+  const code = randomUUID();
+  const expiresAt = Math.floor(Date.now() / 1000) + AUTH_CODE_EXPIRY_SECONDS;
+
+  authorizationCodes.set(code, {
+    clientId,
+    redirectUri,
+    codeChallenge,
+    codeChallengeMethod,
+    scopes,
+    expiresAt
+  });
+
+  // T: Cleanup expired codes
+  cleanupExpiredAuthCodes();
+
+  return code;
+}
+
+// T: Validate and consume authorization code
+function consumeAuthorizationCode(
+  code: string,
+  clientId: string,
+  redirectUri: string,
+  codeVerifier: string
+): { scopes: string[] } | null {
+  const authCode = authorizationCodes.get(code);
+  if (!authCode) return null;
+
+  // V: Check expiration
+  const now = Math.floor(Date.now() / 1000);
+  if (authCode.expiresAt <= now) {
+    authorizationCodes.delete(code);
+    return null;
+  }
+
+  // V: Verify client_id matches
+  if (authCode.clientId !== clientId) return null;
+
+  // V: Verify redirect_uri matches
+  if (authCode.redirectUri !== redirectUri) return null;
+
+  // V: Verify PKCE code_verifier
+  if (!verifyPkce(codeVerifier, authCode.codeChallenge, authCode.codeChallengeMethod)) {
+    return null;
+  }
+
+  // T: Consume the code (one-time use)
+  authorizationCodes.delete(code);
+
+  return { scopes: authCode.scopes };
+}
+
+// T: Clean up expired authorization codes
+function cleanupExpiredAuthCodes(): void {
+  const now = Math.floor(Date.now() / 1000);
+  for (const [code, authCode] of authorizationCodes) {
+    if (authCode.expiresAt <= now) {
+      authorizationCodes.delete(code);
+    }
+  }
+}
+
+import type {
+  McpServerConfig,
+  AnalyzeContractInput,
+  GetAnalysisStatusInput,
+  AskSacInput,
+  GenerateRedlineInput,
+  GenerateNegotiationEmailInput,
+  ExtractClauseInput,
+  ComparePlaybookInput,
+  // Instant Swarm - Parallel Section Redlining
+  InstantSwarmInput,
+  // Quick Tools
+  QuickScanInput,
+  AskClauseInput,
+  CheckDealbreakersInput,
+  // File Download
+  DownloadFileInput,
+  ToolName,
+  PromptName
+} from '../types/Bitsbound_Kings_McpServer_Backend_Types.js';
+import { TOOL_DEFINITIONS, RESOURCE_DEFINITIONS, PROMPT_DEFINITIONS, PROMPT_MESSAGES, DEFAULT_API_URL } from '../types/Bitsbound_Kings_McpServer_Backend_Types.js';
+import { BitsBoundBackautocrat } from '../orchestration/backautocrat/Bitsbound_Kings_McpServer_Backend_Orchestration_Backautocrat.js';
+// Note: serverLogger imported at top for MongoDB connection logging
+
+
+/*
+❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅
+*/
+// #####                                                                                               DEFINITIONS 'R_DVT_G_D' - MCP Server Class
+/*
+❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅
+*/
+
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+// BitsBound MCP Server 'R_DVT_G_D_McpServer'
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+class BitsBoundMcpServer {
+  private readonly server: Server;
+  private readonly backautocrat: BitsBoundBackautocrat | null;
+
+  constructor(config: McpServerConfig) {
+    // T: Create backautocrat only if API key is available (graceful degradation)
+    if (config.BITSBOUND_API_KEY) {
+      this.backautocrat = new BitsBoundBackautocrat(config);
+    } else {
+      serverLogger.warn('BITSBOUND_API_KEY not configured - tools will be unavailable');
+      this.backautocrat = null;
+    }
+
+    this.server = new Server(
+      {
+        name: 'BitsBound',
+        version: '1.0.0',
+        // D: Server branding for claude.ai Custom Connectors
+        description: 'AI-powered contract analysis - partner-level redlines with Track Changes',
+        websiteUrl: 'https://bitsbound.com',
+        icons: [
+          {
+            src: 'https://www.bitsbound.com/favicon.svg',
+            mimeType: 'image/svg+xml'
+          }
+        ]
+      },
+      {
+        capabilities: {
+          tools: {},
+          resources: {},
+          prompts: {}
+        }
+      }
+    );
+
+    this.setupHandlers();
+    this.setupErrorHandling();
+  }
+
+  // ────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+  // Setup: Error Handling 'R_DVT_G_T_ErrorHandling'
+  // ────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+  private setupErrorHandling(): void {
+    this.server.onerror = (error): void => {
+      serverLogger.error('MCP Server error', { error: String(error) });
+    };
+
+    process.on('SIGINT', async () => {
+      serverLogger.info('Received SIGINT, shutting down...');
+      await this.server.close();
+      process.exit(0);
+    });
+
+    process.on('SIGTERM', async () => {
+      serverLogger.info('Received SIGTERM, shutting down...');
+      await this.server.close();
+      process.exit(0);
+    });
+  }
+
+  // ────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+  // Setup: MCP Protocol Handlers 'R_DVT_G_T_Handlers'
+  // ────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+  private setupHandlers(): void {
+    // List available tools
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+      serverLogger.debug('Listing tools');
+      return {
+        tools: Object.values(TOOL_DEFINITIONS)
+      };
+    });
+
+    // List available resources
+    this.server.setRequestHandler(ListResourcesRequestSchema, async () => {
+      serverLogger.debug('Listing resources');
+      return {
+        resources: Object.values(RESOURCE_DEFINITIONS).map(r => ({
+          uri: r.uriTemplate,
+          name: r.name,
+          description: r.description,
+          mimeType: r.mimeType
+        }))
+      };
+    });
+
+    // Handle tool calls
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+      serverLogger.info('Tool called', { tool: name });
+
+      try {
+        const result = await this.handleToolCall(name as ToolName, args as Record<string, unknown>);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(result, null, 2)
+            }
+          ]
+        };
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        serverLogger.error('Tool call failed', { tool: name, error: errorMessage });
+        throw new McpError(ErrorCode.InternalError, errorMessage);
+      }
+    });
+
+    // Handle resource reads
+    this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+      const { uri } = request.params;
+      serverLogger.info('Resource requested', { uri });
+
+      try {
+        const result = await this.handleResourceRead(uri);
+        return {
+          contents: [
+            {
+              uri,
+              mimeType: 'application/json',
+              text: JSON.stringify(result, null, 2)
+            }
+          ]
+        };
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        serverLogger.error('Resource read failed', { uri, error: errorMessage });
+        throw new McpError(ErrorCode.InternalError, errorMessage);
+      }
+    });
+
+    // ────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+    // Prompt Handlers 'R_DVT_G_T_PromptHandlers' - User-facing workflow templates
+    // ────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+    // List available prompts
+    this.server.setRequestHandler(ListPromptsRequestSchema, async () => {
+      serverLogger.debug('Listing prompts');
+      return {
+        prompts: Object.values(PROMPT_DEFINITIONS).map(p => ({
+          name: p.name,
+          description: p.description,
+          arguments: p.arguments
+        }))
+      };
+    });
+
+    // Get specific prompt content
+    this.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+      serverLogger.info('Prompt requested', { prompt: name });
+
+      // V: Validate prompt name
+      if (!(name in PROMPT_DEFINITIONS)) {
+        throw new McpError(ErrorCode.InvalidRequest, `Unknown prompt: ${name}`);
+      }
+
+      const promptName = name as PromptName;
+      const promptDef = PROMPT_DEFINITIONS[promptName];
+      let messages = PROMPT_MESSAGES[promptName];
+
+      // T: If prompt has arguments (like analysisId), inject them into the message
+      if (args && promptDef.arguments.length > 0) {
+        messages = messages.map(msg => ({
+          ...msg,
+          content: {
+            type: 'text' as const,
+            text: Object.entries(args).reduce(
+              (text, [key, value]) => text.replace(`{${key}}`, String(value)),
+              msg.content.text
+            )
+          }
+        }));
+      }
+
+      return {
+        description: promptDef.description,
+        messages
+      };
+    });
+  }
+
+
+/*
+######################################################################################################################################################################################################
+*/
+// ####                                                                                                         LOCAL 'R_DVT_L' - Tool & Resource Handlers
+/*
+######################################################################################################################################################################################################
+*/
+
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+  // Helper: Require Backautocrat 'R_DVT_L_T_RequireBackautocrat'
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+  private requireBackautocrat(): BitsBoundBackautocrat {
+    if (!this.backautocrat) {
+      throw new McpError(
+        ErrorCode.InternalError,
+        'BitsBound API key not configured. Please set BITSBOUND_API_KEY environment variable on the server.'
+      );
+    }
+    return this.backautocrat;
+  }
+
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+  // Tool Router 'R_DVT_L_T_ToolRouter' - Routes tool calls to appropriate handler
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+  private async handleToolCall(
+    toolName: ToolName,
+    args: Record<string, unknown>
+  ): Promise<unknown> {
+    const backautocrat = this.requireBackautocrat();
+    switch (toolName) {
+      case 'process_contract':
+        return backautocrat.analyzeContract(args as unknown as AnalyzeContractInput);
+
+      case 'get_analysis_status':
+        return backautocrat.getAnalysisStatus(args as unknown as GetAnalysisStatusInput);
+
+      case 'ask_sac':
+        return backautocrat.askSac(args as unknown as AskSacInput);
+
+      case 'generate_redline':
+        return backautocrat.generateRedline(args as unknown as GenerateRedlineInput);
+
+      case 'generate_negotiation_email':
+        return backautocrat.generateNegotiationEmail(args as unknown as GenerateNegotiationEmailInput);
+
+      case 'extract_clause':
+        return backautocrat.extractClause(args as unknown as ExtractClauseInput);
+
+      case 'compare_playbook':
+        return backautocrat.comparePlaybook(args as unknown as ComparePlaybookInput);
+
+      // ═══════════════════════════════════════════════════════════════════════════════════════════
+      // INSTANT SWARM - Parallel N-Section Redlining (spawns N agents for N sections)
+      // ═══════════════════════════════════════════════════════════════════════════════════════════
+
+      case 'instant_swarm':
+        return backautocrat.instantSwarm(args as unknown as InstantSwarmInput);
+
+      // ═══════════════════════════════════════════════════════════════════════════════════════════
+      // QUICK TOOLS - Immediate analysis without full pipeline
+      // ═══════════════════════════════════════════════════════════════════════════════════════════
+
+      case 'quick_scan':
+        return backautocrat.quickScan(args as unknown as QuickScanInput);
+
+      case 'ask_clause':
+        return backautocrat.askClause(args as unknown as AskClauseInput);
+
+      case 'check_dealbreakers':
+        return backautocrat.checkDealbreakers(args as unknown as CheckDealbreakersInput);
+
+      // ═══════════════════════════════════════════════════════════════════════════════════════════
+      // FILE DOWNLOAD - Retrieves files from R2 (e.g., redlined DOCX)
+      // ═══════════════════════════════════════════════════════════════════════════════════════════
+
+      case 'download_file':
+        return backautocrat.downloadFile(args as unknown as DownloadFileInput);
+
+      default:
+        throw new Error(`Unknown tool: ${toolName}`);
+    }
+  }
+
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+  // Resource Router 'R_DVT_L_T_ResourceRouter' - Routes resource reads to appropriate handler
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+  private async handleResourceRead(uri: string): Promise<unknown> {
+    const backautocrat = this.requireBackautocrat();
+
+    // Parse URI: bitsbound://analysis/{analysisId}
+    const analysisMatch = uri.match(/^bitsbound:\/\/analysis\/(.+)$/);
+    if (analysisMatch) {
+      return backautocrat.getAnalysisResults(analysisMatch[1]);
+    }
+
+    // Parse URI: bitsbound://playbook/{playbookId}
+    const playbookMatch = uri.match(/^bitsbound:\/\/playbook\/(.+)$/);
+    if (playbookMatch) {
+      return backautocrat.getPlaybook(playbookMatch[1]);
+    }
+
+    throw new Error(`Unknown resource URI: ${uri}`);
+  }
+
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+  // Run Server 'R_DVT_L_T_Run' - Starts the MCP server in stdio mode (for Claude Desktop)
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+  async runStdio(): Promise<void> {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+    serverLogger.info('BitsBound MCP Server running on stdio');
+  }
+
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+  // Get Server Instance 'R_DVT_L_T_GetServer' - Returns the underlying MCP server for HTTP transport
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+  getServer(): Server {
+    return this.server;
+  }
+}
+
+
+/*
+######################################################################################################################################################################################################
+*/
+// ####                                                                                                         HTTP SERVER 'R_DVT_Http' - HTTP/SSE Transport for claude.ai Custom Connectors
+/*
+######################################################################################################################################################################################################
+*/
+
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+// HTTP MCP Server 'R_DVT_Http_Server' - Handles HTTP transport for remote MCP access
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+// D: Map of session ID to transport instance (for stateful sessions)
+const sessionTransports: Map<string, StreamableHTTPServerTransport> = new Map();
+// D: Map of session ID to MCP server instance (for stateful sessions)
+const sessionServers: Map<string, BitsBoundMcpServer> = new Map();
+
+// T: Extract API key from Authorization header
+function extractApiKey(req: IncomingMessage): string | null {
+  const authHeader = req.headers.authorization;
+  if (!authHeader) return null;
+
+  // Support "Bearer sk_live_xxx" format
+  if (authHeader.startsWith('Bearer ')) {
+    return authHeader.slice(7);
+  }
+
+  return null;
+}
+
+// T: Send CORS headers for cross-origin requests
+function setCorsHeaders(res: ServerResponse): void {
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, Mcp-Session-Id');
+  res.setHeader('Access-Control-Expose-Headers', 'Mcp-Session-Id');
+}
+
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+// OAuth 2.1 Endpoints 'R_DVT_Http_OAuth' - Discovery and Token endpoints for claude.ai
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+// T: Handle OAuth Authorization Server Metadata (RFC 8414)
+function handleOAuthMetadata(_req: IncomingMessage, res: ServerResponse): void {
+  const metadata = {
+    issuer: OAUTH_ISSUER,
+    authorization_endpoint: `${OAUTH_ISSUER}/oauth/authorize`,
+    token_endpoint: `${OAUTH_ISSUER}/oauth/token`,
+    token_endpoint_auth_methods_supported: ['client_secret_post', 'client_secret_basic'],
+    grant_types_supported: ['authorization_code', 'client_credentials'],
+    response_types_supported: ['code'],
+    scopes_supported: ['mcp:read', 'mcp:write', 'contract:analyze'],
+    service_documentation: 'https://bitsbound.com/docs/mcp',
+    // OAuth 2.1 PKCE requirement
+    code_challenge_methods_supported: ['S256', 'plain'],
+    // MCP-specific metadata
+    mcp_endpoint: `${OAUTH_ISSUER}/mcp`,
+    mcp_version: '1.0.0'
+  };
+
+  res.writeHead(200, {
+    'Content-Type': 'application/json',
+    'Cache-Control': 'max-age=3600'
+  });
+  res.end(JSON.stringify(metadata, null, 2));
+}
+
+// T: Handle OAuth Protected Resource Metadata (RFC 9470)
+function handleProtectedResourceMetadata(_req: IncomingMessage, res: ServerResponse): void {
+  const metadata = {
+    resource: `${OAUTH_ISSUER}/mcp`,
+    authorization_servers: [OAUTH_ISSUER],
+    bearer_methods_supported: ['header'],
+    scopes_supported: ['mcp:read', 'mcp:write', 'contract:analyze'],
+    resource_documentation: 'https://bitsbound.com/docs/mcp'
+  };
+
+  res.writeHead(200, {
+    'Content-Type': 'application/json',
+    'Cache-Control': 'max-age=3600'
+  });
+  res.end(JSON.stringify(metadata, null, 2));
+}
+
+// T: Handle OAuth Authorization endpoint (Authorization Code flow with PKCE)
+function handleOAuthAuthorize(req: IncomingMessage, res: ServerResponse): void {
+  const url = new URL(req.url || '/', `http://${req.headers.host}`);
+
+  // D: Extract OAuth parameters from query string
+  const responseType = url.searchParams.get('response_type');
+  const clientId = url.searchParams.get('client_id');
+  const redirectUri = url.searchParams.get('redirect_uri');
+  const state = url.searchParams.get('state');
+  const scope = url.searchParams.get('scope');
+  const codeChallenge = url.searchParams.get('code_challenge');
+  const codeChallengeMethod = url.searchParams.get('code_challenge_method') || 'plain';
+
+  // V: Validate required parameters
+  if (responseType !== 'code') {
+    res.writeHead(400, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      error: 'unsupported_response_type',
+      error_description: 'Only response_type=code is supported'
+    }));
+    return;
+  }
+
+  if (!clientId) {
+    res.writeHead(400, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      error: 'invalid_request',
+      error_description: 'client_id is required'
+    }));
+    return;
+  }
+
+  if (!redirectUri) {
+    res.writeHead(400, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      error: 'invalid_request',
+      error_description: 'redirect_uri is required'
+    }));
+    return;
+  }
+
+  // V: PKCE is required for OAuth 2.1
+  if (!codeChallenge) {
+    res.writeHead(400, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      error: 'invalid_request',
+      error_description: 'code_challenge is required (PKCE)'
+    }));
+    return;
+  }
+
+  // D: Allowed scopes for all clients
+  const ALLOWED_SCOPES = ['mcp:read', 'mcp:write', 'contract:analyze'];
+
+  // T: Check if this is a registered confidential client or a public client (PKCE)
+  const client = oauthClients.get(clientId);
+
+  // T: For public clients (PKCE flow), we allow any client_id since security comes from PKCE
+  // For registered confidential clients, we use their configured scopes
+  const clientScopes = client ? client.scopes : ALLOWED_SCOPES;
+
+  // T: Parse and validate requested scopes
+  const requestedScopes = scope ? scope.split(' ') : clientScopes;
+  const grantedScopes = requestedScopes.filter(s => ALLOWED_SCOPES.includes(s));
+
+  // T: Generate authorization code
+  const code = generateAuthorizationCode(
+    clientId,
+    redirectUri,
+    codeChallenge,
+    codeChallengeMethod,
+    grantedScopes
+  );
+
+  serverLogger.info('Authorization code issued', {
+    clientId,
+    clientType: client ? 'confidential' : 'public',
+    scopes: grantedScopes
+  });
+
+  // T: Build redirect URL with authorization code
+  const redirectUrl = new URL(redirectUri);
+  redirectUrl.searchParams.set('code', code);
+  if (state) {
+    redirectUrl.searchParams.set('state', state);
+  }
+
+  // O: Redirect back to client with authorization code
+  res.writeHead(302, {
+    'Location': redirectUrl.toString(),
+    'Cache-Control': 'no-store'
+  });
+  res.end();
+}
+
+// T: Parse request body as URL-encoded form data
+async function parseFormBody(req: IncomingMessage): Promise<URLSearchParams> {
+  return new Promise((resolve, reject) => {
+    let body = '';
+    req.on('data', (chunk: Buffer) => {
+      body += chunk.toString();
+      // V: Limit body size to 16KB for security
+      if (body.length > 16384) {
+        reject(new Error('Request body too large'));
+      }
+    });
+    req.on('end', () => resolve(new URLSearchParams(body)));
+    req.on('error', reject);
+  });
+}
+
+// T: Parse Basic Auth header
+function parseBasicAuth(req: IncomingMessage): { clientId: string; clientSecret: string } | null {
+  const authHeader = req.headers.authorization;
+  if (!authHeader || !authHeader.startsWith('Basic ')) return null;
+
+  try {
+    const decoded = Buffer.from(authHeader.slice(6), 'base64').toString();
+    const colonIndex = decoded.indexOf(':');
+    if (colonIndex === -1) return null;
+
+    return {
+      clientId: decoded.slice(0, colonIndex),
+      clientSecret: decoded.slice(colonIndex + 1)
+    };
+  } catch {
+    return null;
+  }
+}
+
+// T: Handle OAuth Token endpoint (Authorization Code + Client Credentials grants)
+async function handleOAuthToken(req: IncomingMessage, res: ServerResponse): Promise<void> {
+  // V: Only POST allowed
+  if (req.method !== 'POST') {
+    res.writeHead(405, { 'Content-Type': 'application/json', 'Allow': 'POST' });
+    res.end(JSON.stringify({ error: 'method_not_allowed' }));
+    return;
+  }
+
+  try {
+    const body = await parseFormBody(req);
+    const grantType = body.get('grant_type');
+
+    // T: Extract client credentials (supports both Basic auth and POST body)
+    let clientId: string | null = null;
+    let clientSecret: string | null = null;
+
+    // Try Basic auth first
+    const basicAuth = parseBasicAuth(req);
+    if (basicAuth) {
+      clientId = basicAuth.clientId;
+      clientSecret = basicAuth.clientSecret;
+    } else {
+      // Fall back to POST body
+      clientId = body.get('client_id');
+      clientSecret = body.get('client_secret');
+    }
+
+    // ════════════════════════════════════════════════════════════════════════════════════════════
+    // Authorization Code Grant (OAuth 2.1 with PKCE)
+    // ════════════════════════════════════════════════════════════════════════════════════════════
+    if (grantType === 'authorization_code') {
+      const code = body.get('code');
+      const redirectUri = body.get('redirect_uri');
+      const codeVerifier = body.get('code_verifier');
+
+      // V: Validate required parameters
+      if (!code || !redirectUri || !codeVerifier || !clientId) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          error: 'invalid_request',
+          error_description: 'code, redirect_uri, code_verifier, and client_id are required'
+        }));
+        return;
+      }
+
+      // V: Validate and consume authorization code
+      const result = consumeAuthorizationCode(code, clientId, redirectUri, codeVerifier);
+      if (!result) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          error: 'invalid_grant',
+          error_description: 'Invalid or expired authorization code, or PKCE verification failed'
+        }));
+        return;
+      }
+
+      // T: Generate access token with customer's BitsBound API key (client_secret)
+      // The client_secret IS the customer's BitsBound API key (sk_live_xxx...)
+      const accessToken = generateAccessToken(clientId, result.scopes, clientSecret || undefined);
+
+      serverLogger.info('OAuth token issued via authorization_code', {
+        clientId,
+        scopes: result.scopes,
+        hasApiKey: !!clientSecret
+      });
+
+      // O: Return token response
+      res.writeHead(200, {
+        'Content-Type': 'application/json',
+        'Cache-Control': 'no-store',
+        'Pragma': 'no-cache'
+      });
+      res.end(JSON.stringify({
+        access_token: accessToken,
+        token_type: 'Bearer',
+        expires_in: TOKEN_EXPIRY_SECONDS,
+        scope: result.scopes.join(' ')
+      }));
+      return;
+    }
+
+    // ════════════════════════════════════════════════════════════════════════════════════════════
+    // Client Credentials Grant (Machine-to-Machine)
+    // ════════════════════════════════════════════════════════════════════════════════════════════
+    if (grantType === 'client_credentials') {
+      // V: Require client credentials
+      if (!clientId || !clientSecret) {
+        res.writeHead(401, {
+          'Content-Type': 'application/json',
+          'WWW-Authenticate': 'Basic realm="BitsBound MCP"'
+        });
+        res.end(JSON.stringify({
+          error: 'invalid_client',
+          error_description: 'Client credentials required'
+        }));
+        return;
+      }
+
+      // V: Validate client credentials (async for MongoDB per-customer API key validation)
+      const client = await validateClientCredentials(clientId, clientSecret);
+      if (!client) {
+        res.writeHead(401, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          error: 'invalid_client',
+          error_description: 'Invalid client credentials'
+        }));
+        return;
+      }
+
+      // T: Parse requested scope (optional)
+      const requestedScope = body.get('scope');
+      const grantedScopes = requestedScope
+        ? requestedScope.split(' ').filter(s => client.scopes.includes(s))
+        : client.scopes;
+
+      // T: Generate access token with customer's BitsBound API key
+      const accessToken = generateAccessToken(clientId, grantedScopes, clientSecret || undefined);
+
+      serverLogger.info('OAuth token issued via client_credentials', { clientId, scopes: grantedScopes });
+
+      // O: Return token response
+      res.writeHead(200, {
+        'Content-Type': 'application/json',
+        'Cache-Control': 'no-store',
+        'Pragma': 'no-cache'
+      });
+      res.end(JSON.stringify({
+        access_token: accessToken,
+        token_type: 'Bearer',
+        expires_in: TOKEN_EXPIRY_SECONDS,
+        scope: grantedScopes.join(' ')
+      }));
+      return;
+    }
+
+    // V: Unsupported grant type
+    res.writeHead(400, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      error: 'unsupported_grant_type',
+      error_description: 'Supported grant types: authorization_code, client_credentials'
+    }));
+
+  } catch (error) {
+    serverLogger.error('OAuth token error', { error: String(error) });
+    res.writeHead(400, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      error: 'invalid_request',
+      error_description: 'Failed to process token request'
+    }));
+  }
+}
+
+// T: Handle HTTP requests for MCP protocol
+async function handleHttpRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
+  setCorsHeaders(res);
+
+  // V: Handle CORS preflight
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204);
+    res.end();
+    return;
+  }
+
+  const url = new URL(req.url || '/', `http://${req.headers.host}`);
+
+  // ════════════════════════════════════════════════════════════════════════════════════════════
+  // OAuth 2.1 Endpoint Routing
+  // ════════════════════════════════════════════════════════════════════════════════════════════
+
+  // T: OAuth Authorization Server Metadata (RFC 8414)
+  if (url.pathname === '/.well-known/oauth-authorization-server') {
+    handleOAuthMetadata(req, res);
+    return;
+  }
+
+  // T: OAuth Protected Resource Metadata (RFC 9470)
+  if (url.pathname === '/.well-known/oauth-protected-resource') {
+    handleProtectedResourceMetadata(req, res);
+    return;
+  }
+
+  // T: OAuth Authorization endpoint (Authorization Code flow)
+  if (url.pathname === '/oauth/authorize') {
+    handleOAuthAuthorize(req, res);
+    return;
+  }
+
+  // T: OAuth Token endpoint
+  if (url.pathname === '/oauth/token') {
+    await handleOAuthToken(req, res);
+    return;
+  }
+
+  // T: Health check endpoint
+  if (url.pathname === '/health') {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      status: 'healthy',
+      mode: 'http',
+      version: '1.0.0',
+      oauth: {
+        issuer: OAUTH_ISSUER,
+        authorization_endpoint: `${OAUTH_ISSUER}/oauth/authorize`,
+        token_endpoint: `${OAUTH_ISSUER}/oauth/token`,
+        metadata_endpoint: `${OAUTH_ISSUER}/.well-known/oauth-authorization-server`
+      }
+    }));
+    return;
+  }
+
+  // V: Only handle /mcp endpoint beyond this point
+  if (url.pathname !== '/mcp') {
+    res.writeHead(404, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      error: 'Not Found',
+      message: 'Use /mcp endpoint for MCP protocol',
+      oauth_discovery: `${OAUTH_ISSUER}/.well-known/oauth-authorization-server`
+    }));
+    return;
+  }
+
+  // ════════════════════════════════════════════════════════════════════════════════════════════
+  // MCP Endpoint Authentication (JWT Bearer or API Key fallback)
+  // ════════════════════════════════════════════════════════════════════════════════════════════
+
+  let apiKey = '';
+  const bearerToken = extractApiKey(req);
+
+  if (bearerToken) {
+    // T: Check if it's a JWT (has 3 parts separated by dots)
+    if (bearerToken.includes('.') && bearerToken.split('.').length === 3) {
+      // V: Validate JWT token
+      const payload = verifyAccessToken(bearerToken);
+      if (!payload) {
+        res.writeHead(401, {
+          'Content-Type': 'application/json',
+          'WWW-Authenticate': 'Bearer realm="BitsBound MCP", error="invalid_token"'
+        });
+        res.end(JSON.stringify({
+          error: 'invalid_token',
+          error_description: 'The access token is invalid or expired'
+        }));
+        return;
+      }
+      // T: JWT is valid - extract customer's BitsBound API key from token
+      // The API key was stored in the token during OAuth flow (client_secret = customer's API key)
+      apiKey = payload.bitsbound_api_key || process.env.BITSBOUND_API_KEY || '';
+      serverLogger.debug('Authenticated via JWT', {
+        clientId: payload.sub,
+        scopes: payload.scope,
+        hasApiKey: !!payload.bitsbound_api_key
+      });
+    } else if (bearerToken.startsWith('sk_live_')) {
+      // T: It's a raw BitsBound API key (direct auth without OAuth)
+      // V: Validate against MongoDB
+      const validation = await validateApiKeyFromMongoDB(bearerToken);
+      if (!validation.valid) {
+        res.writeHead(401, {
+          'Content-Type': 'application/json',
+          'WWW-Authenticate': 'Bearer realm="BitsBound MCP", error="invalid_token"'
+        });
+        res.end(JSON.stringify({
+          error: 'invalid_token',
+          error_description: 'Invalid BitsBound API key'
+        }));
+        return;
+      }
+      apiKey = bearerToken;
+      serverLogger.info('Authenticated via direct API key', { customerId: validation.customerId });
+    } else {
+      // V: Unknown token format
+      res.writeHead(401, {
+        'Content-Type': 'application/json',
+        'WWW-Authenticate': 'Bearer realm="BitsBound MCP", error="invalid_token"'
+      });
+      res.end(JSON.stringify({
+        error: 'invalid_token',
+        error_description: 'Invalid token format. Use OAuth or provide sk_live_xxx API key.'
+      }));
+      return;
+    }
+  } else {
+    // V: No authentication provided - require OAuth
+    // Return 401 to trigger OAuth flow in claude.ai
+    res.writeHead(401, {
+      'Content-Type': 'application/json',
+      'WWW-Authenticate': `Bearer realm="BitsBound MCP", authorization_uri="${OAUTH_ISSUER}/oauth/authorize", token_uri="${OAUTH_ISSUER}/oauth/token"`
+    });
+    res.end(JSON.stringify({
+      error: 'unauthorized',
+      error_description: 'Authentication required. Please complete OAuth flow.',
+      oauth_discovery: `${OAUTH_ISSUER}/.well-known/oauth-authorization-server`
+    }));
+    return;
+  }
+
+  // D: Get or create session-based transport
+  const sessionId = req.headers['mcp-session-id'] as string | undefined;
+
+  let transport: StreamableHTTPServerTransport;
+  let mcpServer: BitsBoundMcpServer;
+
+  if (sessionId && sessionTransports.has(sessionId)) {
+    // T: Reuse existing session
+    transport = sessionTransports.get(sessionId)!;
+    mcpServer = sessionServers.get(sessionId)!;
+    serverLogger.debug('Reusing existing session', { sessionId });
+  } else if (req.method === 'GET' || (req.method === 'POST' && !sessionId)) {
+    // T: Create new session for initialization
+    const config: McpServerConfig = {
+      BITSBOUND_API_KEY: apiKey,
+      BITSBOUND_API_URL: process.env.BITSBOUND_API_URL || DEFAULT_API_URL
+    };
+
+    mcpServer = new BitsBoundMcpServer(config);
+
+    transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => randomUUID(),
+      onsessioninitialized: (newSessionId: string) => {
+        serverLogger.info('Session initialized', { sessionId: newSessionId });
+        sessionTransports.set(newSessionId, transport);
+        sessionServers.set(newSessionId, mcpServer);
+      },
+      onsessionclosed: (closedSessionId: string) => {
+        serverLogger.info('Session closed', { sessionId: closedSessionId });
+        sessionTransports.delete(closedSessionId);
+        sessionServers.delete(closedSessionId);
+      }
+    });
+
+    // T: Connect the MCP server to the transport
+    await mcpServer.getServer().connect(transport);
+    serverLogger.info('New MCP session created');
+  } else {
+    // V: Invalid request - session required but not found
+    res.writeHead(400, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      error: 'Bad Request',
+      message: 'Session ID required for non-initialization requests'
+    }));
+    return;
+  }
+
+  // T: Handle the request through StreamableHTTPServerTransport
+  try {
+    await transport.handleRequest(req, res);
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+    serverLogger.error('HTTP transport error', { error: errorMessage });
+    if (!res.headersSent) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Internal Server Error', message: errorMessage }));
+    }
+  }
+}
+
+// T: Start HTTP server for remote MCP access
+async function startHttpServer(port: number): Promise<void> {
+  const httpServer = createServer(handleHttpRequest);
+
+  httpServer.listen(port, () => {
+    serverLogger.info(`BitsBound MCP Server running on HTTP port ${port}`);
+    serverLogger.info(`Remote MCP URL: http://localhost:${port}/mcp`);
+    console.log(`\n╔═══════════════════════════════════════════════════════════════════════════════╗`);
+    console.log(`║  BitsBound MCP Server (HTTP Mode) - OAuth 2.1 Enabled                         ║`);
+    console.log(`╠═══════════════════════════════════════════════════════════════════════════════╣`);
+    console.log(`║  MCP Endpoint:        http://localhost:${port}/mcp`.padEnd(80) + `║`);
+    console.log(`║  Health Check:        http://localhost:${port}/health`.padEnd(80) + `║`);
+    console.log(`╠═══════════════════════════════════════════════════════════════════════════════╣`);
+    console.log(`║  OAuth 2.1 Endpoints:                                                         ║`);
+    console.log(`║  Discovery:           /.well-known/oauth-authorization-server                 ║`);
+    console.log(`║  Token Endpoint:      /oauth/token                                            ║`);
+    console.log(`╠═══════════════════════════════════════════════════════════════════════════════╣`);
+    console.log(`║  For claude.ai Custom Connectors:                                             ║`);
+    console.log(`║  1. Name:          BitsBound                                                  ║`);
+    console.log(`║  2. URL:           https://your-domain.com/mcp                                ║`);
+    console.log(`║  3. Client ID:     bitsbound-mcp                                              ║`);
+    console.log(`║  4. Client Secret: Your BitsBound API key (sk_live_xxx...)                    ║`);
+    console.log(`╚═══════════════════════════════════════════════════════════════════════════════╝\n`);
+  });
+
+  // T: Handle graceful shutdown
+  process.on('SIGINT', () => {
+    serverLogger.info('Received SIGINT, shutting down HTTP server...');
+    httpServer.close(() => process.exit(0));
+  });
+
+  process.on('SIGTERM', () => {
+    serverLogger.info('Received SIGTERM, shutting down HTTP server...');
+    httpServer.close(() => process.exit(0));
+  });
+}
+
+
+/*
+######################################################################################################################################################################################################
+*/
+// ####                                                                                                         EXECUTION 'R_E' - Main Entry Point
+/*
+######################################################################################################################################################################################################
+*/
+
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+// Main Entry 'R_E_Main' - Reads config from environment and starts server
+// Supports two modes:
+//   1. STDIO mode (default) - For Claude Desktop local use
+//   2. HTTP mode (MCP_HTTP_PORT env or --http flag) - For claude.ai Custom Connectors
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+async function main(): Promise<void> {
+  serverLogger.info('Starting BitsBound MCP Server...');
+
+  // D: Check for HTTP mode
+  const httpPort = process.env.MCP_HTTP_PORT || process.env.PORT;
+  const isHttpMode = httpPort || process.argv.includes('--http');
+
+  if (isHttpMode) {
+    // T: HTTP mode - for claude.ai Custom Connectors
+    const port = parseInt(httpPort || '3001', 10);
+    serverLogger.info('Starting in HTTP mode', { port });
+    await startHttpServer(port);
+  } else {
+    // T: STDIO mode - for Claude Desktop
+    const apiKey = process.env.BITSBOUND_API_KEY;
+    if (!apiKey) {
+      serverLogger.error('BITSBOUND_API_KEY environment variable is required');
+      console.error('Error: BITSBOUND_API_KEY environment variable is required');
+      console.error('');
+      console.error('For Claude Desktop, set it in your config:');
+      console.error('  "env": { "BITSBOUND_API_KEY": "sk_live_xxxxx" }');
+      console.error('');
+      console.error('For HTTP mode, set MCP_HTTP_PORT and include API key in Authorization header');
+      console.error('');
+      console.error('Get your API key at: https://account.bitsbound.com/api-keys');
+      process.exit(1);
+    }
+
+    const config: McpServerConfig = {
+      BITSBOUND_API_KEY: apiKey,
+      BITSBOUND_API_URL: process.env.BITSBOUND_API_URL || DEFAULT_API_URL
+    };
+
+    serverLogger.info('Configuration loaded (stdio mode)', {
+      apiUrl: config.BITSBOUND_API_URL,
+      apiKeyPrefix: apiKey.substring(0, 10) + '...'
+    });
+
+    const server = new BitsBoundMcpServer(config);
+    await server.runStdio();
+  }
+}
+
+main().catch((error) => {
+  serverLogger.error('Fatal error', { error: String(error) });
+  console.error('Fatal error:', error);
+  process.exit(1);
+});