@bitsbound/mcp-server 1.0.5 → 1.0.6

package/types/Bitsbound_Kings_McpServer_Backend_Types.ts

@@ -0,0 +1,1667 @@
+////////////////////////////////////////
+// # GOLDEN RULE!!!! HONOR ABOVE ALL!!!!
+////////////////////////////////////////
+// NO NEW FILES!!!!!!!!!
+////////////////////////////////////////
+
+/*
+░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+*/
+// ##                                                                                                               REQUIREMENTS 'R'
+/*
+░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+*/
+
+
+/*
+§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§
+*/
+// ###                                                                                                         DEFINITIONS, VALIDATIONS, AND TRANSFORMATIONS 'R_DVT'
+/*
+§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§§
+*/
+
+
+/*
+######################################################################################################################################################################################################
+*/
+// ####                                                                                                    GLOBAL 'R_DVT_G', i.e., File/Agreement Level DVTs
+/*
+######################################################################################################################################################################################################
+*/
+
+
+/*
+❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅
+*/
+// #####                                                                                               DEFINITIONS 'R_DVT_G_D' - MCP Server Configuration & API Types
+/*
+❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅❅
+*/
+
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+// MCP Server Configuration 'R_DVT_G_D_Config'
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+export interface McpServerConfig {
+  readonly BITSBOUND_API_URL: string;
+  readonly BITSBOUND_API_KEY: string;
+}
+
+export const DEFAULT_API_URL = 'https://bitsbound-saas-backend-mxb1.onrender.com';
+
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+// Tool Input Schemas 'R_DVT_G_D_ToolInputs' - What AI platforms send to each tool
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+export interface AnalyzeContractInput {
+  readonly filePath?: string;           // RECOMMENDED: Absolute path to DOCX file on disk
+  readonly docxBase64?: string;         // Alternative: Base64-encoded DOCX content
+  readonly fileName?: string;           // Optional if using filePath (extracted from path)
+  readonly analysisDepth?: 'quick' | 'standard' | 'deep';
+  readonly perspective?: 'customer' | 'vendor' | 'neutral';
+}
+
+export interface GetAnalysisStatusInput {
+  readonly analysisId: string;
+}
+
+export interface AskSacInput {
+  readonly analysisId: string;
+  readonly question: string;
+  readonly includeClauseCitations?: boolean;
+}
+
+export interface GenerateRedlineInput {
+  readonly analysisId: string;
+  readonly aggressiveness?: 1 | 2 | 3 | 4 | 5;
+  readonly includeComments?: boolean;
+}
+
+export interface GenerateNegotiationEmailInput {
+  readonly analysisId: string;
+  readonly tone?: 'collaborative' | 'firm' | 'aggressive';
+  readonly recipientRole?: string;
+}
+
+export interface ExtractClauseInput {
+  readonly analysisId: string;
+  readonly clauseType: 'indemnification' | 'liability' | 'ip' | 'termination' | 'payment' | 'confidentiality' | 'data_privacy' | 'sla' | 'force_majeure' | 'assignment';
+}
+
+export interface ComparePlaybookInput {
+  readonly analysisId: string;
+  readonly playbookId: string;
+}
+
+export interface DownloadFileInput {
+  readonly downloadUrl: string;
+  readonly saveToPath?: string;
+}
+
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+// INSTANT SWARM Input Schemas 'R_DVT_G_D_InstantSwarmInputs' - Parallel 17-Section Redlining
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+/**
+ * InstantSwarmInput - Parallel redlining of entire contract across all 17 BUBSA sections
+ * D: Input for spawning parallel SAC sessions that independently analyze and redline each section
+ *
+ * TIR{ADVT}O Context:
+ * - T: User requests instant parallel redlining of entire contract
+ * - I: Analysis context + aggressiveness + party position
+ * - R: Spawns 17 parallel SAC sessions (one per BUBSA section), no lock contention
+ * - O: Merged redlined DOCX + per-section results
+ */
+export interface InstantSwarmInput {
+  readonly analysisId: string;                           // ID of completed TCA analysis (provides contract context)
+  readonly aggressivenessLevel: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10;  // How aggressive redlines should be (1-10)
+  readonly partyPosition: 'customer' | 'vendor';         // Whose side are we on?
+  readonly ourPartyName?: string;                        // Our company name (for proper party references)
+  readonly counterpartyName?: string;                    // Counterparty name
+  readonly targetSections?: string[];                    // Optional: specific BUBSA sections to analyze (default: all 17)
+}
+
+/**
+ * QuickScanInput - Instant contract analysis (5-10 seconds)
+ * D: Input for immediate risk scan and classification without full pipeline
+ */
+export interface QuickScanInput {
+  readonly contractText: string;           // Raw contract text (or base64 DOCX)
+  readonly fileName?: string;              // Optional filename for context
+  readonly perspective?: 'customer' | 'vendor' | 'neutral';
+}
+
+/**
+ * AskClauseInput - Instant clause Q&A without prior analysis
+ * D: Ask about specific clauses directly from contract text
+ */
+export interface AskClauseInput {
+  readonly contractText: string;           // Raw contract text
+  readonly question: string;               // What to find/explain
+  readonly clauseType?: 'indemnification' | 'liability' | 'ip' | 'termination' | 'payment' | 'confidentiality' | 'data_privacy' | 'sla' | 'force_majeure' | 'assignment' | 'any';
+}
+
+/**
+ * CheckDealbreakersInput - Quick playbook compliance check
+ * D: Fast check for must-have clauses and dealbreakers
+ */
+export interface CheckDealbreakersInput {
+  readonly contractText: string;           // Raw contract text
+  readonly playbookId?: string;            // Optional specific playbook (default: customer's default)
+}
+
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+// Tool Output Types 'R_DVT_G_D_ToolOutputs' - What tools return to AI platforms
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+export interface AnalyzeContractOutput {
+  readonly analysisId: string;
+  readonly status: 'queued' | 'processing' | 'completed' | 'failed';
+  readonly estimatedTimeMinutes: number;
+  readonly initialRiskSummary?: string;
+}
+
+/**
+ * AnalysisStatusOutput - Status of running/completed analysis
+ * D: Reports progress through the 8-stage TCA pipeline:
+ *    1. Loading Context - Parsing deal context and contract structure
+ *    2. Extracting Data - Running 13 deterministic extraction scripts
+ *    3. Identifying Parties - AI identifying customer and vendor
+ *    4. Researching - Running 8 parallel research analyzers
+ *    5. AI Analysis - Running 18 parallel AI analyzers
+ *    6. Instant Swarm™ - Parallel redlining across all sections (if enabled)
+ *    7. Generating Email - Drafting negotiation email (if enabled)
+ *    8. Synthesizing Results - Generating recommendations and scores
+ */
+export interface AnalysisStatusOutput {
+  readonly analysisId: string;
+  readonly status: 'queued' | 'processing' | 'completed' | 'failed';
+  readonly progressPercent: number;
+  readonly currentPhase: string;
+  readonly phasesCompleted: string[];
+  readonly favorabilityScore?: number;
+  readonly topRisks?: string[];
+}
+
+export interface SacResponseOutput {
+  readonly response: string;
+  readonly clauseCitations?: ClauseCitation[];
+  readonly followUpSuggestions?: string[];
+}
+
+export interface ClauseCitation {
+  readonly sectionName: string;
+  readonly clauseText: string;
+  readonly pageNumber?: number;
+}
+
+export interface RedlineOutput {
+  readonly redlinedDocxBase64: string;
+  readonly downloadUrl: string;
+  readonly changesCount: number;
+  readonly changesSummary: string;
+}
+
+export interface NegotiationEmailOutput {
+  readonly subject: string;
+  readonly body: string;
+  readonly keyPoints: string[];
+}
+
+export interface ClauseExtractionOutput {
+  readonly clauseType: string;
+  readonly clauseText: string;
+  readonly riskLevel: 'low' | 'medium' | 'high' | 'critical';
+  readonly riskAnalysis: string;
+  readonly suggestedImprovements: string[];
+  readonly marketComparison?: string;
+}
+
+export interface PlaybookComparisonOutput {
+  readonly deviations: PlaybookDeviation[];
+  readonly complianceScore: number;
+  readonly requiredApprovals: string[];
+}
+
+export interface PlaybookDeviation {
+  readonly section: string;
+  readonly playbookRequirement: string;
+  readonly actualClause: string;
+  readonly severity: 'minor' | 'moderate' | 'major';
+  readonly recommendation: string;
+}
+
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+// INSTANT SWARM Output Types 'R_DVT_G_D_InstantSwarmOutputs' - Parallel Redlining Results
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+/**
+ * InstantSwarmOutput - Results from parallel N-section redlining
+ * D: Contains merged document + per-section analysis results
+ *
+ * TIR{ADVT}O Context:
+ * - Output from parallel SAC swarm execution
+ * - N agents for N sections (dynamic, not fixed)
+ * - Each section analyzed independently, then merged
+ * - Real OOXML Track Changes applied to original document
+ */
+export interface InstantSwarmOutput {
+  readonly success: boolean;
+  readonly totalSections: number;                        // Total sections analyzed (N sections = N agents)
+  readonly completedSections: number;                    // Successfully completed sections
+  readonly failedSections: number;                       // Sections that failed (errors)
+  readonly redlinedDocumentBase64?: string;              // Merged redlined DOCX (base64 encoded)
+  readonly redlinedDocumentUrl?: string;                 // Download URL for redlined document
+  readonly sectionResults: InstantSwarmSectionResult[];  // Per-section breakdown
+  readonly totalRedlinesApplied: number;                 // Total Track Changes across all sections
+  readonly totalCommentsApplied: number;                 // Total margin comments added
+  readonly executionTimeMs: number;                      // Total execution time
+  readonly tokenUsage?: {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+  };
+}
+
+/**
+ * InstantSwarmSectionResult - Results for a single BUBSA section
+ * D: Individual section analysis from the swarm
+ */
+export interface InstantSwarmSectionResult {
+  readonly sectionId: string;                            // BUBSA section ID (e.g., "ip_license", "liability")
+  readonly sectionName: string;                          // Human-readable name (e.g., "IP License Grant")
+  readonly success: boolean;                             // Did this section complete successfully?
+  readonly redlinesApplied: number;                      // Track Changes for this section
+  readonly commentsApplied: number;                      // Comments for this section
+  readonly keyChanges?: string[];                        // Summary of major changes made
+  readonly error?: string;                               // Error message if failed
+  readonly executionTimeMs: number;                      // Time for this section
+}
+
+/**
+ * QuickScanOutput - Instant analysis results (5-10 seconds)
+ * D: Immediate risk assessment without full pipeline
+ */
+export interface QuickScanOutput {
+  readonly contractType: string;                    // "Master Service Agreement", "SaaS Agreement", etc.
+  readonly parties: {
+    readonly customer: string;
+    readonly vendor: string;
+  };
+  readonly favorabilityEstimate: number;            // 0-100 score
+  readonly favorabilityLabel: 'Customer-Favorable' | 'Balanced' | 'Vendor-Favorable' | 'Heavily Vendor-Favorable';
+  readonly topConcerns: Array<{
+    readonly severity: 'critical' | 'high' | 'medium' | 'low';
+    readonly category: string;                      // "Liability", "IP", "Termination", etc.
+    readonly summary: string;                       // Brief description
+  }>;
+  readonly keyTerms: {
+    readonly term?: string;                         // "3 years, auto-renew"
+    readonly paymentTerms?: string;                 // "Net 30, annual prepay"
+    readonly liabilityCap?: string;                 // "$1M" or "Unlimited (CRITICAL)"
+    readonly terminationNotice?: string;            // "90 days"
+    readonly governingLaw?: string;                 // "Delaware"
+  };
+  readonly missingSections: string[];               // BUBSA sections not found
+  readonly recommendation: string;                  // "Proceed with caution" / "Recommend full analysis"
+}
+
+/**
+ * AskClauseOutput - Instant clause Q&A response
+ * D: Direct answer about specific clauses
+ */
+export interface AskClauseOutput {
+  readonly answer: string;                          // Natural language answer
+  readonly clauseText?: string;                     // Extracted clause if found
+  readonly clauseLocation?: string;                 // "Section 8.2", "Page 12"
+  readonly riskAssessment?: {
+    readonly level: 'low' | 'medium' | 'high' | 'critical';
+    readonly explanation: string;
+  };
+  readonly suggestedFollowUp?: string[];            // Related questions to ask
+}
+
+/**
+ * CheckDealbreakersOutput - Quick compliance check results
+ * D: Fast identification of dealbreakers and missing requirements
+ */
+export interface CheckDealbreakersOutput {
+  readonly passesInitialScreen: boolean;            // Quick go/no-go
+  readonly dealbreakers: Array<{
+    readonly issue: string;
+    readonly severity: 'blocker' | 'major' | 'minor';
+    readonly requirement: string;                   // What the playbook requires
+    readonly actual: string;                        // What the contract has
+  }>;
+  readonly missingRequirements: string[];           // Required clauses not found
+  readonly approvalsNeeded: string[];               // Who needs to sign off
+  readonly recommendation: 'proceed' | 'negotiate' | 'escalate' | 'reject';
+}
+
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+// BitsBound SaaS API Types 'R_DVT_G_D_ApiTypes' - For calling the backend
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+export interface BitsBoundApiResponse<T> {
+  readonly success: boolean;
+  readonly data?: T;
+  readonly error?: string;
+  readonly tokenUsage?: number;
+}
+
+export interface StartAnalysisResponse {
+  readonly analysisId: string;
+  readonly status: string;
+  readonly estimatedMinutes: number;
+}
+
+export interface AnalysisProgressResponse {
+  readonly analysisId: string;
+  readonly status: string;
+  readonly progress: number;
+  readonly phase: string;
+  readonly phasesCompleted: string[];
+  readonly results?: AnalysisResults;
+}
+
+export interface AnalysisResults {
+  readonly favorabilityScore: number;
+  readonly topRisks: RiskItem[];
+  readonly sections: SectionAnalysis[];
+  readonly negotiationPriorities: string[];
+}
+
+export interface RiskItem {
+  readonly section: string;
+  readonly risk: string;
+  readonly severity: 'low' | 'medium' | 'high' | 'critical';
+  readonly recommendation: string;
+}
+
+export interface SectionAnalysis {
+  readonly sectionName: string;
+  readonly favorability: number;
+  readonly issues: string[];
+  readonly suggestedChanges: string[];
+}
+
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+// MCP Tool Definitions 'R_DVT_G_D_ToolDefs' - Tool schemas for MCP protocol
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+export const TOOL_DEFINITIONS = {
+  process_contract: {
+    name: 'process_contract',
+    description: 'Process a contract through the full 8-stage BitsBound pipeline: (1) Context Loading, (2) Data Extraction, (3) Party Identification, (4) Research, (5) AI Analysis with 18+ parallel analyzers, (6) Instant Swarm™ parallel redlining, (7) Negotiation Email Generation, (8) Synthesis. Returns a processing ID to track progress. Output includes: redlined DOCX with Track Changes, negotiation email, risk dashboard, and favorability scores. IMPORTANT: Provide EITHER filePath OR docxBase64 (not both). Using filePath is recommended.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        filePath: {
+          type: 'string',
+          description: 'RECOMMENDED: Absolute path to the DOCX file on disk (e.g., "/Users/john/Documents/contract.docx"). The server will read and encode the file automatically.'
+        },
+        docxBase64: {
+          type: 'string',
+          description: 'Alternative: The contract document already encoded as base64 string (DOCX format). Use filePath instead if possible.'
+        },
+        fileName: {
+          type: 'string',
+          description: 'Original filename of the document. If using filePath, this is extracted automatically.'
+        },
+        analysisDepth: {
+          type: 'string',
+          enum: ['quick', 'standard', 'deep'],
+          description: 'Analysis depth: quick (~5 min), standard (~15 min), deep (~30 min). Default: standard'
+        },
+        perspective: {
+          type: 'string',
+          enum: ['customer', 'vendor', 'neutral'],
+          description: 'Analyze from customer (buyer), vendor (seller), or neutral perspective. Default: customer'
+        }
+      },
+      required: []
+    },
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false
+    }
+  },
+
+  get_analysis_status: {
+    name: 'get_analysis_status',
+    description: 'Check the status of a running or completed contract analysis. Returns progress through the 8-stage pipeline (Context→Extraction→Parties→Research→Analysis→Swarm→Email→Synthesis). When complete, returns deliverables including: (1) redlinedDocxDownloadUrl - URL to download the redlined DOCX with Track Changes, (2) negotiationEmailHtml/negotiationEmailPlainText - the generated negotiation email content.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        analysisId: {
+          type: 'string',
+          description: 'The processing ID returned from process_contract'
+        }
+      },
+      required: ['analysisId']
+    },
+    annotations: {
+      readOnlyHint: true
+    }
+  },
+
+  ask_sac: {
+    name: 'ask_sac',
+    description: 'Ask the Supreme AI Co-Counsel (SAC) questions about an analyzed contract. SAC has full context of the contract and all analysis results. Great for clarifying risks, understanding clauses, or getting negotiation advice.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        analysisId: {
+          type: 'string',
+          description: 'The analysis ID of a completed analysis'
+        },
+        question: {
+          type: 'string',
+          description: 'Your question about the contract'
+        },
+        includeClauseCitations: {
+          type: 'boolean',
+          description: 'Include specific clause citations in the response. Default: true'
+        }
+      },
+      required: ['analysisId', 'question']
+    },
+    annotations: {
+      readOnlyHint: true
+    }
+  },
+
+  generate_redline: {
+    name: 'generate_redline',
+    description: 'Generate a redlined Word document with real OOXML Track Changes (w:ins, w:del) applied directly to the original document. Returns the redlined DOCX as base64.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        analysisId: {
+          type: 'string',
+          description: 'The analysis ID of a completed analysis'
+        },
+        aggressiveness: {
+          type: 'number',
+          enum: [1, 2, 3, 4, 5],
+          description: 'How aggressive the redlines should be (1=conservative, 5=aggressive). Default: 3'
+        },
+        includeComments: {
+          type: 'boolean',
+          description: 'Include rationale comments in Word margins. Default: true'
+        }
+      },
+      required: ['analysisId']
+    },
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false
+    }
+  },
+
+  generate_negotiation_email: {
+    name: 'generate_negotiation_email',
+    description: 'Generate a professional negotiation email to send to the counterparty, explaining requested changes and their rationale.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        analysisId: {
+          type: 'string',
+          description: 'The analysis ID of a completed analysis'
+        },
+        tone: {
+          type: 'string',
+          enum: ['collaborative', 'firm', 'aggressive'],
+          description: 'Tone of the email. Default: collaborative'
+        },
+        recipientRole: {
+          type: 'string',
+          description: 'Role of the recipient (e.g., "General Counsel", "Sales Rep", "Procurement"). Helps tailor the message.'
+        }
+      },
+      required: ['analysisId']
+    },
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false
+    }
+  },
+
+  extract_clause: {
+    name: 'extract_clause',
+    description: 'Extract and analyze a specific clause type from an analyzed contract. Returns the clause text, risk analysis, and suggested improvements.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        analysisId: {
+          type: 'string',
+          description: 'The analysis ID of a completed analysis'
+        },
+        clauseType: {
+          type: 'string',
+          enum: ['indemnification', 'liability', 'ip', 'termination', 'payment', 'confidentiality', 'data_privacy', 'sla', 'force_majeure', 'assignment'],
+          description: 'The type of clause to extract'
+        }
+      },
+      required: ['analysisId', 'clauseType']
+    },
+    annotations: {
+      readOnlyHint: true
+    }
+  },
+
+  compare_playbook: {
+    name: 'compare_playbook',
+    description: 'Compare an analyzed contract against a company playbook to identify deviations from pre-approved positions and required approvals.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        analysisId: {
+          type: 'string',
+          description: 'The analysis ID of a completed analysis'
+        },
+        playbookId: {
+          type: 'string',
+          description: 'The ID of the playbook to compare against'
+        }
+      },
+      required: ['analysisId', 'playbookId']
+    },
+    annotations: {
+      readOnlyHint: true
+    }
+  },
+
+  // ════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+  // INSTANT SWARM - Parallel N-Section Redlining (spawns N agents for N sections, max parallelization)
+  // ════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+  instant_swarm: {
+    name: 'instant_swarm',
+    description: 'PARALLEL REDLINING of entire contract. Spawns N independent SAC agents for N sections simultaneously - maximum parallelization with no lock contention. Each agent (IP, Liability, Indemnification, Payment, Term, etc.) independently analyzes and redlines its section, then all branches merge into a single DOCX with real Track Changes. Returns merged document + per-section results. Requires a completed analysis (use process_contract first). This is the flagship feature - full attorney-quality redlines across the entire contract in parallel.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        analysisId: {
+          type: 'string',
+          description: 'The analysis ID from a completed process_contract call. The analysis provides contract context for each section.'
+        },
+        aggressivenessLevel: {
+          type: 'number',
+          enum: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+          description: 'How aggressive the redlines should be (1=conservative, 10=very aggressive). Recommended: 5-7 for balanced approach.'
+        },
+        partyPosition: {
+          type: 'string',
+          enum: ['customer', 'vendor'],
+          description: 'Which side are you on? "customer" = you are buying/receiving services. "vendor" = you are selling/providing services.'
+        },
+        ourPartyName: {
+          type: 'string',
+          description: 'Your company name as it should appear in redlines (e.g., "Acme Corp").'
+        },
+        counterpartyName: {
+          type: 'string',
+          description: 'The other party\'s name (e.g., "Vendor Inc").'
+        },
+        targetSections: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Optional: specific BUBSA sections to analyze. If omitted, analyzes all 17 sections. Valid sections: parties, definitions, ip_license, payment, term_termination, confidentiality, data_privacy, reps_warranties, indemnification, liability, insurance, assignment, force_majeure, dispute_resolution, precedence, miscellaneous, sla'
+        }
+      },
+      required: ['analysisId', 'aggressivenessLevel', 'partyPosition']
+    },
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false
+    }
+  },
+
+  // ════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+  // QUICK TOOLS - Immediate analysis without waiting for full pipeline
+  // ════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+  quick_scan: {
+    name: 'quick_scan',
+    description: 'INSTANT contract analysis (5-10 seconds). Get immediate risk assessment, contract classification, top concerns, and key terms WITHOUT waiting for the full 15-30 minute analysis. Perfect for initial triage or quick questions. Use this FIRST before deciding if a full analysis is needed.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        contractText: {
+          type: 'string',
+          description: 'The contract text (plain text or base64-encoded DOCX). For DOCX files, base64 encode the file contents.'
+        },
+        fileName: {
+          type: 'string',
+          description: 'Optional filename for context (e.g., "Acme_MSA_2024.docx")'
+        },
+        perspective: {
+          type: 'string',
+          enum: ['customer', 'vendor', 'neutral'],
+          description: 'Analyze from customer (buyer), vendor (seller), or neutral perspective. Default: customer'
+        }
+      },
+      required: ['contractText']
+    },
+    annotations: {
+      readOnlyHint: true
+    }
+  },
+
+  ask_clause: {
+    name: 'ask_clause',
+    description: 'INSTANT clause Q&A (2-5 seconds). Ask about specific clauses directly WITHOUT needing a prior analysis. Examples: "What does the indemnification clause say?", "Is there a limitation of liability?", "What are the termination terms?"',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        contractText: {
+          type: 'string',
+          description: 'The contract text (plain text or base64-encoded DOCX)'
+        },
+        question: {
+          type: 'string',
+          description: 'Your question about the contract (e.g., "What is the liability cap?", "Is there an auto-renewal clause?")'
+        },
+        clauseType: {
+          type: 'string',
+          enum: ['indemnification', 'liability', 'ip', 'termination', 'payment', 'confidentiality', 'data_privacy', 'sla', 'force_majeure', 'assignment', 'any'],
+          description: 'Optional: Focus on a specific clause type, or "any" to search the whole contract. Default: any'
+        }
+      },
+      required: ['contractText', 'question']
+    },
+    annotations: {
+      readOnlyHint: true
+    }
+  },
+
+  check_dealbreakers: {
+    name: 'check_dealbreakers',
+    description: 'INSTANT dealbreaker check (3-5 seconds). Quick pass/fail screen against your playbook rules. Identifies blockers, missing required clauses, and who needs to approve. Use before spending time on full analysis.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        contractText: {
+          type: 'string',
+          description: 'The contract text (plain text or base64-encoded DOCX)'
+        },
+        playbookId: {
+          type: 'string',
+          description: 'Optional: Specific playbook to check against. If not provided, uses your default company playbook.'
+        }
+      },
+      required: ['contractText']
+    },
+    annotations: {
+      readOnlyHint: true
+    }
+  },
+
+  download_file: {
+    name: 'download_file',
+    description: 'Download a file from BitsBound (e.g., the redlined DOCX with Track Changes). Returns the file as base64-encoded content that can be saved locally. The downloadUrl is provided by get_analysis_status when analysis is complete.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        downloadUrl: {
+          type: 'string',
+          description: 'The download URL from get_analysis_status deliverables (redlinedDocxDownloadUrl)'
+        },
+        saveToPath: {
+          type: 'string',
+          description: 'Optional: Local file path to save the downloaded file. If not provided, returns base64 content.'
+        }
+      },
+      required: ['downloadUrl']
+    },
+    annotations: {
+      readOnlyHint: true
+    }
+  }
+} as const;
+
+export type ToolName = keyof typeof TOOL_DEFINITIONS;
+
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+// MCP Resource Definitions 'R_DVT_G_D_ResourceDefs' - Resources AI can read
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+export const RESOURCE_DEFINITIONS = {
+  analysis: {
+    uriTemplate: 'bitsbound://analysis/{analysisId}',
+    name: 'Contract Analysis',
+    description: 'Full analysis results including all 17 analyzer outputs, risk scores, and recommendations',
+    mimeType: 'application/json'
+  },
+  playbook: {
+    uriTemplate: 'bitsbound://playbook/{playbookId}',
+    name: 'Company Playbook',
+    description: 'Pre-approved clause library and negotiation rules',
+    mimeType: 'application/json'
+  },
+  redline: {
+    uriTemplate: 'bitsbound://redline/{analysisId}',
+    name: 'Redlined Contract',
+    description: 'The redlined DOCX with Track Changes',
+    mimeType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
+  }
+} as const;
+
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+// MCP Prompt Definitions 'R_DVT_G_D_PromptDefs' - User-facing workflow templates
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+/**
+ * PROMPT_DEFINITIONS - MCP Prompts for guiding users through BitsBound workflows
+ * D: These appear in claude.ai's "Add from BitsBound" menu as actionable items
+ *
+ * TIR{ADVT}O Context:
+ * - T: User selects a prompt from the menu
+ * - I: Prompt template with optional arguments
+ * - R: Claude receives structured instructions to guide the workflow
+ * - O: User experiences a smooth, guided contract analysis flow
+ */
+export const PROMPT_DEFINITIONS = {
+  process_contract: {
+    name: 'process_contract',
+    description: '📄 Process Contract - Upload a DOCX and get partner-level redlines with Track Changes, risk analysis, and a negotiation email',
+    arguments: []
+  },
+  quick_scan: {
+    name: 'quick_scan',
+    description: '⚡ Quick Risk Scan - Get instant risk assessment in 5-10 seconds without waiting for full analysis',
+    arguments: []
+  },
+  ask_about_contract: {
+    name: 'ask_about_contract',
+    description: '💬 Ask About a Clause - Upload a contract and ask specific questions about any clause or term',
+    arguments: []
+  },
+  check_dealbreakers: {
+    name: 'check_dealbreakers',
+    description: '🚨 Check Dealbreakers - Quick pass/fail check against your playbook rules',
+    arguments: []
+  },
+  continue_analysis: {
+    name: 'continue_analysis',
+    description: '📊 Continue Previous Analysis - Resume working with a previously analyzed contract',
+    arguments: [
+      {
+        name: 'analysisId',
+        description: 'The analysis ID from a previous contract analysis',
+        required: true
+      }
+    ]
+  }
+} as const;
+
+export type PromptName = keyof typeof PROMPT_DEFINITIONS;
+
+/**
+ * PROMPT_MESSAGES - The actual prompt content sent to Claude when user selects a prompt
+ * D: These guide Claude to ask for the right inputs and call the right tools
+ * NOTE: MCP spec requires content to be { type: 'text', text: string } not plain string
+ */
+export const PROMPT_MESSAGES: Record<PromptName, { role: 'user'; content: { type: 'text'; text: string } }[]> = {
+  process_contract: [
+    {
+      role: 'user',
+      content: { type: 'text', text: `I want to analyze a contract using BitsBound.
+
+Please help me by:
+1. Asking me to upload the contract file (DOCX format)
+2. Once I upload it, use the BitsBound 'process_contract' tool to analyze it
+3. IMPORTANT: After starting, automatically check progress every 2-3 minutes using 'get_analysis_status' - do NOT stop or wait for me to ask. Keep polling until status is 'complete' or 'failed'. Show me brief progress updates each time.
+4. When complete, show me:
+   - The favorability score (who the contract favors)
+   - Top 5 risks I should know about
+   - Recommended negotiation priorities
+   - Download link for the redlined DOCX (if available in deliverables)
+   - Summary of the negotiation email draft
+
+The analysis typically takes 15-30 minutes. Keep checking automatically until done.` }
+    }
+  ],
+  quick_scan: [
+    {
+      role: 'user',
+      content: { type: 'text', text: `I want a quick risk scan of a contract (5-10 seconds, not the full analysis).
+
+Please help me by:
+1. Asking me to upload or paste the contract
+2. Use the BitsBound 'quick_scan' tool for instant analysis
+3. Show me:
+   - Contract type and parties
+   - Favorability estimate
+   - Top concerns by severity
+   - Key terms (liability cap, term, payment, etc.)
+   - Whether I should do a full analysis
+
+This is for initial triage - not a substitute for full attorney review.` }
+    }
+  ],
+  ask_about_contract: [
+    {
+      role: 'user',
+      content: { type: 'text', text: `I want to ask questions about specific clauses in a contract.
+
+Please help me by:
+1. Asking me to upload or paste the contract (or relevant sections)
+2. Ask what I want to know (e.g., "What is the liability cap?", "Is there an auto-renewal?")
+3. Use the BitsBound 'ask_clause' tool for instant answers
+4. Include the actual clause text and any risk assessment
+
+I can ask multiple questions - this is a Q&A session about the contract.` }
+    }
+  ],
+  check_dealbreakers: [
+    {
+      role: 'user',
+      content: { type: 'text', text: `I want to check a contract for dealbreakers against my company's playbook.
+
+Please help me by:
+1. Asking me to upload or paste the contract
+2. Use the BitsBound 'check_dealbreakers' tool
+3. Show me:
+   - Pass/fail result
+   - Any dealbreaker issues found
+   - Missing required clauses
+   - Who needs to approve if we proceed
+
+This is a quick pre-screen before spending time on full analysis.` }
+    }
+  ],
+  continue_analysis: [
+    {
+      role: 'user',
+      content: { type: 'text', text: `I want to continue working with a previously analyzed contract.
+
+I have an analysis ID from a previous BitsBound analysis. Please:
+1. Ask me for the analysis ID
+2. Use 'get_analysis_status' to check if it's complete
+3. If complete, I can:
+   - Ask questions with 'ask_sac' (SAC has full context)
+   - Generate a redlined document with 'generate_redline'
+   - Generate a negotiation email with 'generate_negotiation_email'
+   - Extract specific clauses with 'extract_clause'
+   - Compare against a playbook with 'compare_playbook'
+
+What would you like to do with this analysis?` }
+    }
+  ]
+};
+
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+// OpenAPI Specification 'R_DVT_G_D_OpenAPI' - For ChatGPT Actions
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+/**
+ * OpenAPI 3.1 specification for BitsBound Contract Analysis API.
+ * Used by ChatGPT Custom GPT Actions to call the BitsBound MCP API endpoints.
+ *
+ * TIR{ADVT}O Context:
+ * - Definition: Complete API schema enabling ChatGPT to understand and call BitsBound endpoints
+ * - Validation: JSON Schema validation for all request/response bodies
+ * - Output: JSON object conforming to OpenAPI 3.1 specification
+ */
+export const OPENAPI_SPEC = {
+  openapi: '3.1.0',
+  info: {
+    title: 'BitsBound Contract Analysis API',
+    description: 'AI-powered contract analysis for legal professionals. Analyze contracts, generate redlines with real Track Changes, get clause-by-clause risk analysis, and draft negotiation emails.',
+    version: '1.0.0',
+    contact: {
+      name: 'BitsBound Support',
+      url: 'https://bitsbound.com',
+      email: 'support@bitsbound.com'
+    },
+    termsOfService: 'https://bitsbound.com/terms',
+    'x-logo': {
+      url: 'https://bitsbound.com/favicon.svg'
+    }
+  },
+  servers: [
+    {
+      url: 'https://bitsbound-saas-backend-mxb1.onrender.com',
+      description: 'Production server'
+    }
+  ],
+  security: [
+    { ApiKeyAuth: [] }
+  ],
+  paths: {
+    '/api/v1/mcp/analyze': {
+      post: {
+        operationId: 'analyzeContract',
+        summary: 'Upload and analyze a contract',
+        description: 'Upload a contract (DOCX or PDF) for comprehensive AI analysis through an 8-stage pipeline: (1) Context Loading, (2) Data Extraction with 13 scripts, (3) Party Identification, (4) Research with 8 parallel analyzers, (5) AI Analysis with 18+ parallel analyzers, (6) Instant Swarm™ parallel redlining (optional), (7) Email Generation (optional), (8) Synthesis. Returns an analysis ID to track progress.',
+        tags: ['Contract Analysis'],
+        requestBody: {
+          required: true,
+          content: {
+            'application/json': {
+              schema: {
+                type: 'object',
+                required: ['contract_content', 'filename'],
+                properties: {
+                  contract_content: {
+                    type: 'string',
+                    description: 'Base64-encoded contract file (DOCX or PDF)'
+                  },
+                  filename: {
+                    type: 'string',
+                    description: 'Original filename with extension (e.g., "msa.docx")'
+                  },
+                  analysis_type: {
+                    type: 'string',
+                    enum: ['quick', 'standard', 'full'],
+                    default: 'full',
+                    description: 'Analysis depth: quick (~5 min), standard (~15 min), full (~30 min)'
+                  }
+                }
+              }
+            }
+          }
+        },
+        responses: {
+          '200': {
+            description: 'Analysis started successfully',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    success: { type: 'boolean' },
+                    analysisId: { type: 'string', description: 'Unique identifier for tracking this analysis' },
+                    status: { type: 'string', enum: ['queued', 'processing'] },
+                    estimatedTime: { type: 'string', description: 'Estimated completion time' },
+                    message: { type: 'string' }
+                  }
+                }
+              }
+            }
+          },
+          '400': { description: 'Invalid request - missing or malformed parameters' },
+          '401': { description: 'Invalid or missing API key' }
+        }
+      }
+    },
+    '/api/v1/mcp/analysis/{analysisId}/status': {
+      get: {
+        operationId: 'getAnalysisStatus',
+        summary: 'Check analysis progress',
+        description: 'Poll this endpoint to check the status of a running analysis through the 8-stage pipeline. Returns progress percentage, current phase (Loading Context → Extracting Data → Identifying Parties → Researching → AI Analysis → Instant Swarm™ → Generating Email → Synthesizing Results), and results when complete.',
+        tags: ['Contract Analysis'],
+        parameters: [
+          {
+            name: 'analysisId',
+            in: 'path',
+            required: true,
+            schema: { type: 'string' },
+            description: 'The analysis ID returned from analyzeContract'
+          }
+        ],
+        responses: {
+          '200': {
+            description: 'Analysis status retrieved',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    success: { type: 'boolean' },
+                    analysisId: { type: 'string' },
+                    status: { type: 'string', enum: ['queued', 'processing', 'completed', 'failed'] },
+                    progress: { type: 'number', description: 'Progress percentage (0-100)' },
+                    currentPhase: { type: 'string', description: 'Current analysis phase from the 8-stage pipeline' },
+                    phases: { type: 'array', items: { type: 'string' }, description: 'Completed phases: phase1_context, phase2_extraction, phase3_parties, phase4_research, phase5_analysis, phase6_instantswarm, phase7_email, phase8_synthesis' },
+                    createdAt: { type: 'string', format: 'date-time' },
+                    completedAt: { type: 'string', format: 'date-time' }
+                  }
+                }
+              }
+            }
+          },
+          '404': { description: 'Analysis not found' }
+        }
+      }
+    },
+    '/api/v1/mcp/analysis/{analysisId}/full': {
+      get: {
+        operationId: 'getFullAnalysis',
+        summary: 'Get complete analysis results',
+        description: 'Retrieve the full analysis results including all section analyses, risks, favorability scores, and recommendations. Only available after analysis completes.',
+        tags: ['Contract Analysis'],
+        parameters: [
+          {
+            name: 'analysisId',
+            in: 'path',
+            required: true,
+            schema: { type: 'string' }
+          }
+        ],
+        responses: {
+          '200': {
+            description: 'Full analysis results',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    success: { type: 'boolean' },
+                    analysisId: { type: 'string' },
+                    status: { type: 'string' },
+                    analysis: { type: 'object', description: 'Section-by-section analysis' },
+                    risks: { type: 'array', items: { type: 'object' }, description: 'Identified risks' },
+                    favorability: { type: 'object', description: 'Favorability scores' },
+                    recommendations: { type: 'array', items: { type: 'object' } }
+                  }
+                }
+              }
+            }
+          },
+          '400': { description: 'Analysis not yet complete' },
+          '404': { description: 'Analysis not found' }
+        }
+      }
+    },
+    '/api/v1/mcp/sac/chat': {
+      post: {
+        operationId: 'askSac',
+        summary: 'Ask the Supreme AI Co-Counsel',
+        description: 'Ask questions about an analyzed contract. SAC (Supreme AI Co-Counsel) has full context of the contract and all analysis results. Great for clarifying risks, understanding clauses, or getting negotiation advice.',
+        tags: ['SAC Chat'],
+        requestBody: {
+          required: true,
+          content: {
+            'application/json': {
+              schema: {
+                type: 'object',
+                required: ['analysis_id', 'question'],
+                properties: {
+                  analysis_id: { type: 'string', description: 'Analysis ID from a completed analysis' },
+                  question: { type: 'string', description: 'Your question about the contract' },
+                  context: { type: 'string', description: 'Optional additional context for the question' }
+                }
+              }
+            }
+          }
+        },
+        responses: {
+          '200': {
+            description: 'SAC response',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    success: { type: 'boolean' },
+                    answer: { type: 'string', description: 'SAC response to your question' },
+                    citations: { type: 'array', items: { type: 'string' }, description: 'Relevant clause citations' },
+                    confidence: { type: 'number', description: 'Confidence score (0-1)' },
+                    analysisContext: { type: 'object', description: 'Summary of analysis context used' }
+                  }
+                }
+              }
+            }
+          },
+          '404': { description: 'Analysis not found' }
+        }
+      }
+    },
+    '/api/v1/mcp/redline/generate': {
+      post: {
+        operationId: 'generateRedline',
+        summary: 'Generate redlined document',
+        description: 'Generate a redlined Word document with real OOXML Track Changes (w:ins, w:del) applied directly to the original document. Returns a download URL for the redlined DOCX.',
+        tags: ['Document Generation'],
+        requestBody: {
+          required: true,
+          content: {
+            'application/json': {
+              schema: {
+                type: 'object',
+                required: ['analysis_id'],
+                properties: {
+                  analysis_id: { type: 'string' },
+                  include_comments: { type: 'boolean', default: true, description: 'Include rationale comments in margins' },
+                  format: { type: 'string', enum: ['docx', 'pdf'], default: 'docx' }
+                }
+              }
+            }
+          }
+        },
+        responses: {
+          '200': {
+            description: 'Redline generated successfully',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    success: { type: 'boolean' },
+                    analysisId: { type: 'string' },
+                    downloadUrl: { type: 'string', format: 'uri', description: 'URL to download the redlined document' },
+                    format: { type: 'string' },
+                    expiresAt: { type: 'string', format: 'date-time', description: 'URL expiration time' }
+                  }
+                }
+              }
+            }
+          },
+          '404': { description: 'Analysis not found' }
+        }
+      }
+    },
+    '/api/v1/mcp/email/generate': {
+      post: {
+        operationId: 'generateNegotiationEmail',
+        summary: 'Generate negotiation email',
+        description: 'Generate a professional negotiation email to send to the counterparty, explaining requested changes and their rationale.',
+        tags: ['Document Generation'],
+        requestBody: {
+          required: true,
+          content: {
+            'application/json': {
+              schema: {
+                type: 'object',
+                required: ['analysis_id'],
+                properties: {
+                  analysis_id: { type: 'string' },
+                  tone: { type: 'string', enum: ['professional', 'collaborative', 'firm'], default: 'professional' },
+                  recipient_name: { type: 'string', description: 'Name of the recipient' },
+                  sender_name: { type: 'string', description: 'Name of the sender' }
+                }
+              }
+            }
+          }
+        },
+        responses: {
+          '200': {
+            description: 'Email draft generated',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    success: { type: 'boolean' },
+                    analysisId: { type: 'string' },
+                    email: {
+                      type: 'object',
+                      properties: {
+                        subject: { type: 'string' },
+                        body: { type: 'string' },
+                        keyPoints: { type: 'array', items: { type: 'string' } }
+                      }
+                    },
+                    tone: { type: 'string' }
+                  }
+                }
+              }
+            }
+          },
+          '404': { description: 'Analysis not found' }
+        }
+      }
+    },
+    '/api/v1/mcp/analysis/{analysisId}/clause/{clauseType}': {
+      get: {
+        operationId: 'extractClause',
+        summary: 'Extract and analyze specific clause',
+        description: 'Extract a specific clause type from an analyzed contract. Returns the clause text, risk analysis, and suggested improvements.',
+        tags: ['Clause Extraction'],
+        parameters: [
+          {
+            name: 'analysisId',
+            in: 'path',
+            required: true,
+            schema: { type: 'string' }
+          },
+          {
+            name: 'clauseType',
+            in: 'path',
+            required: true,
+            schema: {
+              type: 'string',
+              enum: ['indemnification', 'liability', 'limitation_of_liability', 'confidentiality', 'ip', 'intellectual_property', 'termination', 'term', 'payment', 'data_protection', 'privacy', 'warranty', 'warranties', 'force_majeure', 'assignment', 'insurance', 'sla', 'dpa']
+            },
+            description: 'Type of clause to extract'
+          }
+        ],
+        responses: {
+          '200': {
+            description: 'Clause extracted successfully',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    success: { type: 'boolean' },
+                    analysisId: { type: 'string' },
+                    clauseType: { type: 'string' },
+                    clause: {
+                      type: 'object',
+                      properties: {
+                        text: { type: 'string' },
+                        analysis: { type: 'object' },
+                        favorability: { type: 'object' },
+                        risks: { type: 'array', items: { type: 'object' } },
+                        recommendations: { type: 'array', items: { type: 'string' } }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          '404': { description: 'Analysis or clause not found' }
+        }
+      }
+    },
+    '/api/v1/mcp/playbook/compare': {
+      post: {
+        operationId: 'comparePlaybook',
+        summary: 'Compare against playbook',
+        description: 'Compare an analyzed contract against a company playbook to identify deviations from pre-approved positions.',
+        tags: ['Playbook'],
+        requestBody: {
+          required: true,
+          content: {
+            'application/json': {
+              schema: {
+                type: 'object',
+                required: ['analysis_id', 'playbook_id'],
+                properties: {
+                  analysis_id: { type: 'string' },
+                  playbook_id: { type: 'string', description: 'ID of the playbook to compare against' }
+                }
+              }
+            }
+          }
+        },
+        responses: {
+          '200': {
+            description: 'Playbook comparison results',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    success: { type: 'boolean' },
+                    analysisId: { type: 'string' },
+                    playbookId: { type: 'string' },
+                    playbookName: { type: 'string' },
+                    comparison: {
+                      type: 'object',
+                      properties: {
+                        complianceScore: { type: 'number' },
+                        deviations: { type: 'array', items: { type: 'object' } },
+                        totalRulesChecked: { type: 'integer' },
+                        passedRules: { type: 'integer' },
+                        failedRules: { type: 'integer' }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          '404': { description: 'Analysis or playbook not found' }
+        }
+      }
+    },
+    '/api/v1/mcp/playbooks': {
+      get: {
+        operationId: 'listPlaybooks',
+        summary: 'List available playbooks',
+        description: 'Get a list of all playbooks available for the authenticated user.',
+        tags: ['Playbook'],
+        responses: {
+          '200': {
+            description: 'List of playbooks',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    success: { type: 'boolean' },
+                    playbooks: {
+                      type: 'array',
+                      items: {
+                        type: 'object',
+                        properties: {
+                          id: { type: 'string' },
+                          name: { type: 'string' },
+                          description: { type: 'string' },
+                          createdAt: { type: 'string', format: 'date-time' }
+                        }
+                      }
+                    },
+                    count: { type: 'integer' }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    '/api/v1/mcp/playbook/{playbookId}': {
+      get: {
+        operationId: 'getPlaybook',
+        summary: 'Get playbook details',
+        description: 'Retrieve full details of a specific playbook including all rules and sections.',
+        tags: ['Playbook'],
+        parameters: [
+          {
+            name: 'playbookId',
+            in: 'path',
+            required: true,
+            schema: { type: 'string' }
+          }
+        ],
+        responses: {
+          '200': {
+            description: 'Playbook details',
+            content: {
+              'application/json': {
+                schema: {
+                  type: 'object',
+                  properties: {
+                    success: { type: 'boolean' },
+                    playbook: {
+                      type: 'object',
+                      properties: {
+                        id: { type: 'string' },
+                        name: { type: 'string' },
+                        description: { type: 'string' },
+                        rules: { type: 'array', items: { type: 'object' } },
+                        sections: { type: 'array', items: { type: 'object' } },
+                        createdAt: { type: 'string', format: 'date-time' },
+                        updatedAt: { type: 'string', format: 'date-time' }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          '404': { description: 'Playbook not found' }
+        }
+      }
+    }
+  },
+  components: {
+    securitySchemes: {
+      ApiKeyAuth: {
+        type: 'apiKey',
+        in: 'header',
+        name: 'x-api-key',
+        description: 'BitsBound API key (format: sk_live_xxxxx). Get yours at https://account.bitsbound.com/api-keys'
+      },
+      BearerAuth: {
+        type: 'http',
+        scheme: 'bearer',
+        description: 'Alternative: Authorization: Bearer sk_live_xxxxx'
+      }
+    }
+  },
+  tags: [
+    { name: 'Contract Analysis', description: 'Upload contracts and retrieve analysis results' },
+    { name: 'SAC Chat', description: 'Interactive Q&A with Supreme AI Co-Counsel' },
+    { name: 'Document Generation', description: 'Generate redlined documents and negotiation emails' },
+    { name: 'Clause Extraction', description: 'Extract and analyze specific contract clauses' },
+    { name: 'Playbook', description: 'Company playbook management and comparison' }
+  ]
+} as const;
+
+/**
+ * Returns the OpenAPI spec as a JSON string, formatted for readability.
+ */
+export function getOpenApiSpecJson(): string {
+  return JSON.stringify(OPENAPI_SPEC, null, 2);
+}
+
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+// README Documentation 'R_DVT_G_D_README' - Comprehensive MCP Server Documentation
+// ══════════════════════════════════════════════════════════════════════════════════════════════════════════════════
+
+/**
+ * BitsBound MCP Server - Comprehensive Documentation
+ *
+ * This documentation is exported as a constant to comply with NNF (No New Files) policy.
+ * Access programmatically: `import { README_DOCUMENTATION } from './types/...Types.js'`
+ */
+export const README_DOCUMENTATION = `# BitsBound MCP Server
+
+AI-powered contract analysis for Claude, ChatGPT, and other AI platforms via the Model Context Protocol (MCP).
+
+## Overview
+
+BitsBound MCP Server enables AI assistants to analyze contracts, generate redlined documents with real Track Changes,
+and provide clause-by-clause risk analysis. It connects AI platforms to BitsBound's 8-Stage TCA Pipeline:
+
+1. **Loading Context** - Parsing deal context and contract structure
+2. **Extracting Data** - Running 13 deterministic extraction scripts
+3. **Identifying Parties** - AI identifying customer and vendor positions
+4. **Researching** - Running 8 parallel research analyzers
+5. **AI Analysis** - Running 18+ parallel AI analyzers (The Swarm)
+6. **Instant Swarm™** - Parallel redlining across all sections (optional)
+7. **Generating Email** - Drafting negotiation email with redline summary (optional)
+8. **Synthesizing Results** - Generating final recommendations and scores
+
+## Quick Start
+
+### For Claude Desktop (MCP Protocol)
+
+Add to your Claude Desktop configuration (\`~/Library/Application Support/Claude/claude_desktop_config.json\`):
+
+\`\`\`json
+{
+  "mcpServers": {
+    "bitsbound": {
+      "command": "npx",
+      "args": ["-y", "@bitsbound/mcp-server"],
+      "env": {
+        "BITSBOUND_API_KEY": "sk_live_your_api_key_here"
+      }
+    }
+  }
+}
+\`\`\`
+
+### For ChatGPT (Custom GPT Actions)
+
+1. Create a new Custom GPT at https://chat.openai.com/gpts/editor
+2. Go to "Configure" → "Create new action"
+3. Import OpenAPI schema from: \`https://bitsbound-saas-backend-mxb1.onrender.com/api/v1/mcp/openapi.json\`
+4. Set Authentication: API Key, Header name: \`x-api-key\`
+5. Enter your BitsBound API key
+
+### For Other AI Platforms (REST API)
+
+Use the REST API directly with your API key:
+
+\`\`\`bash
+curl -X POST https://bitsbound-saas-backend-mxb1.onrender.com/api/v1/mcp/analyze \\
+  -H "Content-Type: application/json" \\
+  -H "x-api-key: sk_live_your_api_key_here" \\
+  -d '{
+    "contract_content": "<base64-encoded-docx>",
+    "filename": "master-service-agreement.docx",
+    "analysis_type": "full"
+  }'
+\`\`\`
+
+## Getting Your API Key
+
+1. Sign up at https://account.bitsbound.com
+2. Subscribe to a plan (Starter: $25/mo, Professional: $125/mo, Team: $625/mo)
+3. Navigate to API Keys section
+4. Generate a new API key (format: \`sk_live_xxxxx\`)
+
+## Available Tools
+
+### process_contract
+Upload a contract (DOCX format, base64 encoded) for full 8-stage pipeline processing.
+
+**Parameters:**
+- \`docxBase64\` (required): Base64-encoded DOCX file
+- \`fileName\` (required): Original filename
+- \`analysisDepth\`: 'quick' (~5 min), 'standard' (~15 min), 'deep' (~30 min)
+- \`perspective\`: 'customer', 'vendor', or 'neutral'
+
+**Returns:** Analysis ID for tracking progress
+
+### get_analysis_status
+Check the status of a running or completed analysis.
+
+**Parameters:**
+- \`analysisId\` (required): The analysis ID from process_contract
+
+**Returns:** Progress percentage, current phase, results when complete
+
+### ask_sac
+Ask the Supreme AI Co-Counsel questions about an analyzed contract.
+
+**Parameters:**
+- \`analysisId\` (required): Analysis ID of a completed analysis
+- \`question\` (required): Your question about the contract
+- \`includeClauseCitations\`: Include specific clause citations (default: true)
+
+**Returns:** AI response with clause citations and follow-up suggestions
+
+### generate_redline
+Generate a redlined Word document with real OOXML Track Changes.
+
+**Parameters:**
+- \`analysisId\` (required): Analysis ID of a completed analysis
+- \`aggressiveness\`: 1-5 (1=conservative, 5=aggressive)
+- \`includeComments\`: Include rationale comments (default: true)
+
+**Returns:** Base64-encoded redlined DOCX with download URL
+
+### generate_negotiation_email
+Generate a professional negotiation email to send to counterparty.
+
+**Parameters:**
+- \`analysisId\` (required): Analysis ID of a completed analysis
+- \`tone\`: 'collaborative', 'firm', or 'aggressive'
+- \`recipientRole\`: Role of the recipient (e.g., "General Counsel")
+
+**Returns:** Subject line, email body, and key points
+
+### extract_clause
+Extract and analyze a specific clause type from an analyzed contract.
+
+**Parameters:**
+- \`analysisId\` (required): Analysis ID of a completed analysis
+- \`clauseType\` (required): One of: 'indemnification', 'liability', 'ip', 'termination',
+  'payment', 'confidentiality', 'data_privacy', 'sla', 'force_majeure', 'assignment'
+
+**Returns:** Clause text, risk level, analysis, suggested improvements
+
+### compare_playbook
+Compare an analyzed contract against a company playbook.
+
+**Parameters:**
+- \`analysisId\` (required): Analysis ID of a completed analysis
+- \`playbookId\` (required): ID of the playbook to compare against
+
+**Returns:** Deviations, compliance score, required approvals
+
+## Example Workflow
+
+\`\`\`
+User: "Analyze this Master Service Agreement and tell me the key risks"
+
+Claude/ChatGPT:
+1. Calls process_contract with the uploaded DOCX (with Instant Swarm + Email enabled)
+2. Polls get_analysis_status to watch progress through 8 stages:
+   - Loading Context → Extracting Data → Identifying Parties → Researching
+   - AI Analysis → Instant Swarm™ → Generating Email → Synthesizing Results
+3. Reads results showing favorability score (e.g., 42% - Vendor Favorable)
+4. Identifies top risks: unlimited liability, broad IP assignment, weak SLA
+5. User can ask follow-up questions via ask_sac (SAC has full contract context)
+6. Downloads the redlined DOCX with real Track Changes (from Instant Swarm™)
+7. Reviews the auto-generated negotiation email (from Email Generator)
+\`\`\`
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| BITSBOUND_API_KEY | Yes | Your API key (sk_live_xxxxx) |
+| BITSBOUND_API_URL | No | API URL (default: production server) |
+
+## API Endpoints (REST)
+
+All endpoints require \`x-api-key\` header or \`Authorization: Bearer <key>\` header.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | /api/v1/mcp/analyze | Start contract analysis |
+| GET | /api/v1/mcp/analysis/:id/status | Get analysis status |
+| GET | /api/v1/mcp/analysis/:id/full | Get full analysis results |
+| POST | /api/v1/mcp/sac/chat | Ask SAC questions |
+| POST | /api/v1/mcp/redline/generate | Generate redlined DOCX |
+| POST | /api/v1/mcp/email/generate | Generate negotiation email |
+| GET | /api/v1/mcp/analysis/:id/clause/:type | Extract specific clause |
+| POST | /api/v1/mcp/playbook/compare | Compare against playbook |
+| GET | /api/v1/mcp/playbook/:id | Get playbook details |
+| GET | /api/v1/mcp/playbooks | List available playbooks |
+| GET | /api/v1/mcp/openapi.json | OpenAPI specification (public) |
+
+## Pricing
+
+BitsBound uses token-based pricing. Analysis costs vary by depth:
+- Quick analysis: ~100K tokens (~$2.50)
+- Standard analysis: ~500K tokens (~$12.50)
+- Deep analysis: ~1M tokens (~$25.00)
+
+Subscription tiers include monthly token allocations:
+- Starter ($25/mo): 1M tokens
+- Professional ($125/mo): 5M tokens
+- Team ($625/mo): 25M tokens
+- Enterprise ($3,750/mo): 150M tokens
+
+## Legal Disclaimer
+
+BitsBound provides AI-assisted contract analysis tools for legal professionals. All outputs are
+preliminary drafts requiring attorney review and do not constitute legal advice. BitsBound is
+not a law firm and does not provide legal advice.
+
+## Support
+
+- Website: https://bitsbound.com
+- Documentation: https://bitsbound.com/docs
+- API Keys: https://account.bitsbound.com/api-keys
+- Support: support@bitsbound.com
+
+## License
+
+MIT License - see package.json for details.
+
+---
+
+Built by Rob Taylor, Esq. - Corporate attorney and full-stack AI engineer.
+` as const;
+
+/**
+ * Returns the README documentation for display or export.
+ */
+export function getReadmeDocumentation(): string {
+  return README_DOCUMENTATION;
+}
+
+
+/*
+######################################################################################################################################################################################################
+*/
+// ####                                                                                                         LOCAL 'R_DVT_L', i.e. FUNCTION/PROVISION LEVEL DVTs
+/*
+######################################################################################################################################################################################################
+*/
+
+// No local types needed - all types are global for MCP protocol