differino-mcp 0.4.0 → 0.5.0

package/README.md

@@ -59,7 +59,9 @@ Compare two local files and get a diff summary plus the visual document-review m
 - `file_b_path` (required) -- Absolute path to the modified document
 - `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`.
+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. Successful responses include `creditsRemaining` and `freeComparisonRemaining`. 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`.
+
+Files up to 45 MB each are supported. Small pairs (up to ~4 MB combined) go through the multipart endpoint; larger files are uploaded automatically via signed upload URLs (`POST /api/v1/uploads` -> direct PUT to storage -> `POST /api/v1/uploads/complete` -> compare by version ids). This is transparent: you always just call `compare_documents`.
 
 Responses include visual artifact metadata when available:
 
@@ -176,14 +178,33 @@ Example:
 }
 ```
 
+### get_balance
+
+Get the account status of the workspace behind the API key: credit balance, whether the lifetime free comparison is still available, effective plan, and workspace id. Useful before `compare_documents` or after a `[NO_CREDITS]` error. Free.
+
+**Parameters:** none
+
+Example response:
+
+```json
+{
+  "credits": 42,
+  "freeComparisonRemaining": 0,
+  "plan": "pro",
+  "workspaceId": "3b2f...",
+  "buyUrl": "https://www.differino.com/billing?pack=comparino"
+}
+```
+
 ## REST API
 
 The MCP server uses the Differino REST API under the hood. You can also call it directly:
 
 ```bash
-# Compare two files
+# Compare two SMALL files (multipart body limited to ~4.5 MB total on Vercel)
 curl -X POST https://www.differino.com/api/v1/compare \
   -H "Authorization: Bearer dfn_your_api_key" \
+  -H "Idempotency-Key: my-unique-key-001" \
   -F "file_a=@original.pdf" \
   -F "file_b=@modified.pdf" \
   -F "comparison_mode=visual" \
@@ -197,6 +218,10 @@ curl https://www.differino.com/api/v1/comparisons/{id} \
 curl "https://www.differino.com/api/v1/comparisons?limit=10&status=ready" \
   -H "Authorization: Bearer dfn_your_api_key"
 
+# Account status: credits, free comparison, plan
+curl https://www.differino.com/api/v1/me \
+  -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" \
@@ -207,6 +232,56 @@ curl "https://www.differino.com/api/v1/comparisons/{id}/export?jobId={jobId}" \
   -H "Authorization: Bearer dfn_your_api_key"
 ```
 
+### Large files: the signed-upload flow
+
+Multipart `POST /api/v1/compare` is limited to about 4.5 MB of TOTAL request body (Vercel limit); above that it returns `413 PAYLOAD_TOO_LARGE`. For files up to 45 MB each, upload directly to storage:
+
+```bash
+# 1. Init: declare both files, get signed upload URLs + version ids
+curl -X POST https://www.differino.com/api/v1/uploads \
+  -H "Authorization: Bearer dfn_your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{"fileA": {"name": "original.pdf", "type": "application/pdf", "size": 10485760},
+       "fileB": {"name": "modified.pdf", "type": "application/pdf", "size": 11534336}}'
+
+# 2. PUT each file body to its uploadUrl (URLs are valid for 2 hours)
+curl -X PUT "{fileA.uploadUrl}" \
+  -H "Content-Type: application/pdf" \
+  --data-binary @original.pdf
+curl -X PUT "{fileB.uploadUrl}" \
+  -H "Content-Type: application/pdf" \
+  --data-binary @modified.pdf
+
+# 3. Complete: verify the stored objects and queue extraction
+curl -X POST https://www.differino.com/api/v1/uploads/complete \
+  -H "Authorization: Bearer dfn_your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{"versionIds": ["{fileA.versionId}", "{fileB.versionId}"]}'
+
+# 4. Compare the uploaded versions (JSON body instead of multipart)
+curl -X POST https://www.differino.com/api/v1/compare \
+  -H "Authorization: Bearer dfn_your_api_key" \
+  -H "Content-Type: application/json" \
+  -d '{"versionAId": "{fileA.versionId}", "versionBId": "{fileB.versionId}", "comparisonMode": "visual"}'
+```
+
+Steps 1-3 are free; only step 4 consumes the free comparison or a credit.
+
+### Idempotency
+
+`POST /api/v1/compare` accepts an optional `Idempotency-Key` header (up to 200 characters). Repeating a key within your workspace returns the existing comparison (`idempotentReplay: true`) without charging again. Use it to make retries safe.
+
+### Rate limits
+
+All limits are per workspace. Exceeding one returns `429` with `code: "RATE_LIMITED"`, a `retryAfter` field (seconds), and a `Retry-After` header.
+
+| Endpoint | Limit |
+|----------|-------|
+| `POST /api/v1/compare` | 10 / minute |
+| `POST /api/v1/comparisons/{id}/export` | 20 / hour, plus at most 5 pending/processing export jobs (`429 EXPORT_QUEUE_FULL`) |
+| `GET` endpoints (list, get, export status, me) | 120 / minute (shared) |
+| `POST /api/v1/uploads` + `/uploads/complete` | 30 / minute (shared) |
+
 ### accuracy_mode
 
 `POST /api/v1/compare` accepts an optional `accuracy_mode` form field:
@@ -220,11 +295,17 @@ curl "https://www.differino.com/api/v1/comparisons/{id}/export?jobId={jobId}" \
 | HTTP | `code` | Meaning |
 |------|--------|---------|
 | 400 | | Invalid request: missing files, unsupported file type, file too large, or invalid parameters |
+| 400 | `INVALID_FILE` | File content does not match its extension (magic-byte check), or upload verification failed |
+| 400 | `FILE_TOO_LARGE` | Declared file size exceeds the 45 MB per-file limit |
+| 400 | `VERSION_FAILED` / `VERSION_NOT_PENDING` | Referenced version cannot be used (processing failed, or already completed) |
 | 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 |
+| 402 | `NO_CREDITS` | No free comparison left and no credits remaining; the response includes `buyUrl` (https://www.differino.com/billing?pack=comparino) |
+| 404 | `VERSION_NOT_FOUND` | Comparison, version, or export job not found in your workspace |
+| 413 | `PAYLOAD_TOO_LARGE` | Multipart body exceeds ~4.5 MB total; use the signed-upload flow |
+| 429 | `RATE_LIMITED` | Rate limit exceeded; retry after `retryAfter` seconds |
+| 429 | `EXPORT_QUEUE_FULL` | More than 5 export jobs pending/processing in your workspace |
 
-When present, the `code` field is machine-readable; the MCP server prefixes it to error messages (for example `[NO_CREDITS] No credits remaining...`).
+When present, the `code` field is machine-readable; the MCP server prefixes it to error messages (for example `[NO_CREDITS] No credits remaining...`) and appends `retryAfter` / `buyUrl` details when the API provides them.
 
 ## Supported Formats
 

package/dist/index.js

@@ -47,6 +47,12 @@ 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
+// Vercel rejects request bodies above ~4.5 MB, so multipart /api/v1/compare
+// only works for small pairs. Above this COMBINED size we transparently use
+// the signed-upload flow (uploads -> PUT -> complete -> compare by version
+// ids), which supports files up to 45 MB each.
+const MULTIPART_TOTAL_LIMIT_BYTES = 4 * 1024 * 1024;
+const UPLOAD_TIMEOUT_MS = 600_000; // 10 minutes for direct-to-storage PUTs
 // ---------------------------------------------------------------------------
 // HTTP helpers
 // ---------------------------------------------------------------------------
@@ -87,8 +93,15 @@ async function apiCall(endpoint, options = {}) {
         throw new Error(`Non-JSON response from ${endpoint} (HTTP ${res.status}): ${text.slice(0, 200)}`);
     }
     if (!res.ok) {
-        const message = json.error || `API error ${res.status}: ${text.slice(0, 300)}`;
-        // Surface machine-readable error codes (e.g. NO_CREDITS) to the agent.
+        let message = json.error || `API error ${res.status}: ${text.slice(0, 300)}`;
+        // Surface actionable metadata to the agent.
+        if (json.code === 'RATE_LIMITED' && json.retryAfter != null) {
+            message += ` Wait ${json.retryAfter} seconds before retrying.`;
+        }
+        if (json.buyUrl) {
+            message += ` Buy credits at ${json.buyUrl}`;
+        }
+        // Surface machine-readable error codes (e.g. NO_CREDITS, RATE_LIMITED) to the agent.
         throw new Error(json.code ? `[${json.code}] ${message}` : message);
     }
     return json;
@@ -118,6 +131,30 @@ function getMimeType(ext) {
 // ---------------------------------------------------------------------------
 // Tool implementations
 // ---------------------------------------------------------------------------
+async function putToSignedUrl(uploadUrl, buffer, mimeType, label) {
+    let res;
+    try {
+        res = await fetch(uploadUrl, {
+            method: 'PUT',
+            headers: {
+                'Content-Type': mimeType,
+                'x-upsert': 'false',
+            },
+            body: new Uint8Array(buffer),
+            signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS),
+        });
+    }
+    catch (err) {
+        if (isTimeoutError(err)) {
+            throw new Error(`Uploading ${label} timed out after ${UPLOAD_TIMEOUT_MS / 1000}s. Try again.`);
+        }
+        throw err;
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new Error(`Uploading ${label} to storage failed (HTTP ${res.status}): ${body.slice(0, 200)}`);
+    }
+}
 async function compareDocuments(args) {
     const { file_a_path, file_b_path, comparison_mode = 'visual' } = args;
     // Validate files exist
@@ -136,10 +173,23 @@ async function compareDocuments(args) {
     if (!SUPPORTED_EXTENSIONS.has(extB)) {
         throw new Error(`Unsupported file type for ${nameB}. Supported: PDF, DOCX, TXT.`);
     }
-    // Build multipart form
-    const form = new FormData();
     const fileABuffer = fs.readFileSync(file_a_path);
     const fileBBuffer = fs.readFileSync(file_b_path);
+    // Large pairs cannot go through the multipart endpoint (Vercel caps request
+    // bodies at ~4.5 MB total). Use the signed-upload flow transparently.
+    if (fileABuffer.length + fileBBuffer.length > MULTIPART_TOTAL_LIMIT_BYTES) {
+        return compareViaSignedUploads({
+            nameA,
+            nameB,
+            extA,
+            extB,
+            fileABuffer,
+            fileBBuffer,
+            comparison_mode,
+        });
+    }
+    // Build multipart form
+    const form = new FormData();
     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);
@@ -150,6 +200,48 @@ async function compareDocuments(args) {
     });
     return JSON.stringify(result, null, 2);
 }
+async function compareViaSignedUploads(args) {
+    const { nameA, nameB, extA, extB, fileABuffer, fileBBuffer, comparison_mode } = args;
+    // 1. Init: create documents/versions and get signed upload URLs.
+    const init = await apiCall('/api/v1/uploads', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            fileA: { name: nameA, type: getMimeType(extA), size: fileABuffer.length },
+            fileB: { name: nameB, type: getMimeType(extB), size: fileBBuffer.length },
+        }),
+    });
+    if (!init?.fileA?.uploadUrl || !init?.fileB?.uploadUrl) {
+        throw new Error('Signed upload init did not return upload URLs.');
+    }
+    // 2. PUT both files directly to storage.
+    await putToSignedUrl(init.fileA.uploadUrl, fileABuffer, getMimeType(extA), nameA);
+    await putToSignedUrl(init.fileB.uploadUrl, fileBBuffer, getMimeType(extB), nameB);
+    // 3. Complete: verify the stored objects and queue extraction.
+    await apiCall('/api/v1/uploads/complete', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            versionIds: [init.fileA.versionId, init.fileB.versionId],
+            visualArtifacts: comparison_mode === 'visual',
+        }),
+    });
+    // 4. Compare the uploaded versions.
+    const result = await apiCall('/api/v1/compare', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            versionAId: init.fileA.versionId,
+            versionBId: init.fileB.versionId,
+            comparisonMode: comparison_mode,
+        }),
+    });
+    return JSON.stringify(result, null, 2);
+}
+async function getBalance() {
+    const result = await apiCall('/api/v1/me');
+    return JSON.stringify(result, null, 2);
+}
 async function getComparison(args) {
     const result = await apiCall(`/api/v1/comparisons/${args.comparison_id}`);
     return JSON.stringify(result, null, 2);
@@ -346,14 +438,14 @@ async function getTextDiff(args) {
 // ---------------------------------------------------------------------------
 // MCP Server
 // ---------------------------------------------------------------------------
-const server = new index_js_1.Server({ name: 'differino', version: '0.4.0' }, { capabilities: { tools: {} } });
+const server = new index_js_1.Server({ name: 'differino', version: '0.5.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 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.',
+                'Reads files from local disk, uploads them to Differino, and returns a text diff summary. Files up to 45 MB each are supported: large files are uploaded automatically via signed upload URLs. 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; the response includes creditsRemaining and freeComparisonRemaining.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -498,6 +590,16 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
                 required: ['comparison_id'],
             },
         },
+        {
+            name: 'get_balance',
+            description: 'Get the account status of the workspace behind the API key: credit balance, whether the lifetime free comparison is still available, effective plan, and workspace id. ' +
+                'Use it before compare_documents to know whether a comparison can be paid for, or after a [NO_CREDITS] error to confirm the balance and get the purchase URL. Does not consume credits.',
+            inputSchema: {
+                type: 'object',
+                properties: {},
+                required: [],
+            },
+        },
     ],
 }));
 server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
@@ -523,6 +625,9 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             case 'get_text_diff':
                 result = await getTextDiff(args);
                 break;
+            case 'get_balance':
+                result = await getBalance();
+                break;
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "differino-mcp",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "MCP server for Differino document comparison",
   "packageManager": "pnpm@9.0.0",
   "main": "dist/index.js",
@@ -17,5 +17,9 @@
   "devDependencies": {
     "typescript": "^5.3.0",
     "@types/node": "^20.0.0"
-  }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
 }

package/.next/trace

@@ -1 +0,0 @@
-[{"name":"generate-buildid","duration":115,"timestamp":148958595929,"id":4,"parentId":1,"tags":{},"startTime":1774429523967,"traceId":"be39ecf3904fcb99"},{"name":"load-custom-routes","duration":119,"timestamp":148958596120,"id":5,"parentId":1,"tags":{},"startTime":1774429523967,"traceId":"be39ecf3904fcb99"},{"name":"next-build","duration":82517,"timestamp":148958517288,"id":1,"tags":{"buildMode":"default","isTurboBuild":"false","version":"14.1.0","isTurbopack":false},"startTime":1774429523888,"traceId":"be39ecf3904fcb99"}]

package/src/index.ts

@@ -1,675 +0,0 @@
-#!/usr/bin/env node
-
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import {
-  CallToolRequestSchema,
-  ListToolsRequestSchema,
-} from '@modelcontextprotocol/sdk/types.js';
-import * as fs from 'fs';
-import * as path from 'path';
-
-// ---------------------------------------------------------------------------
-// Configuration
-// ---------------------------------------------------------------------------
-
-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 = {},
-): Promise<any> {
-  const url = `${BASE_URL}${endpoint}`;
-  const headers: Record<string, string> = {
-    Authorization: `Bearer ${API_KEY}`,
-    ...(options.headers as Record<string, string> || {}),
-  };
-
-  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} (HTTP ${res.status}): ${text.slice(0, 200)}`);
-  }
-
-  if (!res.ok) {
-    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
-// ---------------------------------------------------------------------------
-
-const SUPPORTED_EXTENSIONS = new Set(['pdf', 'docx', 'txt']);
-
-function getExtension(filename: string): string {
-  return (filename.split('.').pop() || '').toLowerCase();
-}
-
-function getMimeType(ext: string): string {
-  switch (ext) {
-    case 'pdf':
-      return 'application/pdf';
-    case 'docx':
-      return 'application/vnd.openxmlformats-officedocument.wordprocessingml.document';
-    case 'txt':
-      return 'text/plain';
-    default:
-      return 'application/octet-stream';
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Tool implementations
-// ---------------------------------------------------------------------------
-
-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, comparison_mode = 'visual' } = args;
-
-  // Validate files exist
-  for (const fp of [file_a_path, file_b_path]) {
-    if (!fs.existsSync(fp)) {
-      throw new Error(`File not found: ${fp}`);
-    }
-  }
-
-  const nameA = path.basename(file_a_path);
-  const nameB = path.basename(file_b_path);
-  const extA = getExtension(nameA);
-  const extB = getExtension(nameB);
-
-  if (!SUPPORTED_EXTENSIONS.has(extA)) {
-    throw new Error(`Unsupported file type for ${nameA}. Supported: PDF, DOCX, TXT.`);
-  }
-  if (!SUPPORTED_EXTENSIONS.has(extB)) {
-    throw new Error(`Unsupported file type for ${nameB}. Supported: PDF, DOCX, TXT.`);
-  }
-
-  // Build multipart form
-  const form = new FormData();
-  const fileABuffer = fs.readFileSync(file_a_path);
-  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,
-  );
-  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,
-  });
-
-  return JSON.stringify(result, null, 2);
-}
-
-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);
-}
-
-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:
-        `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,
-  );
-}
-
-// ---------------------------------------------------------------------------
-// MCP Server
-// ---------------------------------------------------------------------------
-
-const server = new Server(
-  { name: 'differino', version: '0.4.0' },
-  { capabilities: { tools: {} } },
-);
-
-server.setRequestHandler(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 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: {
-          file_a_path: {
-            type: 'string',
-            description: 'Absolute path to the original document',
-          },
-          file_b_path: {
-            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, 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: {
-          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 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'],
-      },
-    },
-  ],
-}));
-
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  const { name, arguments: args } = request.params;
-
-  try {
-    let result: string;
-
-    switch (name) {
-      case 'compare_documents':
-        result = await compareDocuments(args as any);
-        break;
-      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:
-        throw new Error(`Unknown tool: ${name}`);
-    }
-
-    return {
-      content: [{ type: 'text', text: result }],
-    };
-  } catch (err: unknown) {
-    const message = err instanceof Error ? err.message : String(err);
-    return {
-      content: [{ type: 'text', text: `Error: ${message}` }],
-      isError: true,
-    };
-  }
-});
-
-// ---------------------------------------------------------------------------
-// Entry point
-// ---------------------------------------------------------------------------
-
-async function main(): Promise<void> {
-  if (!API_KEY) {
-    console.error(
-      'Error: DIFFERINO_API_KEY environment variable is required.\n' +
-        'Generate one at https://www.differino.com/settings',
-    );
-    process.exit(1);
-  }
-
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-}
-
-main().catch((err) => {
-  console.error('Fatal error:', err);
-  process.exit(1);
-});

package/tsconfig.json

@@ -1,14 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "Node16",
-    "moduleResolution": "Node16",
-    "outDir": "dist",
-    "rootDir": "src",
-    "strict": true,
-    "esModuleInterop": true,
-    "declaration": true,
-    "skipLibCheck": true
-  },
-  "include": ["src/**/*"]
-}