@bitsbound/mcp-server 1.0.5 → 1.0.7

package/orchestration/backautocrat/Bitsbound_Kings_McpServer_Backend_Orchestration_Backautocrat.ts

@@ -0,0 +1,715 @@
+////////////////////////////////////////
+// # GOLDEN RULE!!!! HONOR ABOVE ALL!!!!
+////////////////////////////////////////
+// NO NEW FILES!!!!!!!!!
+////////////////////////////////////////
+
+/*
+░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+*/
+// ##                                                                                                               REQUIREMENTS 'R'
+/*
+░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+*/
+
+
+/*
+§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§
+*/
+// ###                                                                                                         DEFINITIONS, VALIDATIONS, AND TRANSFORMATIONS 'R_DVT'
+/*
+§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§
+*/
+
+
+/*
+######################################################################################################################################################################################################
+*/
+// ####                                                                                                    GLOBAL 'R_DVT_G' - Imports & Configuration
+/*
+######################################################################################################################################################################################################
+*/
+
+import { readFile, writeFile } from 'fs/promises';
+import { basename } from 'path';
+
+import type {
+  McpServerConfig,
+  AnalyzeContractInput,
+  AnalyzeContractOutput,
+  GetAnalysisStatusInput,
+  AnalysisStatusOutput,
+  AskSacInput,
+  SacResponseOutput,
+  GenerateRedlineInput,
+  RedlineOutput,
+  GenerateNegotiationEmailInput,
+  NegotiationEmailOutput,
+  ExtractClauseInput,
+  ClauseExtractionOutput,
+  ComparePlaybookInput,
+  PlaybookComparisonOutput,
+  BitsBoundApiResponse,
+  StartAnalysisResponse,
+  AnalysisProgressResponse,
+  // Instant Swarm - Parallel Section Redlining
+  InstantSwarmInput,
+  InstantSwarmOutput,
+  // Quick Tools
+  QuickScanInput,
+  QuickScanOutput,
+  AskClauseInput,
+  AskClauseOutput,
+  CheckDealbreakersInput,
+  CheckDealbreakersOutput,
+  // File Download
+  DownloadFileInput
+} from '../../types/Bitsbound_Kings_McpServer_Backend_Types.js';
+import { DEFAULT_API_URL } from '../../types/Bitsbound_Kings_McpServer_Backend_Types.js';
+import { apiLogger } from '../../logger/Bitsbound_Kings_McpServer_Backend_Logger.js';
+
+
+/*
+❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅
+*/
+// #####                                                                                               DEFINITIONS 'R_DVT_G_D' - Backautocrat Class
+/*
+❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅
+*/
+
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+// Backautocrat 'R_DVT_G_D_Backautocrat' - Orchestrates API calls to BitsBound SaaS backend
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+export class BitsBoundBackautocrat {
+  private readonly apiUrl: string;
+  private readonly apiKey: string;
+
+  constructor(config: McpServerConfig) {
+    this.apiUrl = config.BITSBOUND_API_URL || DEFAULT_API_URL;
+    this.apiKey = config.BITSBOUND_API_KEY;
+
+    if (!this.apiKey) {
+      throw new Error('BITSBOUND_API_KEY is required');
+    }
+  }
+
+  // ────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+  // Private: HTTP Request Helper 'R_DVT_G_T_Request'
+  // ────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+  private async request<T>(
+    method: 'GET' | 'POST',
+    endpoint: string,
+    body?: Record<string, unknown>
+  ): Promise<BitsBoundApiResponse<T>> {
+    const url = `${this.apiUrl}${endpoint}`;
+
+    apiLogger.debug('Making API request', { method, endpoint });
+
+    try {
+      const response = await fetch(url, {
+        method,
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${this.apiKey}`,
+          'X-MCP-Client': 'bitsbound-mcp-server/1.0.0'
+        },
+        body: body ? JSON.stringify(body) : undefined
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        apiLogger.error('API request failed', {
+          status: response.status,
+          error: errorText
+        });
+        return {
+          success: false,
+          error: `API error ${response.status}: ${errorText}`
+        };
+      }
+
+      const data = await response.json() as T;
+      apiLogger.debug('API request successful', { endpoint });
+
+      return { success: true, data };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      apiLogger.error('API request exception', { error: errorMessage });
+      return {
+        success: false,
+        error: `Request failed: ${errorMessage}`
+      };
+    }
+  }
+
+
+/*
+######################################################################################################################################################################################################
+*/
+// ####                                                                                                         LOCAL 'R_DVT_L' - Tool Handler Methods
+/*
+######################################################################################################################################################################################################
+*/
+
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+  // Tool: process_contract 'R_DVT_L_T_ProcessContract'
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+  async analyzeContract(input: AnalyzeContractInput): Promise<AnalyzeContractOutput> {
+    let docxBase64: string;
+    let fileName: string;
+
+    // Handle filePath (RECOMMENDED) or docxBase64
+    if (input.filePath) {
+      // Read file from disk and base64 encode it
+      apiLogger.info('Reading contract from file path', { filePath: input.filePath });
+      try {
+        const fileBuffer = await readFile(input.filePath);
+        docxBase64 = fileBuffer.toString('base64');
+        fileName = input.fileName || basename(input.filePath);
+        apiLogger.info('File read successfully', { fileName, sizeBytes: fileBuffer.length });
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        apiLogger.error('Failed to read file', { filePath: input.filePath, error: errorMessage });
+        throw new Error(`Failed to read file at ${input.filePath}: ${errorMessage}`);
+      }
+    } else if (input.docxBase64) {
+      // Use provided base64
+      docxBase64 = input.docxBase64;
+      fileName = input.fileName || 'contract.docx';
+    } else {
+      throw new Error('Either filePath or docxBase64 is required. Use filePath for best results (e.g., "/Users/you/Documents/contract.docx")');
+    }
+
+    apiLogger.info('Starting contract analysis', { fileName });
+
+    const response = await this.request<StartAnalysisResponse>(
+      'POST',
+      '/api/v1/mcp/analyze',
+      {
+        contract_content: docxBase64,
+        filename: fileName,
+        analysis_type: input.analysisDepth || 'standard',
+        perspective: input.perspective || 'customer'
+      }
+    );
+
+    if (!response.success || !response.data) {
+      throw new Error(response.error || 'Failed to start analysis');
+    }
+
+    return {
+      analysisId: response.data.analysisId,
+      status: 'queued',
+      estimatedTimeMinutes: response.data.estimatedMinutes,
+      initialRiskSummary: 'Analysis queued. Use get_analysis_status to check progress.'
+    };
+  }
+
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+  // Tool: get_analysis_status 'R_DVT_L_T_GetStatus'
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+  async getAnalysisStatus(input: GetAnalysisStatusInput): Promise<AnalysisStatusOutput> {
+    apiLogger.info('Checking analysis status', { analysisId: input.analysisId });
+
+    const response = await this.request<AnalysisProgressResponse>(
+      'GET',
+      `/api/v1/mcp/analysis/${input.analysisId}/status`
+    );
+
+    if (!response.success || !response.data) {
+      throw new Error(response.error || 'Failed to get analysis status');
+    }
+
+    const data = response.data;
+    return {
+      analysisId: data.analysisId,
+      status: data.status as AnalysisStatusOutput['status'],
+      progressPercent: data.progress,
+      currentPhase: data.phase,
+      phasesCompleted: data.phasesCompleted,
+      favorabilityScore: data.results?.favorabilityScore,
+      topRisks: data.results?.topRisks.map((r: { severity: string; section: string; risk: string }) => `[${r.severity.toUpperCase()}] ${r.section}: ${r.risk}`)
+    };
+  }
+
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+  // Tool: ask_sac 'R_DVT_L_T_AskSac'
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+  async askSac(input: AskSacInput): Promise<SacResponseOutput> {
+    apiLogger.info('Asking SAC', { analysisId: input.analysisId });
+
+    const response = await this.request<{
+      response: string;
+      citations?: Array<{ section: string; text: string; page?: number }>;
+      suggestions?: string[];
+    }>(
+      'POST',
+      '/api/v1/mcp/sac/chat',
+      {
+        analysisId: input.analysisId,
+        question: input.question,
+        includeClauseCitations: input.includeClauseCitations ?? true
+      }
+    );
+
+    if (!response.success || !response.data) {
+      throw new Error(response.error || 'Failed to get SAC response');
+    }
+
+    return {
+      response: response.data.response,
+      clauseCitations: response.data.citations?.map((c: { section: string; text: string; page?: number }) => ({
+        sectionName: c.section,
+        clauseText: c.text,
+        pageNumber: c.page
+      })),
+      followUpSuggestions: response.data.suggestions
+    };
+  }
+
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+  // Tool: generate_redline 'R_DVT_L_T_GenerateRedline'
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+  async generateRedline(input: GenerateRedlineInput): Promise<RedlineOutput> {
+    apiLogger.info('Generating redline', { analysisId: input.analysisId });
+
+    const response = await this.request<{
+      docxBase64: string;
+      downloadUrl: string;
+      changesCount: number;
+      summary: string;
+    }>(
+      'POST',
+      '/api/v1/mcp/redline/generate',
+      {
+        analysisId: input.analysisId,
+        aggressiveness: input.aggressiveness ?? 3,
+        includeComments: input.includeComments ?? true
+      }
+    );
+
+    if (!response.success || !response.data) {
+      throw new Error(response.error || 'Failed to generate redline');
+    }
+
+    return {
+      redlinedDocxBase64: response.data.docxBase64,
+      downloadUrl: response.data.downloadUrl,
+      changesCount: response.data.changesCount,
+      changesSummary: response.data.summary
+    };
+  }
+
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+  // Tool: generate_negotiation_email 'R_DVT_L_T_GenerateEmail'
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+  async generateNegotiationEmail(input: GenerateNegotiationEmailInput): Promise<NegotiationEmailOutput> {
+    apiLogger.info('Generating negotiation email', { analysisId: input.analysisId });
+
+    const response = await this.request<{
+      subject: string;
+      body: string;
+      keyPoints: string[];
+    }>(
+      'POST',
+      '/api/v1/mcp/email/generate',
+      {
+        analysisId: input.analysisId,
+        tone: input.tone ?? 'collaborative',
+        recipientRole: input.recipientRole
+      }
+    );
+
+    if (!response.success || !response.data) {
+      throw new Error(response.error || 'Failed to generate email');
+    }
+
+    return response.data;
+  }
+
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+  // Tool: extract_clause 'R_DVT_L_T_ExtractClause'
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+  async extractClause(input: ExtractClauseInput): Promise<ClauseExtractionOutput> {
+    apiLogger.info('Extracting clause', {
+      analysisId: input.analysisId,
+      clauseType: input.clauseType
+    });
+
+    const response = await this.request<{
+      clauseType: string;
+      clauseText: string;
+      riskLevel: 'low' | 'medium' | 'high' | 'critical';
+      riskAnalysis: string;
+      suggestedImprovements: string[];
+      marketComparison?: string;
+    }>(
+      'GET',
+      `/api/v1/mcp/analysis/${input.analysisId}/clause/${input.clauseType}`
+    );
+
+    if (!response.success || !response.data) {
+      throw new Error(response.error || 'Failed to extract clause');
+    }
+
+    return response.data;
+  }
+
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+  // Tool: compare_playbook 'R_DVT_L_T_ComparePlaybook'
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+  async comparePlaybook(input: ComparePlaybookInput): Promise<PlaybookComparisonOutput> {
+    apiLogger.info('Comparing against playbook', {
+      analysisId: input.analysisId,
+      playbookId: input.playbookId
+    });
+
+    const response = await this.request<{
+      deviations: Array<{
+        section: string;
+        playbookRequirement: string;
+        actualClause: string;
+        severity: 'minor' | 'moderate' | 'major';
+        recommendation: string;
+      }>;
+      complianceScore: number;
+      requiredApprovals: string[];
+    }>(
+      'POST',
+      '/api/v1/mcp/playbook/compare',
+      {
+        analysisId: input.analysisId,
+        playbookId: input.playbookId
+      }
+    );
+
+    if (!response.success || !response.data) {
+      throw new Error(response.error || 'Failed to compare playbook');
+    }
+
+    return response.data;
+  }
+
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+  // Resource: Get Analysis Results 'R_DVT_L_T_GetAnalysis'
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+  async getAnalysisResults(analysisId: string): Promise<Record<string, unknown>> {
+    apiLogger.info('Fetching full analysis results', { analysisId });
+
+    const response = await this.request<Record<string, unknown>>(
+      'GET',
+      `/api/v1/mcp/analysis/${analysisId}/full`
+    );
+
+    if (!response.success || !response.data) {
+      throw new Error(response.error || 'Failed to fetch analysis');
+    }
+
+    return response.data;
+  }
+
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+  // Resource: Get Playbook 'R_DVT_L_T_GetPlaybook'
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+  async getPlaybook(playbookId: string): Promise<Record<string, unknown>> {
+    apiLogger.info('Fetching playbook', { playbookId });
+
+    const response = await this.request<Record<string, unknown>>(
+      'GET',
+      `/api/v1/mcp/playbook/${playbookId}`
+    );
+
+    if (!response.success || !response.data) {
+      throw new Error(response.error || 'Failed to fetch playbook');
+    }
+
+    return response.data;
+  }
+
+
+/*
+######################################################################################################################################################################################################
+*/
+// ####                                                                                                         INSTANT SWARM 'R_DVT_L_InstantSwarm' - Parallel Section Redlining
+/*
+######################################################################################################################################################################################################
+*/
+
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+  // Tool: instant_swarm 'R_DVT_L_T_InstantSwarm' - Parallel redlining across ALL sections simultaneously
+  // Spawns N agents for N sections (dynamic - not fixed) for maximum parallelization
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+  async instantSwarm(input: InstantSwarmInput): Promise<InstantSwarmOutput> {
+    apiLogger.info('Starting Instant Swarm - parallel section redlining', {
+      analysisId: input.analysisId,
+      aggressivenessLevel: input.aggressivenessLevel,
+      partyPosition: input.partyPosition,
+      targetSections: input.targetSections || 'all'
+    });
+
+    // T: Call the existing /api/v1/sac/autopilot/swarm endpoint on the SaaS backend
+    // This endpoint spawns N parallel SAC sessions for N sections, each writing to isolated R2 branches
+    const response = await this.request<{
+      success: boolean;
+      totalSections: number;
+      completedSections: number;
+      failedSections: number;
+      mergedDocumentPath?: string;
+      mergedDocumentBase64?: string;
+      sectionResults: Array<{
+        sectionId: string;
+        sectionName: string;
+        success: boolean;
+        redlinesApplied: number;
+        commentsApplied: number;
+        keyChanges?: string[];
+        error?: string;
+        executionTimeMs: number;
+      }>;
+      totalRedlinesApplied: number;
+      totalCommentsApplied: number;
+      executionTimeMs: number;
+      tokenUsage?: {
+        inputTokens: number;
+        outputTokens: number;
+      };
+    }>(
+      'POST',
+      '/api/v1/mcp/instant/swarm',  // MCP-specific endpoint that wraps /sac/autopilot/swarm
+      {
+        analysisId: input.analysisId,
+        aggressivenessLevel: input.aggressivenessLevel,
+        partyPosition: input.partyPosition,
+        ourPartyName: input.ourPartyName,
+        counterpartyName: input.counterpartyName,
+        targetSections: input.targetSections
+      }
+    );
+
+    if (!response.success || !response.data) {
+      throw new Error(response.error || 'Failed to execute Instant Swarm');
+    }
+
+    const data = response.data;
+
+    return {
+      success: data.success,
+      totalSections: data.totalSections,
+      completedSections: data.completedSections,
+      failedSections: data.failedSections,
+      redlinedDocumentBase64: data.mergedDocumentBase64,
+      redlinedDocumentUrl: data.mergedDocumentPath,
+      sectionResults: data.sectionResults.map(sr => ({
+        sectionId: sr.sectionId,
+        sectionName: sr.sectionName,
+        success: sr.success,
+        redlinesApplied: sr.redlinesApplied,
+        commentsApplied: sr.commentsApplied,
+        keyChanges: sr.keyChanges,
+        error: sr.error,
+        executionTimeMs: sr.executionTimeMs
+      })),
+      totalRedlinesApplied: data.totalRedlinesApplied,
+      totalCommentsApplied: data.totalCommentsApplied,
+      executionTimeMs: data.executionTimeMs,
+      tokenUsage: data.tokenUsage
+    };
+  }
+
+
+/*
+######################################################################################################################################################################################################
+*/
+// ####                                                                                                         QUICK TOOLS 'R_DVT_L_QuickTools' - Immediate Analysis
+/*
+######################################################################################################################################################################################################
+*/
+
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+  // Tool: quick_scan 'R_DVT_L_T_QuickScan' - Instant contract analysis (5-10 seconds)
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+  async quickScan(input: QuickScanInput): Promise<QuickScanOutput> {
+    apiLogger.info('Starting quick scan', {
+      fileName: input.fileName,
+      perspective: input.perspective || 'customer'
+    });
+
+    const response = await this.request<QuickScanOutput>(
+      'POST',
+      '/api/v1/mcp/instant/quick-scan',
+      {
+        contractText: input.contractText,
+        fileName: input.fileName,
+        perspective: input.perspective || 'customer'
+      }
+    );
+
+    if (!response.success || !response.data) {
+      throw new Error(response.error || 'Failed to perform quick scan');
+    }
+
+    return response.data;
+  }
+
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+  // Tool: ask_clause 'R_DVT_L_T_AskClause' - Instant clause Q&A (2-5 seconds)
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+  async askClause(input: AskClauseInput): Promise<AskClauseOutput> {
+    apiLogger.info('Asking about clause', {
+      question: input.question.substring(0, 50) + '...',
+      clauseType: input.clauseType || 'any'
+    });
+
+    const response = await this.request<AskClauseOutput>(
+      'POST',
+      '/api/v1/mcp/instant/ask-clause',
+      {
+        contractText: input.contractText,
+        question: input.question,
+        clauseType: input.clauseType || 'any'
+      }
+    );
+
+    if (!response.success || !response.data) {
+      throw new Error(response.error || 'Failed to get clause answer');
+    }
+
+    return response.data;
+  }
+
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+  // Tool: check_dealbreakers 'R_DVT_L_T_CheckDealbreakers' - Instant playbook compliance (3-5 seconds)
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+  async checkDealbreakers(input: CheckDealbreakersInput): Promise<CheckDealbreakersOutput> {
+    apiLogger.info('Checking dealbreakers', {
+      playbookId: input.playbookId || 'default'
+    });
+
+    const response = await this.request<CheckDealbreakersOutput>(
+      'POST',
+      '/api/v1/mcp/instant/check-dealbreakers',
+      {
+        contractText: input.contractText,
+        playbookId: input.playbookId
+      }
+    );
+
+    if (!response.success || !response.data) {
+      throw new Error(response.error || 'Failed to check dealbreakers');
+    }
+
+    return response.data;
+  }
+
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+  // Download File 'R_DVT_L_T_DownloadFile' - Download file from R2 via MCP endpoint
+  // ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+  /**
+   * T_DOWNLOAD_FILE: Download a file from BitsBound R2 storage
+   *
+   * TIR{ADVT}O Context:
+   * - T: User requests to download a file (e.g., redlined DOCX)
+   * - I: downloadUrl from get_analysis_status deliverables
+   * - R{ADVT}:
+   *   - D: MCP download endpoint URL pattern
+   *   - V: URL must be a valid BitsBound download URL
+   *   - T: Fetch file via HTTP, optionally save to disk
+   * - O: { success, base64Content, savedToPath?, fileName, fileSizeBytes }
+   */
+  async downloadFile(input: DownloadFileInput): Promise<{
+    success: boolean;
+    base64Content?: string;
+    savedToPath?: string;
+    fileName?: string;
+    fileSizeBytes?: number;
+    error?: string;
+  }> {
+    const { downloadUrl, saveToPath } = input;
+
+    apiLogger.info('Downloading file', { downloadUrl, saveToPath });
+
+    try {
+      // The download URL is a full URL - just fetch it with auth header
+      const response = await fetch(downloadUrl, {
+        method: 'GET',
+        headers: {
+          'X-API-Key': this.apiKey
+        }
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`Download failed: ${response.status} ${response.statusText} - ${errorText}`);
+      }
+
+      // Get the file as ArrayBuffer
+      const arrayBuffer = await response.arrayBuffer();
+      const buffer = Buffer.from(arrayBuffer);
+
+      // Extract filename from Content-Disposition header or URL
+      const contentDisposition = response.headers.get('Content-Disposition');
+      let fileName = 'document.docx';
+      if (contentDisposition) {
+        const match = contentDisposition.match(/filename="?([^"]+)"?/);
+        if (match) {
+          fileName = match[1];
+        }
+      } else {
+        // Try to extract from URL
+        const urlParts = downloadUrl.split('/');
+        const lastPart = urlParts[urlParts.length - 1];
+        if (lastPart && !lastPart.includes('?')) {
+          fileName = decodeURIComponent(lastPart);
+        }
+      }
+
+      // If saveToPath is provided, write to disk
+      if (saveToPath) {
+        await writeFile(saveToPath, buffer);
+        apiLogger.info('File saved to disk', { path: saveToPath, size: buffer.length });
+
+        return {
+          success: true,
+          savedToPath: saveToPath,
+          fileName,
+          fileSizeBytes: buffer.length
+        };
+      }
+
+      // Otherwise, return as base64
+      const base64Content = buffer.toString('base64');
+      apiLogger.info('File downloaded as base64', { fileName, size: buffer.length });
+
+      return {
+        success: true,
+        base64Content,
+        fileName,
+        fileSizeBytes: buffer.length
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      apiLogger.error('Download failed', { error: errorMessage });
+
+      return {
+        success: false,
+        error: errorMessage
+      };
+    }
+  }
+}