differino-mcp 0.1.0 → 0.4.0

package/src/index.ts

@@ -6,7 +6,6 @@ import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
-import { createClient, SupabaseClient } from '@supabase/supabase-js';
 import * as fs from 'fs';
 import * as path from 'path';
 
@@ -14,107 +13,52 @@ import * as path from 'path';
 // Configuration
 // ---------------------------------------------------------------------------
 
-const SUPABASE_URL =
-  process.env.SUPABASE_URL ||
-  process.env.DIFFERINO_SUPABASE_URL ||
-  '';
-const SUPABASE_ANON_KEY =
-  process.env.SUPABASE_ANON_KEY ||
-  process.env.DIFFERINO_SUPABASE_ANON_KEY ||
-  '';
-const BASE_URL = process.env.DIFFERINO_URL || 'https://differino.com';
-const EMAIL = process.env.DIFFERINO_EMAIL || '';
-const PASSWORD = process.env.DIFFERINO_PASSWORD || '';
-
-let accessToken: string | null = null;
-let refreshToken: string | null = null;
-let supabase: SupabaseClient | null = null;
+const API_KEY = process.env.DIFFERINO_API_KEY || '';
+const BASE_URL = process.env.DIFFERINO_URL || 'https://www.differino.com';
+
+const REQUEST_TIMEOUT_MS = 300_000; // 5 minutes: compare can wait on extraction + diff
+const EXPORT_POLL_INTERVAL_MS = 2_000;
+const EXPORT_POLL_TIMEOUT_MS = 180_000; // 3 minutes
 
 // ---------------------------------------------------------------------------
-// Auth helpers
+// HTTP helpers
 // ---------------------------------------------------------------------------
 
-async function authenticate(): Promise<void> {
-  supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY);
-  const { data, error } = await supabase.auth.signInWithPassword({
-    email: EMAIL,
-    password: PASSWORD,
-  });
-  if (error) throw new Error(`Authentication failed: ${error.message}`);
-  accessToken = data.session.access_token;
-  refreshToken = data.session.refresh_token;
-}
-
-async function ensureAuth(): Promise<SupabaseClient> {
-  if (!supabase || !accessToken) {
-    await authenticate();
-  }
-  return supabase!;
-}
-
-/**
- * Build the cookie header that the Next.js Supabase SSR client expects.
- *
- * @supabase/ssr stores the session in a cookie whose name follows the pattern
- * `sb-<project-ref>-auth-token`. The value is a base64url-encoded JSON string
- * containing `access_token`, `refresh_token`, etc.
- *
- * For large tokens the library may chunk the cookie across multiple numbered
- * cookies (sb-<ref>-auth-token.0, .1, ...). We produce a single cookie here
- * which works for typical token sizes.
- */
-function buildAuthCookie(): string {
-  const projectRef = SUPABASE_URL.match(/https:\/\/([^.]+)\./)?.[1] || 'ref';
-  const cookieName = `sb-${projectRef}-auth-token`;
-  const cookieValue = JSON.stringify({
-    access_token: accessToken,
-    refresh_token: refreshToken,
-    token_type: 'bearer',
-  });
-
-  // The SSR helper may also check chunked variants (.0, .1, …).
-  // Providing a single non-chunked cookie is accepted when the value fits in
-  // one cookie (< 3180 bytes). For very long JWTs we split into chunks.
-  const encoded = cookieValue;
-  const CHUNK_SIZE = 3180;
-
-  if (encoded.length <= CHUNK_SIZE) {
-    return `${cookieName}=${encodeURIComponent(encoded)}`;
-  }
-
-  // Chunked cookies
-  const chunks: string[] = [];
-  for (let i = 0; i * CHUNK_SIZE < encoded.length; i++) {
-    const slice = encoded.substring(i * CHUNK_SIZE, (i + 1) * CHUNK_SIZE);
-    chunks.push(`${cookieName}.${i}=${encodeURIComponent(slice)}`);
-  }
-  return chunks.join('; ');
+function isTimeoutError(err: unknown): boolean {
+  return (
+    err instanceof Error &&
+    (err.name === 'TimeoutError' ||
+      err.name === 'AbortError' ||
+      (err.cause instanceof Error &&
+        (err.cause.name === 'TimeoutError' || err.cause.name === 'AbortError')))
+  );
 }
 
-// ---------------------------------------------------------------------------
-// HTTP helpers (calls to the Differino Next.js API)
-// ---------------------------------------------------------------------------
-
 async function apiCall(
   endpoint: string,
   options: RequestInit = {},
 ): Promise<any> {
   const url = `${BASE_URL}${endpoint}`;
   const headers: Record<string, string> = {
+    Authorization: `Bearer ${API_KEY}`,
     ...(options.headers as Record<string, string> || {}),
   };
 
-  if (accessToken) {
-    headers['Cookie'] = buildAuthCookie();
-  }
-
-  const res = await fetch(url, { ...options, headers, redirect: 'manual' });
-
-  // Handle redirects (auth middleware may redirect to /login)
-  if (res.status >= 300 && res.status < 400) {
-    throw new Error(
-      `API redirected (${res.status}) — session may have expired. Location: ${res.headers.get('location')}`,
-    );
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      ...options,
+      headers,
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+  } catch (err) {
+    if (isTimeoutError(err)) {
+      throw new Error(
+        `Request to ${endpoint} timed out after ${REQUEST_TIMEOUT_MS / 1000}s. ` +
+          'The operation may still be running on the server; use get_comparison or list_comparisons to check its status.',
+      );
+    }
+    throw err;
   }
 
   const text = await res.text();
@@ -122,16 +66,22 @@ async function apiCall(
   try {
     json = JSON.parse(text);
   } catch {
-    throw new Error(`Non-JSON response from ${endpoint}: ${text.slice(0, 200)}`);
+    throw new Error(`Non-JSON response from ${endpoint} (HTTP ${res.status}): ${text.slice(0, 200)}`);
   }
 
   if (!res.ok) {
-    throw new Error(json.error || `API error ${res.status}: ${text.slice(0, 300)}`);
+    const message = json.error || `API error ${res.status}: ${text.slice(0, 300)}`;
+    // Surface machine-readable error codes (e.g. NO_CREDITS) to the agent.
+    throw new Error(json.code ? `[${json.code}] ${message}` : message);
   }
 
   return json;
 }
 
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 // ---------------------------------------------------------------------------
 // File utilities
 // ---------------------------------------------------------------------------
@@ -162,16 +112,14 @@ function getMimeType(ext: string): string {
 async function compareDocuments(args: {
   file_a_path: string;
   file_b_path: string;
-  accuracy_mode?: string;
+  comparison_mode?: 'visual' | 'text';
 }): Promise<string> {
-  await ensureAuth();
-
-  const { file_a_path, file_b_path, accuracy_mode = 'balanced' } = args;
+  const { file_a_path, file_b_path, comparison_mode = 'visual' } = args;
 
-  // --- Validate files ---
+  // Validate files exist
   for (const fp of [file_a_path, file_b_path]) {
     if (!fs.existsSync(fp)) {
-      return `Error: File not found: ${fp}`;
+      throw new Error(`File not found: ${fp}`);
     }
   }
 
@@ -181,327 +129,325 @@ async function compareDocuments(args: {
   const extB = getExtension(nameB);
 
   if (!SUPPORTED_EXTENSIONS.has(extA)) {
-    return `Error: Unsupported file type for ${nameA}. Supported: PDF, DOCX, TXT.`;
+    throw new Error(`Unsupported file type for ${nameA}. Supported: PDF, DOCX, TXT.`);
   }
   if (!SUPPORTED_EXTENSIONS.has(extB)) {
-    return `Error: Unsupported file type for ${nameB}. Supported: PDF, DOCX, TXT.`;
+    throw new Error(`Unsupported file type for ${nameB}. Supported: PDF, DOCX, TXT.`);
   }
 
-  // --- Upload file A ---
+  // Build multipart form
+  const form = new FormData();
   const fileABuffer = fs.readFileSync(file_a_path);
-  const fileASize = fileABuffer.byteLength;
-
-  // Use init/complete flow for files > 4MB, direct upload for smaller ones
-  let uploadA: { versionId: string; documentId: string };
-  let uploadB: { versionId: string; documentId: string };
-
-  if (fileASize < 4 * 1024 * 1024) {
-    // Direct upload via /api/upload
-    const formA = new FormData();
-    formA.append('file', new Blob([fileABuffer], { type: getMimeType(extA) }), nameA);
-    formA.append('name', nameA);
+  const fileBBuffer = fs.readFileSync(file_b_path);
 
-    uploadA = await apiCall('/api/upload', {
-      method: 'POST',
-      body: formA,
-    });
-  } else {
-    uploadA = await uploadLargeFile(file_a_path, nameA, fileABuffer, extA);
-  }
+  form.append(
+    'file_a',
+    new Blob([fileABuffer], { type: getMimeType(extA) }),
+    nameA,
+  );
+  form.append(
+    'file_b',
+    new Blob([fileBBuffer], { type: getMimeType(extB) }),
+    nameB,
+  );
+  form.append('comparison_mode', comparison_mode);
 
-  // --- Upload file B ---
-  const fileBBuffer = fs.readFileSync(file_b_path);
-  const fileBSize = fileBBuffer.byteLength;
+  // Call the REST API. It handles upload, extraction, comparison, and polling.
+  const result = await apiCall('/api/v1/compare', {
+    method: 'POST',
+    body: form,
+  });
 
-  if (fileBSize < 4 * 1024 * 1024) {
-    const formB = new FormData();
-    formB.append('file', new Blob([fileBBuffer], { type: getMimeType(extB) }), nameB);
-    formB.append('name', nameB);
+  return JSON.stringify(result, null, 2);
+}
 
-    uploadB = await apiCall('/api/upload', {
-      method: 'POST',
-      body: formB,
-    });
-  } else {
-    uploadB = await uploadLargeFile(file_b_path, nameB, fileBBuffer, extB);
-  }
+async function getComparison(args: { comparison_id: string }): Promise<string> {
+  const result = await apiCall(`/api/v1/comparisons/${args.comparison_id}`);
+  return JSON.stringify(result, null, 2);
+}
 
-  // --- Wait for text extraction ---
-  const MAX_WAIT_MS = 120_000;
-  const POLL_MS = 2_000;
-
-  for (const vId of [uploadA.versionId, uploadB.versionId]) {
-    const deadline = Date.now() + MAX_WAIT_MS;
-    while (Date.now() < deadline) {
-      const { data } = await supabase!
-        .from('versions')
-        .select('status')
-        .eq('id', vId)
-        .single();
-
-      if (data?.status === 'ready') break;
-      if (data?.status === 'failed') {
-        return `Error: Text extraction failed for version ${vId}.`;
-      }
+async function listComparisons(args: {
+  limit?: number;
+  status?: string;
+}): Promise<string> {
+  const params = new URLSearchParams();
+  if (args.limit !== undefined) params.set('limit', String(args.limit));
+  if (args.status) params.set('status', args.status);
+  const qs = params.toString();
 
-      await sleep(POLL_MS);
-    }
-  }
+  const result = await apiCall(`/api/v1/comparisons${qs ? `?${qs}` : ''}`);
+  return JSON.stringify(result, null, 2);
+}
 
-  // --- Create comparison ---
-  const comparison = await apiCall('/api/comparisons', {
+async function exportComparisonPdf(args: {
+  comparison_id: string;
+  include_unchanged?: boolean;
+  locale?: string;
+  wait?: boolean;
+}): Promise<string> {
+  const {
+    comparison_id,
+    include_unchanged = false,
+    locale = 'en',
+    wait = true,
+  } = args;
+
+  const created = await apiCall(`/api/v1/comparisons/${comparison_id}/export`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({
-      versionAId: uploadA.versionId,
-      versionBId: uploadB.versionId,
-      accuracyMode: accuracy_mode,
+      format: 'pdf',
+      includeUnchanged: include_unchanged,
+      locale,
     }),
   });
 
-  // --- Poll for comparison result ---
-  const compDeadline = Date.now() + MAX_WAIT_MS;
-  while (Date.now() < compDeadline) {
-    const { data } = await supabase!
-      .from('comparisons')
-      .select('status, summary, error_message')
-      .eq('id', comparison.id)
-      .single();
-
-    if (data?.status === 'ready') {
-      const summary = data.summary as Record<string, number> | null;
+  const jobId: string = created.jobId;
+  const statusEndpoint = `/api/v1/comparisons/${comparison_id}/export?jobId=${encodeURIComponent(jobId)}`;
+
+  if (!wait) {
+    return JSON.stringify(
+      {
+        jobId,
+        status: created.status ?? 'processing',
+        message:
+          'Export queued. Call export_comparison_pdf again with wait=true, or poll ' +
+          `GET ${statusEndpoint} to get the downloadUrl.`,
+      },
+      null,
+      2,
+    );
+  }
+
+  const deadline = Date.now() + EXPORT_POLL_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    await sleep(EXPORT_POLL_INTERVAL_MS);
+    const statusRes = await apiCall(statusEndpoint);
+
+    if (statusRes.status === 'completed') {
       return JSON.stringify(
         {
-          status: 'ready',
-          comparison_id: comparison.id,
-          url: `${BASE_URL}/compare?id=${comparison.id}`,
-          summary: {
-            added_blocks: summary?.added_blocks ?? 0,
-            removed_blocks: summary?.removed_blocks ?? 0,
-            modified_blocks: summary?.modified_blocks ?? 0,
-            unchanged_blocks: summary?.unchanged_blocks ?? 0,
-          },
+          jobId,
+          status: 'completed',
+          downloadUrl: statusRes.downloadUrl,
+          note: 'The download URL is signed and expires in about 5 minutes.',
         },
         null,
         2,
       );
     }
-
-    if (data?.status === 'failed') {
-      return `Error: Comparison failed — ${data.error_message || 'unknown error'}`;
+    if (statusRes.status === 'failed') {
+      throw new Error(`Export failed: ${statusRes.error || 'unknown error'}`);
     }
-
-    await sleep(POLL_MS);
   }
 
   return JSON.stringify(
     {
+      jobId,
       status: 'processing',
-      comparison_id: comparison.id,
-      url: `${BASE_URL}/compare?id=${comparison.id}`,
-      message: 'Comparison is still processing. Check the URL for results.',
+      message:
+        `Export still processing after ${EXPORT_POLL_TIMEOUT_MS / 1000}s. ` +
+        `Poll GET ${statusEndpoint} for the downloadUrl.`,
     },
     null,
     2,
   );
 }
 
-/**
- * Upload a large file (>4 MB) via the init + signed-URL + complete flow,
- * which bypasses Vercel's 4.5 MB request body limit.
- */
-async function uploadLargeFile(
-  filePath: string,
-  filename: string,
-  buffer: Buffer,
-  ext: string,
-): Promise<{ versionId: string; documentId: string }> {
-  const mime = getMimeType(ext);
-
-  // 1. Init — creates version record and returns a signed upload URL
-  const init = await apiCall('/api/upload/init', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      filename,
-      contentType: mime,
-      fileSize: buffer.byteLength,
-      documentName: filename,
-    }),
-  });
+// Prominence order used by min_salience filtering, lowest to highest.
+const SALIENCE_RANK: Record<string, number> = {
+  technical: 0,
+  subtle: 1,
+  visible: 2,
+  structural: 3,
+};
+
+async function summarizeVisualDiff(args: {
+  comparison_id: string;
+  min_salience?: string;
+  include_snippets?: boolean;
+  max_changes_per_page?: number;
+}): Promise<string> {
+  const {
+    comparison_id,
+    min_salience,
+    include_snippets = true,
+    max_changes_per_page = 20,
+  } = args;
+
+  const comparison = await apiCall(`/api/v1/comparisons/${comparison_id}`);
+  const visual = comparison.visual ?? {};
+  const manifest = visual.manifest;
+
+  if (visual.status !== 'ready' || !manifest) {
+    const hint =
+      comparison.status !== 'ready'
+        ? 'The comparison is still processing; retry once get_comparison reports status=ready.'
+        : 'This comparison has no visual manifest (it may be a text-mode comparison). Use get_text_diff instead.';
+    throw new Error(
+      `Visual diff not available (comparison status=${comparison.status}, visual.status=${visual.status ?? 'unknown'}). ${hint}`,
+    );
+  }
 
-  // 2. Upload directly to Supabase Storage via the signed URL
-  const uploadRes = await fetch(init.signedUrl, {
-    method: 'PUT',
-    headers: { 'Content-Type': mime },
-    body: new Uint8Array(buffer),
-  });
+  const minRank = min_salience ? SALIENCE_RANK[min_salience] ?? 0 : 0;
+  const seenGroups = new Set<string>();
+  const pages: Array<Record<string, unknown>> = [];
+  let listedChanges = 0;
+  let filteredBySalience = 0;
+
+  for (const page of manifest.pages ?? []) {
+    const regions: any[] = page.regions ?? [];
+    const changes: Array<Record<string, unknown>> = [];
+    let omittedChanges = 0;
+
+    for (const region of regions) {
+      const groupKey: string = region.groupId ?? region.id;
+      // Fragments of the same change (e.g. across page boundaries) share a
+      // groupId; report each change once.
+      if (seenGroups.has(groupKey)) continue;
+      seenGroups.add(groupKey);
+
+      const salience: string = region.salience ?? 'visible';
+      if ((SALIENCE_RANK[salience] ?? SALIENCE_RANK.visible) < minRank) {
+        filteredBySalience += 1;
+        continue;
+      }
 
-  if (!uploadRes.ok) {
-    const text = await uploadRes.text();
-    throw new Error(`Storage upload failed (${uploadRes.status}): ${text.slice(0, 200)}`);
-  }
+      if (changes.length >= max_changes_per_page) {
+        omittedChanges += 1;
+        continue;
+      }
 
-  // 3. Complete — enqueues extraction job
-  const complete = await apiCall('/api/upload/complete', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ versionId: init.versionId }),
-  });
+      changes.push({
+        groupId: groupKey,
+        type: region.type ?? 'changed',
+        title: region.title ?? null,
+        ...(region.description ? { description: region.description } : {}),
+        salience: region.salience ?? null,
+        ...(region.salienceReason ? { salienceReason: region.salienceReason } : {}),
+        ...(include_snippets
+          ? {
+              snippetA: region.snippetA ?? null,
+              snippetB: region.snippetB ?? null,
+            }
+          : {}),
+      });
+      listedChanges += 1;
+    }
 
-  return {
-    versionId: init.versionId,
-    documentId: init.documentId,
-  };
-}
+    if (changes.length > 0 || omittedChanges > 0) {
+      pages.push({
+        pageNumber: page.pageNumber,
+        changes,
+        ...(omittedChanges > 0
+          ? {
+              omittedChanges,
+              note: `Increase max_changes_per_page to see the ${omittedChanges} omitted change(s) on this page.`,
+            }
+          : {}),
+      });
+    }
+  }
 
-async function getComparison(args: { comparison_id: string }): Promise<string> {
-  await ensureAuth();
-
-  const { data, error } = await supabase!
-    .from('comparisons')
-    .select(
-      `
-      id, status, summary, error_message, created_at, completed_at,
-      version_a:versions!version_a_id ( id, document_id, documents ( name ) ),
-      version_b:versions!version_b_id ( id, document_id, documents ( name ) )
-    `,
-    )
-    .eq('id', args.comparison_id)
-    .single();
-
-  if (error || !data) return 'Error: Comparison not found.';
-
-  const rec = data as any;
   return JSON.stringify(
     {
-      comparison_id: rec.id,
-      status: rec.status,
-      url: `${BASE_URL}/compare?id=${rec.id}`,
-      file_a: rec.version_a?.documents?.name ?? 'Unknown',
-      file_b: rec.version_b?.documents?.name ?? 'Unknown',
-      summary: rec.summary ?? null,
-      error: rec.error_message ?? null,
-      created_at: rec.created_at,
-      completed_at: rec.completed_at,
+      comparisonId: comparison.id ?? comparison_id,
+      status: comparison.status,
+      totalChanges: manifest.totalChanges ?? null,
+      changedPageCount: manifest.changedPageCount ?? null,
+      listedChanges,
+      ...(min_salience ? { minSalience: min_salience, filteredBySalience } : {}),
+      pages,
     },
     null,
     2,
   );
 }
 
-async function listComparisons(args: { limit?: number }): Promise<string> {
-  await ensureAuth();
-
-  const limit = args.limit || 10;
-
-  const { data: workspace } = await supabase!
-    .from('workspaces')
-    .select('id')
-    .single();
-
-  if (!workspace) return 'Error: No workspace found.';
-
-  const { data, error } = await supabase!
-    .from('comparisons')
-    .select(
-      `
-      id, status, created_at,
-      version_a:versions!version_a_id ( documents ( name ) ),
-      version_b:versions!version_b_id ( documents ( name ) )
-    `,
-    )
-    .eq('workspace_id', workspace.id)
-    .order('created_at', { ascending: false })
-    .limit(limit);
-
-  if (error) return `Error: ${error.message}`;
-
-  const comparisons = (data || []).map((c: any) => ({
-    id: c.id,
-    status: c.status,
-    file_a: c.version_a?.documents?.name ?? 'Unknown',
-    file_b: c.version_b?.documents?.name ?? 'Unknown',
-    created_at: c.created_at,
-    url: `${BASE_URL}/compare?id=${c.id}`,
-  }));
-
-  return JSON.stringify(comparisons, null, 2);
-}
-
-async function listDocuments(args: { limit?: number }): Promise<string> {
-  await ensureAuth();
-
-  const { data: workspace } = await supabase!
-    .from('workspaces')
-    .select('id')
-    .single();
-
-  if (!workspace) return 'Error: No workspace found.';
-
-  const { data, error } = await supabase!
-    .from('documents')
-    .select(
-      `
-      id, name, updated_at,
-      versions ( id, version_number, status, created_at )
-    `,
-    )
-    .eq('workspace_id', workspace.id)
-    .order('updated_at', { ascending: false })
-    .limit(args.limit || 20);
-
-  if (error) return `Error: ${error.message}`;
-
-  return JSON.stringify(data, null, 2);
-}
+async function getTextDiff(args: {
+  comparison_id: string;
+  only_changed?: boolean;
+  max_blocks?: number;
+}): Promise<string> {
+  const { comparison_id, only_changed = true, max_blocks = 100 } = args;
 
-async function getCredits(): Promise<string> {
-  await ensureAuth();
+  const comparison = await apiCall(`/api/v1/comparisons/${comparison_id}`);
 
-  const { data: workspace } = await supabase!
-    .from('workspaces')
-    .select('credits, plan, pro_expires_at')
-    .single();
+  if (comparison.status !== 'ready') {
+    throw new Error(
+      `Comparison is not ready yet (status=${comparison.status}). Retry once get_comparison reports status=ready.`,
+    );
+  }
+  if (!comparison.diffUrl) {
+    throw new Error('No text diff is available for this comparison.');
+  }
 
-  if (!workspace) return 'Error: No workspace found.';
+  // diffUrl is a signed URL; no auth header needed.
+  let res: Response;
+  try {
+    res = await fetch(comparison.diffUrl, {
+      signal: AbortSignal.timeout(60_000),
+    });
+  } catch (err) {
+    if (isTimeoutError(err)) {
+      throw new Error('Timed out downloading the diff data after 60s. Try again.');
+    }
+    throw err;
+  }
+  if (!res.ok) {
+    throw new Error(`Failed to download diff data (HTTP ${res.status}).`);
+  }
 
-  const now = new Date();
-  const monthKey = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-01`;
+  const diff = (await res.json()) as {
+    summary?: Record<string, unknown>;
+    blocks?: Array<{
+      type: string;
+      content_a?: string;
+      content_b?: string;
+      spans?: Array<{ type: string; text: string }>;
+    }>;
+  };
 
-  const { data: usage } = await supabase!
-    .from('usage')
-    .select('comparison_count')
-    .eq('month', monthKey)
-    .single();
+  const blocks = Array.isArray(diff.blocks) ? diff.blocks : [];
+  const matching = only_changed
+    ? blocks.filter((block) => block.type !== 'equal')
+    : blocks;
+  const truncated = matching.length > max_blocks;
+
+  const outputBlocks = matching.slice(0, max_blocks).map((block) => ({
+    type: block.type,
+    ...(block.content_a !== undefined ? { content_a: block.content_a } : {}),
+    ...(block.content_b !== undefined ? { content_b: block.content_b } : {}),
+    // Word-level spans are only informative for modified blocks.
+    ...(block.type === 'modified' && Array.isArray(block.spans) && block.spans.length > 0
+      ? { spans: block.spans }
+      : {}),
+  }));
 
   return JSON.stringify(
     {
-      credits: (workspace as any).credits,
-      plan: (workspace as any).plan,
-      pro_expires_at: (workspace as any).pro_expires_at,
-      free_comparisons_used: (usage as any)?.comparison_count ?? 0,
-      free_comparisons_limit: 3,
+      comparisonId: comparison.id ?? comparison_id,
+      summary: diff.summary ?? null,
+      only_changed,
+      returned_blocks: outputBlocks.length,
+      total_matching_blocks: matching.length,
+      truncated,
+      ...(truncated
+        ? { note: `Output truncated to max_blocks=${max_blocks}. Increase max_blocks to see more.` }
+        : {}),
+      blocks: outputBlocks,
     },
     null,
     2,
   );
 }
 
-// ---------------------------------------------------------------------------
-// Utility
-// ---------------------------------------------------------------------------
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
 // ---------------------------------------------------------------------------
 // MCP Server
 // ---------------------------------------------------------------------------
 
 const server = new Server(
-  { name: 'differino', version: '0.1.0' },
+  { name: 'differino', version: '0.4.0' },
   { capabilities: { tools: {} } },
 );
 
@@ -511,7 +457,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       name: 'compare_documents',
       description:
         'Compare two documents (PDF, DOCX, or TXT) and see the differences. ' +
-        'Reads files from local disk, uploads them to Differino, and returns a diff summary.',
+        'Reads files from local disk, uploads them to Differino, and returns a text diff summary. Use comparison_mode="visual" for the full document-review manifest with page images, red/green change regions, stable groupId values, and salience metadata; use comparison_mode="text" for faster text-only comparison. ' +
+        'If the response has status="processing", the comparison is still running: poll get_comparison with the returned id until status="ready". Consumes the free comparison or 1 credit.',
       inputSchema: {
         type: 'object' as const,
         properties: {
@@ -523,10 +470,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             type: 'string',
             description: 'Absolute path to the modified document',
           },
-          accuracy_mode: {
+          comparison_mode: {
             type: 'string',
-            enum: ['fast', 'balanced', 'thorough'],
-            description: 'Comparison accuracy mode (default: balanced)',
+            enum: ['visual', 'text'],
+            description: 'visual for full document review, or text for fast text-only comparison',
+            default: 'visual',
           },
         },
         required: ['file_a_path', 'file_b_path'],
@@ -534,7 +482,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'get_comparison',
-      description: 'Get the status and results of a specific comparison by its ID.',
+      description:
+        'Get the status and results of a specific comparison by its ID, including visual.status and the visual.manifest document-review contract with grouped change identities and salience metadata when visual artifacts are available. ' +
+        'Use it to poll a comparison that is still processing, or to re-fetch results (including fresh signed URLs) for an existing comparison. Does not consume credits.',
       inputSchema: {
         type: 'object' as const,
         properties: {
@@ -548,37 +498,114 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: 'list_comparisons',
-      description: 'List recent document comparisons in the user\'s workspace.',
+      description:
+        'List recent comparisons in the workspace, newest first. Returns for each comparison: id, status, comparisonMode, file_a/file_b name and type, summary counters, created_at, and completed_at. ' +
+        'Use it to find a comparison id when you do not have one, to check recent activity, or to locate unfinished comparisons (status filter). Does not consume credits.',
       inputSchema: {
         type: 'object' as const,
         properties: {
           limit: {
             type: 'number',
-            description: 'Maximum number of comparisons to return (default: 10)',
+            description: 'Maximum number of comparisons to return (1-50)',
+            default: 10,
+          },
+          status: {
+            type: 'string',
+            enum: ['pending', 'processing', 'ready', 'failed'],
+            description: 'Only return comparisons with this status',
           },
         },
+        required: [],
       },
     },
     {
-      name: 'list_documents',
-      description: 'List documents in the user\'s Differino library.',
+      name: 'export_comparison_pdf',
+      description:
+        'Export a finished comparison as a PDF report and return a temporary download URL (valid for about 5 minutes). ' +
+        'With wait=true (default) it polls the export job every 2 seconds for up to 3 minutes and returns { jobId, status: "completed", downloadUrl }. With wait=false it returns { jobId, status } immediately; call again later or poll the REST endpoint to fetch the URL. ' +
+        'The comparison must have status="ready". Free workspaces get a watermarked PDF; workspaces with credits export without watermark. Does not consume credits.',
       inputSchema: {
         type: 'object' as const,
         properties: {
-          limit: {
+          comparison_id: {
+            type: 'string',
+            description: 'The comparison UUID',
+          },
+          include_unchanged: {
+            type: 'boolean',
+            description: 'Include unchanged content in the PDF report, not only the changes',
+            default: false,
+          },
+          locale: {
+            type: 'string',
+            enum: ['en', 'es', 'zh', 'fr', 'de', 'hi'],
+            description: 'Language for the report labels',
+            default: 'en',
+          },
+          wait: {
+            type: 'boolean',
+            description: 'Poll until the export completes (up to 3 minutes) and return the downloadUrl',
+            default: true,
+          },
+        },
+        required: ['comparison_id'],
+      },
+    },
+    {
+      name: 'summarize_visual_diff',
+      description:
+        'Compact page-by-page summary of the visual diff of a finished visual comparison: one entry per change group (fragments sharing a groupId are deduplicated), with type, title, salience, and optional text snippets. No image URLs and no pixel coordinates, so it is the cheapest way for an agent to reason about what changed and where. ' +
+        'Use min_salience to hide low-prominence changes; prominence order is technical < subtle < visible < structural. Requires visual.status="ready"; for text-mode comparisons use get_text_diff instead. Does not consume credits.',
+      inputSchema: {
+        type: 'object' as const,
+        properties: {
+          comparison_id: {
+            type: 'string',
+            description: 'The comparison UUID',
+          },
+          min_salience: {
+            type: 'string',
+            enum: ['technical', 'subtle', 'visible', 'structural'],
+            description: 'Only include changes at or above this prominence level',
+          },
+          include_snippets: {
+            type: 'boolean',
+            description: 'Include snippetA/snippetB text excerpts for each change',
+            default: true,
+          },
+          max_changes_per_page: {
             type: 'number',
-            description: 'Maximum number of documents to return (default: 20)',
+            description: 'Maximum changes listed per page; extra changes are counted as omitted',
+            default: 20,
           },
         },
+        required: ['comparison_id'],
       },
     },
     {
-      name: 'get_credits',
+      name: 'get_text_diff',
       description:
-        'Check the user\'s credit balance, plan status, and free comparison usage for the current month.',
+        'Fetch the block-level text diff of a finished comparison. Returns summary counters plus diff blocks with their content: added and removed blocks carry the affected text, modified blocks also carry word-level spans marking exactly which words changed. ' +
+        'By default only changed blocks are returned (only_changed=true); set only_changed=false to include equal blocks for full context. Best when you need to quote exact text changes. Works for both text and visual comparisons. Does not consume credits.',
       inputSchema: {
         type: 'object' as const,
-        properties: {},
+        properties: {
+          comparison_id: {
+            type: 'string',
+            description: 'The comparison UUID',
+          },
+          only_changed: {
+            type: 'boolean',
+            description: 'Return only added/removed/modified blocks, skipping equal ones',
+            default: true,
+          },
+          max_blocks: {
+            type: 'number',
+            description: 'Maximum number of blocks to return',
+            default: 100,
+          },
+        },
+        required: ['comparison_id'],
       },
     },
   ],
@@ -600,14 +627,17 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'list_comparisons':
         result = await listComparisons(args as any);
         break;
-      case 'list_documents':
-        result = await listDocuments(args as any);
+      case 'export_comparison_pdf':
+        result = await exportComparisonPdf(args as any);
+        break;
+      case 'summarize_visual_diff':
+        result = await summarizeVisualDiff(args as any);
         break;
-      case 'get_credits':
-        result = await getCredits();
+      case 'get_text_diff':
+        result = await getTextDiff(args as any);
         break;
       default:
-        result = `Unknown tool: ${name}`;
+        throw new Error(`Unknown tool: ${name}`);
     }
 
     return {
@@ -627,28 +657,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 // ---------------------------------------------------------------------------
 
 async function main(): Promise<void> {
-  // Validate required env vars
-  if (!EMAIL || !PASSWORD) {
+  if (!API_KEY) {
     console.error(
-      'Error: DIFFERINO_EMAIL and DIFFERINO_PASSWORD environment variables are required.',
+      'Error: DIFFERINO_API_KEY environment variable is required.\n' +
+        'Generate one at https://www.differino.com/settings',
     );
     process.exit(1);
   }
-  if (!SUPABASE_URL || !SUPABASE_ANON_KEY) {
-    console.error(
-      'Error: SUPABASE_URL and SUPABASE_ANON_KEY environment variables are required.',
-    );
-    process.exit(1);
-  }
-
-  // Authenticate on startup so we fail fast if credentials are wrong
-  try {
-    await authenticate();
-  } catch (err: unknown) {
-    const message = err instanceof Error ? err.message : String(err);
-    console.error(message);
-    process.exit(1);
-  }
 
   const transport = new StdioServerTransport();
   await server.connect(transport);