differino-mcp 0.2.0 → 0.4.0

package/README.md

@@ -1,41 +1,20 @@
 # differino-mcp
 
-MCP (Model Context Protocol) server for [Differino](https://differino.com) -- compare PDF, DOCX, and TXT documents from any AI agent.
+MCP (Model Context Protocol) server for [Differino](https://www.differino.com) -- compare PDF, DOCX, and TXT documents from any AI agent.
 
 ## Setup
 
 ### 1. Install
 
 ```bash
-cd mcp
-npm install
-npm run build
+pnpm add -g differino-mcp
 ```
 
-Or install globally:
+### 2. Get an API Key
 
-```bash
-npm install -g differino-mcp
-```
-
-### 2. Configure
-
-Set environment variables:
-
-```bash
-export DIFFERINO_EMAIL="your@email.com"
-export DIFFERINO_PASSWORD="your-password"
-export SUPABASE_URL="https://your-project.supabase.co"
-export SUPABASE_ANON_KEY="your-anon-key"
-```
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `DIFFERINO_EMAIL` | Yes | Your Differino account email |
-| `DIFFERINO_PASSWORD` | Yes | Your Differino account password |
-| `SUPABASE_URL` | Yes | Supabase project URL (also accepts `DIFFERINO_SUPABASE_URL`) |
-| `SUPABASE_ANON_KEY` | Yes | Supabase anon/public key (also accepts `DIFFERINO_SUPABASE_ANON_KEY`) |
-| `DIFFERINO_URL` | No | Base URL for the web app (default: `https://differino.com`) |
+1. Sign up at [differino.com](https://www.differino.com/signup)
+2. Go to **Settings → API Key**
+3. Click **Generate Key** and copy it
 
 ### 3. Add to Claude Desktop
 
@@ -45,68 +24,207 @@ Add to your `claude_desktop_config.json`:
 {
   "mcpServers": {
     "differino": {
-      "command": "node",
-      "args": ["/path/to/comparadocs/mcp/dist/index.js"],
+      "command": "pnpm",
+      "args": ["dlx", "differino-mcp"],
       "env": {
-        "DIFFERINO_EMAIL": "your@email.com",
-        "DIFFERINO_PASSWORD": "your-password",
-        "SUPABASE_URL": "https://your-project.supabase.co",
-        "SUPABASE_ANON_KEY": "your-anon-key"
+        "DIFFERINO_API_KEY": "dfn_your_api_key_here"
       }
     }
   }
 }
 ```
 
-Or if installed globally via npm:
+### Local development
 
-```json
-{
-  "mcpServers": {
-    "differino": {
-      "command": "npx",
-      "args": ["differino-mcp"],
-      "env": {
-        "DIFFERINO_EMAIL": "your@email.com",
-        "DIFFERINO_PASSWORD": "your-password",
-        "SUPABASE_URL": "https://your-project.supabase.co",
-        "SUPABASE_ANON_KEY": "your-anon-key"
-      }
-    }
-  }
-}
+From the repository root:
+
+```bash
+pnpm install
+pnpm --dir mcp build
 ```
 
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `DIFFERINO_API_KEY` | Yes | Your API key -- generate at Settings → API Key |
+| `DIFFERINO_URL` | No | Base URL (default: `https://www.differino.com`) |
+
 ## Tools
 
 ### compare_documents
 
-Compare two local files and get a diff summary.
+Compare two local files and get a diff summary plus the visual document-review manifest when available. This is the only tool that consumes a comparison (your free comparison or 1 credit).
 
 **Parameters:**
 - `file_a_path` (required) -- Absolute path to the original document
 - `file_b_path` (required) -- Absolute path to the modified document
-- `accuracy_mode` (optional) -- `fast`, `balanced` (default), or `thorough`
+- `comparison_mode` (optional) -- `visual` for full document review, or `text` for fast text-only comparison (default: `visual`)
+
+The tool uploads both files, waits for extraction and comparison, and returns a summary with added/removed/modified block counts plus a link to the full comparison. If the server is still working when the internal wait expires, the response has `status: "processing"`; poll `get_comparison` with the returned `id` until `status` is `ready`.
+
+Responses include visual artifact metadata when available:
 
-The tool uploads both files, waits for text extraction and diff computation, and returns a summary with added/removed/modified block counts plus a link to the full visual comparison.
+- `comparisonMode`: `visual` or `text`
+- `visual.status`: `ready`, `pending`, `missing`, or `disabled`
+- `visual.manifest`: the document-review contract when `visual.status` is `ready`
+  - `pages[]`: side-by-side page pairs with image URLs and dimensions
+  - `pages[].regions[]`: red/green-ready change regions with `leftBox`, `rightBox`, snippets, change type, salience metadata, and a stable `groupId`
+  - `regions[].groupId`: shared identity for paired change fragments, including changes that cross page boundaries
+  - `regions[].salience`: `subtle`, `visible`, `structural`, or `technical`, plus `salienceReason` when available
+  - `totalChanges` and `changedPageCount`: summary fields for compact controls and optional review navigation; paired fragments with the same `groupId` count as one change
+- `visual.diffUrl`: signed URL for the visual diff JSON when available
 
-Files under 4 MB are uploaded directly. Larger files use a signed-URL flow that bypasses Vercel's body size limit.
+Agents should treat `visual.manifest` as the primary surface for professional document review: render the two documents continuously, draw exact inline highlights when coordinates are present, use `groupId` for selection and synchronized scrolling, and derive center-gutter/minimap markers from the region coordinates. If `visual.status` is not `ready`, agents should use the text diff summary and comparison URL instead of assuming there are no visual changes.
+
+Example:
+
+```json
+{
+  "name": "compare_documents",
+  "arguments": {
+    "file_a_path": "/docs/contract_v1.pdf",
+    "file_b_path": "/docs/contract_v2.pdf",
+    "comparison_mode": "visual"
+  }
+}
+```
 
 ### get_comparison
 
-Check the status and results of a comparison by its UUID.
+Check the status and results of a comparison by its UUID. Returns the same visual artifact contract as `compare_documents`, with fresh signed URLs. Use it to poll comparisons that returned `status: "processing"`. Free (does not consume credits).
+
+**Parameters:**
+- `comparison_id` (required) -- The comparison UUID
 
 ### list_comparisons
 
-List recent comparisons in your workspace (default: 10).
+List recent comparisons in your workspace, newest first. Returns `id`, `status`, `comparisonMode`, `file_a`/`file_b` name and type, `summary` counters, `created_at`, and `completed_at` for each comparison. Useful to recover a comparison id or check recent activity. Free.
+
+**Parameters:**
+- `limit` (optional) -- Maximum results, 1 to 50 (default: 10)
+- `status` (optional) -- Filter by `pending`, `processing`, `ready`, or `failed`
+
+Example:
+
+```json
+{
+  "name": "list_comparisons",
+  "arguments": { "limit": 5, "status": "ready" }
+}
+```
+
+### export_comparison_pdf
+
+Export a finished comparison as a PDF report and get a temporary download URL (valid for about 5 minutes). With `wait: true` (default) the tool polls the export job every 2 seconds for up to 3 minutes and returns the `downloadUrl`. Free workspaces get a watermarked PDF; workspaces with credits export without watermark. Free (exports do not consume credits).
+
+**Parameters:**
+- `comparison_id` (required) -- The comparison UUID (must have `status: "ready"`)
+- `include_unchanged` (optional) -- Include unchanged content in the report (default: `false`)
+- `locale` (optional) -- Report language: `en`, `es`, `zh`, `fr`, `de`, or `hi` (default: `en`)
+- `wait` (optional) -- Poll until the export completes (default: `true`)
+
+Example:
+
+```json
+{
+  "name": "export_comparison_pdf",
+  "arguments": {
+    "comparison_id": "8f14e45f-...",
+    "locale": "es",
+    "include_unchanged": false
+  }
+}
+```
+
+### summarize_visual_diff
+
+Compact, page-by-page summary of the visual diff: one entry per change group (fragments that share a `groupId` are deduplicated), with change type, title, salience, and optional text snippets. No image URLs and no pixel coordinates, so it is the cheapest way for an agent to understand what changed and where. Requires a visual comparison with `visual.status: "ready"`. Free.
+
+**Parameters:**
+- `comparison_id` (required) -- The comparison UUID
+- `min_salience` (optional) -- Only include changes at or above this prominence level; order is `technical` < `subtle` < `visible` < `structural`
+- `include_snippets` (optional) -- Include `snippetA`/`snippetB` excerpts (default: `true`)
+- `max_changes_per_page` (optional) -- Cap per page, extra changes are counted as omitted (default: 20)
+
+Example:
+
+```json
+{
+  "name": "summarize_visual_diff",
+  "arguments": {
+    "comparison_id": "8f14e45f-...",
+    "min_salience": "visible",
+    "max_changes_per_page": 10
+  }
+}
+```
+
+### get_text_diff
+
+Fetch the block-level text diff of a finished comparison. Returns the diff summary counters plus the diff blocks: `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. Best when you need to quote exact text changes. Free.
+
+**Parameters:**
+- `comparison_id` (required) -- The comparison UUID (must have `status: "ready"`)
+- `only_changed` (optional) -- Skip `equal` blocks (default: `true`)
+- `max_blocks` (optional) -- Maximum blocks returned (default: 100)
+
+Example:
+
+```json
+{
+  "name": "get_text_diff",
+  "arguments": { "comparison_id": "8f14e45f-...", "max_blocks": 50 }
+}
+```
+
+## REST API
+
+The MCP server uses the Differino REST API under the hood. You can also call it directly:
+
+```bash
+# Compare two files
+curl -X POST https://www.differino.com/api/v1/compare \
+  -H "Authorization: Bearer dfn_your_api_key" \
+  -F "file_a=@original.pdf" \
+  -F "file_b=@modified.pdf" \
+  -F "comparison_mode=visual" \
+  -F "accuracy_mode=balanced"
+
+# Check comparison status
+curl https://www.differino.com/api/v1/comparisons/{id} \
+  -H "Authorization: Bearer dfn_your_api_key"
+
+# List recent comparisons
+curl "https://www.differino.com/api/v1/comparisons?limit=10&status=ready" \
+  -H "Authorization: Bearer dfn_your_api_key"
+
+# Export a comparison as PDF, then poll for the download URL
+curl -X POST https://www.differino.com/api/v1/comparisons/{id}/export \
+  -H "Authorization: Bearer dfn_your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{"format": "pdf", "includeUnchanged": false, "locale": "en"}'
+
+curl "https://www.differino.com/api/v1/comparisons/{id}/export?jobId={jobId}" \
+  -H "Authorization: Bearer dfn_your_api_key"
+```
+
+### accuracy_mode
+
+`POST /api/v1/compare` accepts an optional `accuracy_mode` form field:
 
-### list_documents
+- `fast` -- quickest results, best for plain text and simple layouts (default for `comparison_mode=text`)
+- `balanced` -- good accuracy/speed trade-off (default for `comparison_mode=visual`)
+- `thorough` -- maximum accuracy for complex layouts, slower
 
-List documents in your Differino library (default: 20).
+### Error codes
 
-### get_credits
+| HTTP | `code` | Meaning |
+|------|--------|---------|
+| 400 | | Invalid request: missing files, unsupported file type, file too large, or invalid parameters |
+| 401 | | Missing or invalid API key |
+| 402 | `NO_CREDITS` | No free comparison left and no credits remaining; buy a pack at [differino.com/pricing](https://www.differino.com/pricing) |
+| 404 | | Comparison or export job not found in your workspace |
 
-Check your credit balance, current plan, and free comparison usage for the month.
+When present, the `code` field is machine-readable; the MCP server prefixes it to error messages (for example `[NO_CREDITS] No credits remaining...`).
 
 ## Supported Formats
 
@@ -116,5 +234,5 @@ Check your credit balance, current plan, and free comparison usage for the month
 
 ## Credits
 
-3 free comparisons per month. After that, each comparison costs 1 credit.
-Buy credit packs at [differino.com/pricing](https://differino.com/pricing).
+Every account gets 1 free comparison (lifetime, not monthly). After that, each comparison costs 1 credit. Checking results, listing comparisons, exporting PDFs, and reading diffs are always free.
+Buy credit packs at [differino.com/pricing](https://www.differino.com/pricing).

package/dist/index.js

@@ -44,29 +44,58 @@ const path = __importStar(require("path"));
 // ---------------------------------------------------------------------------
 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
 // ---------------------------------------------------------------------------
 // HTTP helpers
 // ---------------------------------------------------------------------------
+function isTimeoutError(err) {
+    return (err instanceof Error &&
+        (err.name === 'TimeoutError' ||
+            err.name === 'AbortError' ||
+            (err.cause instanceof Error &&
+                (err.cause.name === 'TimeoutError' || err.cause.name === 'AbortError'))));
+}
 async function apiCall(endpoint, options = {}) {
     const url = `${BASE_URL}${endpoint}`;
     const headers = {
         Authorization: `Bearer ${API_KEY}`,
         ...(options.headers || {}),
     };
-    const res = await fetch(url, { ...options, headers });
+    let res;
+    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();
     let json;
     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) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 // ---------------------------------------------------------------------------
 // File utilities
 // ---------------------------------------------------------------------------
@@ -90,11 +119,11 @@ function getMimeType(ext) {
 // Tool implementations
 // ---------------------------------------------------------------------------
 async function compareDocuments(args) {
-    const { file_a_path, file_b_path } = args;
+    const { file_a_path, file_b_path, comparison_mode = 'visual' } = args;
     // 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}`);
         }
     }
     const nameA = path.basename(file_a_path);
@@ -102,10 +131,10 @@ async function compareDocuments(args) {
     const extA = getExtension(nameA);
     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.`);
     }
     // Build multipart form
     const form = new FormData();
@@ -113,7 +142,8 @@ async function compareDocuments(args) {
     const fileBBuffer = fs.readFileSync(file_b_path);
     form.append('file_a', new Blob([fileABuffer], { type: getMimeType(extA) }), nameA);
     form.append('file_b', new Blob([fileBBuffer], { type: getMimeType(extB) }), nameB);
-    // Call the REST API — it handles upload, extraction, comparison, and polling
+    form.append('comparison_mode', comparison_mode);
+    // Call the REST API. It handles upload, extraction, comparison, and polling.
     const result = await apiCall('/api/v1/compare', {
         method: 'POST',
         body: form,
@@ -125,23 +155,205 @@ async function getComparison(args) {
     return JSON.stringify(result, null, 2);
 }
 async function listComparisons(args) {
-    // Use the internal session-less API — falls through to REST
-    // For now, this tool is simplified to just report the endpoint
+    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();
+    const result = await apiCall(`/api/v1/comparisons${qs ? `?${qs}` : ''}`);
+    return JSON.stringify(result, null, 2);
+}
+async function exportComparisonPdf(args) {
+    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({
+            format: 'pdf',
+            includeUnchanged: include_unchanged,
+            locale,
+        }),
+    });
+    const jobId = 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({
+                jobId,
+                status: 'completed',
+                downloadUrl: statusRes.downloadUrl,
+                note: 'The download URL is signed and expires in about 5 minutes.',
+            }, null, 2);
+        }
+        if (statusRes.status === 'failed') {
+            throw new Error(`Export failed: ${statusRes.error || 'unknown error'}`);
+        }
+    }
+    return JSON.stringify({
+        jobId,
+        status: 'processing',
+        message: `Export still processing after ${EXPORT_POLL_TIMEOUT_MS / 1000}s. ` +
+            `Poll GET ${statusEndpoint} for the downloadUrl.`,
+    }, null, 2);
+}
+// Prominence order used by min_salience filtering, lowest to highest.
+const SALIENCE_RANK = {
+    technical: 0,
+    subtle: 1,
+    visible: 2,
+    structural: 3,
+};
+async function summarizeVisualDiff(args) {
+    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}`);
+    }
+    const minRank = min_salience ? SALIENCE_RANK[min_salience] ?? 0 : 0;
+    const seenGroups = new Set();
+    const pages = [];
+    let listedChanges = 0;
+    let filteredBySalience = 0;
+    for (const page of manifest.pages ?? []) {
+        const regions = page.regions ?? [];
+        const changes = [];
+        let omittedChanges = 0;
+        for (const region of regions) {
+            const groupKey = 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 = region.salience ?? 'visible';
+            if ((SALIENCE_RANK[salience] ?? SALIENCE_RANK.visible) < minRank) {
+                filteredBySalience += 1;
+                continue;
+            }
+            if (changes.length >= max_changes_per_page) {
+                omittedChanges += 1;
+                continue;
+            }
+            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;
+        }
+        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.`,
+                    }
+                    : {}),
+            });
+        }
+    }
+    return JSON.stringify({
+        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 getTextDiff(args) {
+    const { comparison_id, only_changed = true, max_blocks = 100 } = args;
+    const comparison = await apiCall(`/api/v1/comparisons/${comparison_id}`);
+    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.');
+    }
+    // diffUrl is a signed URL; no auth header needed.
+    let res;
+    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 diff = (await res.json());
+    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({
-        message: 'Use compare_documents to create comparisons, and get_comparison to check results.',
-        api_docs: `${BASE_URL}/mcp`,
+        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);
 }
 // ---------------------------------------------------------------------------
 // MCP Server
 // ---------------------------------------------------------------------------
-const server = new index_js_1.Server({ name: 'differino', version: '0.2.0' }, { capabilities: { tools: {} } });
+const server = new index_js_1.Server({ name: 'differino', version: '0.4.0' }, { capabilities: { tools: {} } });
 server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
     tools: [
         {
             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 with a URL to view the full comparison.',
+                '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',
                 properties: {
@@ -153,13 +365,118 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
                         type: 'string',
                         description: 'Absolute path to the modified document',
                     },
+                    comparison_mode: {
+                        type: 'string',
+                        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'],
             },
         },
         {
             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',
+                properties: {
+                    comparison_id: {
+                        type: 'string',
+                        description: 'The comparison UUID',
+                    },
+                },
+                required: ['comparison_id'],
+            },
+        },
+        {
+            name: 'list_comparisons',
+            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',
+                properties: {
+                    limit: {
+                        type: 'number',
+                        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: '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',
+                properties: {
+                    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',
+                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 changes listed per page; extra changes are counted as omitted',
+                        default: 20,
+                    },
+                },
+                required: ['comparison_id'],
+            },
+        },
+        {
+            name: 'get_text_diff',
+            description: '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',
                 properties: {
@@ -167,6 +484,16 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
                         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'],
             },
@@ -184,8 +511,20 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             case 'get_comparison':
                 result = await getComparison(args);
                 break;
+            case 'list_comparisons':
+                result = await listComparisons(args);
+                break;
+            case 'export_comparison_pdf':
+                result = await exportComparisonPdf(args);
+                break;
+            case 'summarize_visual_diff':
+                result = await summarizeVisualDiff(args);
+                break;
+            case 'get_text_diff':
+                result = await getTextDiff(args);
+                break;
             default:
-                result = `Unknown tool: ${name}`;
+                throw new Error(`Unknown tool: ${name}`);
         }
         return {
             content: [{ type: 'text', text: result }],

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "differino-mcp",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "MCP server for Differino document comparison",
+  "packageManager": "pnpm@9.0.0",
   "main": "dist/index.js",
   "bin": {
     "differino-mcp": "dist/index.js"

package/src/index.ts

@@ -16,10 +16,24 @@ import * as path from 'path';
 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
+
 // ---------------------------------------------------------------------------
 // HTTP helpers
 // ---------------------------------------------------------------------------
 
+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')))
+  );
+}
+
 async function apiCall(
   endpoint: string,
   options: RequestInit = {},
@@ -30,23 +44,44 @@ async function apiCall(
     ...(options.headers as Record<string, string> || {}),
   };
 
-  const res = await fetch(url, { ...options, headers });
+  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();
   let json: any;
   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
 // ---------------------------------------------------------------------------
@@ -77,13 +112,14 @@ function getMimeType(ext: string): string {
 async function compareDocuments(args: {
   file_a_path: string;
   file_b_path: string;
+  comparison_mode?: 'visual' | 'text';
 }): Promise<string> {
-  const { file_a_path, file_b_path } = args;
+  const { file_a_path, file_b_path, comparison_mode = 'visual' } = args;
 
   // 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}`);
     }
   }
 
@@ -93,10 +129,10 @@ 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.`);
   }
 
   // Build multipart form
@@ -114,8 +150,9 @@ async function compareDocuments(args: {
     new Blob([fileBBuffer], { type: getMimeType(extB) }),
     nameB,
   );
+  form.append('comparison_mode', comparison_mode);
 
-  // Call the REST API — it handles upload, extraction, comparison, and polling
+  // Call the REST API. It handles upload, extraction, comparison, and polling.
   const result = await apiCall('/api/v1/compare', {
     method: 'POST',
     body: form,
@@ -129,14 +166,276 @@ async function getComparison(args: { comparison_id: string }): Promise<string> {
   return JSON.stringify(result, null, 2);
 }
 
-async function listComparisons(args: { limit?: number }): Promise<string> {
-  // Use the internal session-less API — falls through to REST
-  // For now, this tool is simplified to just report the endpoint
+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();
+
+  const result = await apiCall(`/api/v1/comparisons${qs ? `?${qs}` : ''}`);
+  return JSON.stringify(result, null, 2);
+}
+
+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({
+      format: 'pdf',
+      includeUnchanged: include_unchanged,
+      locale,
+    }),
+  });
+
+  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(
+        {
+          jobId,
+          status: 'completed',
+          downloadUrl: statusRes.downloadUrl,
+          note: 'The download URL is signed and expires in about 5 minutes.',
+        },
+        null,
+        2,
+      );
+    }
+    if (statusRes.status === 'failed') {
+      throw new Error(`Export failed: ${statusRes.error || 'unknown error'}`);
+    }
+  }
+
   return JSON.stringify(
     {
+      jobId,
+      status: 'processing',
       message:
-        'Use compare_documents to create comparisons, and get_comparison to check results.',
-      api_docs: `${BASE_URL}/mcp`,
+        `Export still processing after ${EXPORT_POLL_TIMEOUT_MS / 1000}s. ` +
+        `Poll GET ${statusEndpoint} for the downloadUrl.`,
+    },
+    null,
+    2,
+  );
+}
+
+// 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}`,
+    );
+  }
+
+  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 (changes.length >= max_changes_per_page) {
+        omittedChanges += 1;
+        continue;
+      }
+
+      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;
+    }
+
+    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.`,
+            }
+          : {}),
+      });
+    }
+  }
+
+  return JSON.stringify(
+    {
+      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 getTextDiff(args: {
+  comparison_id: string;
+  only_changed?: boolean;
+  max_blocks?: number;
+}): Promise<string> {
+  const { comparison_id, only_changed = true, max_blocks = 100 } = args;
+
+  const comparison = await apiCall(`/api/v1/comparisons/${comparison_id}`);
+
+  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.');
+  }
+
+  // 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 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 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(
+    {
+      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,
@@ -148,7 +447,7 @@ async function listComparisons(args: { limit?: number }): Promise<string> {
 // ---------------------------------------------------------------------------
 
 const server = new Server(
-  { name: 'differino', version: '0.2.0' },
+  { name: 'differino', version: '0.4.0' },
   { capabilities: { tools: {} } },
 );
 
@@ -158,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 with a URL to view the full comparison.',
+        '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: {
@@ -170,6 +470,12 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             type: 'string',
             description: 'Absolute path to the modified document',
           },
+          comparison_mode: {
+            type: 'string',
+            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'],
       },
@@ -177,7 +483,47 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     {
       name: 'get_comparison',
       description:
-        'Get the status and results of a specific comparison by its ID.',
+        '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: {
+          comparison_id: {
+            type: 'string',
+            description: 'The comparison UUID',
+          },
+        },
+        required: ['comparison_id'],
+      },
+    },
+    {
+      name: 'list_comparisons',
+      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 (1-50)',
+            default: 10,
+          },
+          status: {
+            type: 'string',
+            enum: ['pending', 'processing', 'ready', 'failed'],
+            description: 'Only return comparisons with this status',
+          },
+        },
+        required: [],
+      },
+    },
+    {
+      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: {
@@ -185,6 +531,79 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             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 changes listed per page; extra changes are counted as omitted',
+            default: 20,
+          },
+        },
+        required: ['comparison_id'],
+      },
+    },
+    {
+      name: 'get_text_diff',
+      description:
+        '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: {
+          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'],
       },
@@ -205,8 +624,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'get_comparison':
         result = await getComparison(args as any);
         break;
+      case 'list_comparisons':
+        result = await listComparisons(args as any);
+        break;
+      case 'export_comparison_pdf':
+        result = await exportComparisonPdf(args as any);
+        break;
+      case 'summarize_visual_diff':
+        result = await summarizeVisualDiff(args as any);
+        break;
+      case 'get_text_diff':
+        result = await getTextDiff(args as any);
+        break;
       default:
-        result = `Unknown tool: ${name}`;
+        throw new Error(`Unknown tool: ${name}`);
     }
 
     return {