differino-mcp 0.5.1 → 0.5.3

package/README.md

@@ -6,7 +6,11 @@ MCP (Model Context Protocol) server for [Differino](https://www.differino.com) -
 
 ### 1. Install
 
+No install is needed: MCP clients can run the published package with `npx`. If you prefer a global install:
+
 ```bash
+npm install -g differino-mcp
+# or
 pnpm add -g differino-mcp
 ```
 
@@ -24,8 +28,8 @@ Add to your `claude_desktop_config.json`:
 {
   "mcpServers": {
     "differino": {
-      "command": "pnpm",
-      "args": ["dlx", "differino-mcp"],
+      "command": "npx",
+      "args": ["-y", "differino-mcp"],
       "env": {
         "DIFFERINO_API_KEY": "dfn_your_api_key_here"
       }
@@ -34,6 +38,8 @@ Add to your `claude_desktop_config.json`:
 }
 ```
 
+With pnpm, use `"command": "pnpm", "args": ["dlx", "differino-mcp"]` instead. Cursor and other MCP clients take the same `command` / `args` / `env` shape.
+
 ### Local development
 
 From the repository root:
@@ -52,18 +58,26 @@ pnpm --dir mcp build
 
 ### compare_documents
 
-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).
+Compare two local files and get a compact result. 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
 - `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. 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`.
+The tool uploads both files, waits for extraction and comparison, and returns:
+
+- `id`, `status`, `url` (web view) and `comparisonMode`
+- `summary`: added/removed/modified block counts
+- `visual.status` plus `visual.totalChanges`, `visual.changedPageCount` and `visual.pageCount` when the visual manifest exists
+- `creditsRemaining` and `freeComparisonRemaining`
+- `next`: the tools to call for details
+
+It deliberately does NOT include the page-by-page manifest (hundreds of KB of image URLs on long documents). Call `summarize_visual_diff` for a cheap overview of what changed, `get_text_diff` for the exact text, or `get_comparison` for the full contract with signed page image URLs. 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:
+`get_comparison` responses include the full visual artifact contract when available:
 
 - `comparisonMode`: `visual` or `text`
 - `visual.status`: `ready`, `pending`, `missing`, or `disabled`
@@ -74,6 +88,7 @@ Responses include visual artifact metadata when available:
   - `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
+- `visualManifest` (top level): deprecated duplicate of `visual.manifest`, kept for older integrations and removed in a future version
 
 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.
 
@@ -116,7 +131,7 @@ Example:
 
 ### 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).
+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`. Export jobs move through `pending`, `processing`, `completed` (with `downloadUrl`) or `failed`; with `wait: false` you get the `jobId` right after queueing and poll the REST status endpoint yourself. 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"`)
@@ -189,6 +204,7 @@ Example response:
 ```json
 {
   "credits": 42,
+  "creditsRemaining": 42,
   "freeComparisonRemaining": 0,
   "plan": "pro",
   "workspaceId": "3b2f...",
@@ -271,9 +287,11 @@ Steps 1-3 are free; only step 4 consumes the free comparison or a credit.
 
 `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.
 
+The key is bound to the request it was first used with (file contents or version ids, `comparison_mode`, `accuracy_mode`). Sending the same key with different inputs returns `422 IDEMPOTENCY_KEY_REUSED` and the id of the earlier comparison; use a fresh key for a new comparison. Keys do not expire.
+
 ### Rate limits
 
-All limits are per workspace. Exceeding one returns `429` with `code: "RATE_LIMITED"`, a `retryAfter` field (seconds), and a `Retry-After` header.
+All limits are per workspace. Exceeding a rate limit returns `429` with `code: "RATE_LIMITED"`, a `retryAfter` field (seconds), and a `Retry-After` header. `429 EXPORT_QUEUE_FULL` carries `retryAfter: 30` in the body.
 
 | Endpoint | Limit |
 |----------|-------|
@@ -292,20 +310,27 @@ All limits are per workspace. Exceeding one returns `429` with `code: "RATE_LIMI
 
 ### Error codes
 
+Every error response carries a machine-readable `code`:
+
 | 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 | `INVALID_REQUEST` | Malformed body or parameters: bad JSON, missing files or fields, invalid UUIDs, out-of-range `limit` |
+| 400 | `INVALID_FILE` | Unsupported file type, 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 |
+| 400 | `VERSION_NOT_COMPLETED` | Referenced version was created but its upload was never completed; PUT the file and call `/api/v1/uploads/complete` first |
+| 401 | `UNAUTHORIZED` | Missing or invalid API key |
 | 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 |
+| 404 | `NOT_FOUND` | Comparison or export job not found in your workspace |
+| 404 | `VERSION_NOT_FOUND` | Version not found in your workspace |
 | 413 | `PAYLOAD_TOO_LARGE` | Multipart body exceeds ~4.5 MB total; use the signed-upload flow |
+| 422 | `IDEMPOTENCY_KEY_REUSED` | Same `Idempotency-Key` with different files, versions, mode or accuracy; the response includes the earlier `comparisonId` |
 | 429 | `RATE_LIMITED` | Rate limit exceeded; retry after `retryAfter` seconds |
-| 429 | `EXPORT_QUEUE_FULL` | More than 5 export jobs pending/processing in your workspace |
+| 429 | `EXPORT_QUEUE_FULL` | More than 5 export jobs pending/processing in your workspace; `retryAfter: 30` |
+| 500 | `INTERNAL_ERROR` / `EXTRACTION_FAILED` / `COMPARISON_FAILED` | Server-side failure; metering consumed for a comparison that did not complete is refunded |
+| 504 | `EXTRACTION_TIMEOUT` | Text extraction did not finish within the request window; metering refunded |
 
-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.
+The MCP server prefixes the code to error messages (for example `[NO_CREDITS] No credits remaining...`) and appends `retryAfter` / `buyUrl` details when the API provides them.
 
 ## Supported Formats
 
@@ -317,3 +342,11 @@ When present, the `code` field is machine-readable; the MCP server prefixes it t
 
 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).
+
+## About this repository
+
+This repo contains the source of the `differino-mcp` npm package: a thin MCP client for the [Differino](https://www.differino.com) REST API. The Differino comparison engine, web app, and infrastructure are proprietary and not part of this repository. Using the API consumes Differino credits; see [pricing](https://www.differino.com/pricing).
+
+## License
+
+MIT (this MCP client only).

package/dist/index.js

@@ -44,6 +44,22 @@ const path = __importStar(require("path"));
 // ---------------------------------------------------------------------------
 const API_KEY = process.env.DIFFERINO_API_KEY || '';
 const BASE_URL = process.env.DIFFERINO_URL || 'https://www.differino.com';
+// The version announced to MCP clients is the one in package.json, so a
+// release only has to bump one place. The literal is a fallback for unusual
+// installs where the file is not next to dist/.
+const FALLBACK_VERSION = '0.5.3';
+function readPackageVersion() {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+        if (typeof pkg?.version === 'string' && pkg.version)
+            return pkg.version;
+    }
+    catch {
+        // fall through
+    }
+    return FALLBACK_VERSION;
+}
+const SERVER_VERSION = readPackageVersion();
 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
@@ -155,6 +171,46 @@ async function putToSignedUrl(uploadUrl, buffer, mimeType, label) {
         throw new Error(`Uploading ${label} to storage failed (HTTP ${res.status}): ${body.slice(0, 200)}`);
     }
 }
+/**
+ * compare_documents used to return the whole REST response, including the
+ * visual manifest with up to four signed URLs per page: hundreds of KB of
+ * tokens on long documents, all of it retrievable later with get_comparison.
+ * Return the decision-relevant part and point at the cheaper follow-up tools.
+ */
+function summarizeCompareResult(result) {
+    const visual = result?.visual ?? {};
+    const manifest = visual.manifest;
+    const status = result?.status ?? 'unknown';
+    const out = {
+        id: result?.id ?? null,
+        status,
+        url: result?.url ?? null,
+        comparisonMode: result?.comparisonMode ?? null,
+        summary: result?.summary ?? null,
+        visual: {
+            status: visual.status ?? result?.visualStatus ?? 'unknown',
+            totalChanges: manifest?.totalChanges ?? null,
+            changedPageCount: manifest?.changedPageCount ?? null,
+            pageCount: Array.isArray(manifest?.pages) ? manifest.pages.length : null,
+        },
+        creditsRemaining: result?.creditsRemaining ?? null,
+        freeComparisonRemaining: result?.freeComparisonRemaining ?? null,
+    };
+    if (result?.idempotentReplay)
+        out.idempotentReplay = true;
+    if (result?.message)
+        out.message = result.message;
+    out.next =
+        status === 'ready'
+            ? [
+                'summarize_visual_diff: cheapest page-by-page overview of what changed (visual comparisons)',
+                'get_text_diff: exact text of the changed blocks',
+                'get_comparison: full response contract including page image URLs',
+                'export_comparison_pdf: downloadable report',
+            ]
+            : ['get_comparison: poll with this id until status is ready'];
+    return JSON.stringify(out, null, 2);
+}
 async function compareDocuments(args) {
     const { file_a_path, file_b_path, comparison_mode = 'visual' } = args;
     // Validate files exist
@@ -198,7 +254,7 @@ async function compareDocuments(args) {
         method: 'POST',
         body: form,
     });
-    return JSON.stringify(result, null, 2);
+    return summarizeCompareResult(result);
 }
 async function compareViaSignedUploads(args) {
     const { nameA, nameB, extA, extB, fileABuffer, fileBBuffer, comparison_mode } = args;
@@ -236,7 +292,7 @@ async function compareViaSignedUploads(args) {
             comparisonMode: comparison_mode,
         }),
     });
-    return JSON.stringify(result, null, 2);
+    return summarizeCompareResult(result);
 }
 async function getBalance() {
     const result = await apiCall('/api/v1/me');
@@ -438,13 +494,13 @@ async function getTextDiff(args) {
 // ---------------------------------------------------------------------------
 // MCP Server
 // ---------------------------------------------------------------------------
-const server = new index_js_1.Server({ name: 'differino', version: '0.5.0' }, { capabilities: { tools: {} } });
+const server = new index_js_1.Server({ name: 'differino', version: SERVER_VERSION }, { 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. 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. ' +
+                'Reads files from local disk, uploads them to Differino, and returns a compact result: comparison id and URL, summary counters (added/removed/modified), visual.status with totalChanges and changedPageCount, and the remaining balance. It does NOT include the page-by-page manifest; call summarize_visual_diff for a cheap overview of the changes, get_text_diff for exact text, or get_comparison for the full contract with page image URLs. 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 pipeline (page renders, red/green regions, groupId, salience); 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',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "differino-mcp",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "MCP server for Differino: compare PDF, DOCX, and TXT documents from any AI agent",
   "packageManager": "pnpm@9.0.0",
   "main": "dist/index.js",
@@ -12,7 +12,7 @@
     "start": "node dist/index.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0"
+    "@modelcontextprotocol/sdk": "^1.30.0"
   },
   "devDependencies": {
     "typescript": "^5.3.0",
@@ -33,5 +33,9 @@
     "pdf",
     "docx",
     "differino"
-  ]
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sweetcucumbersalad/differino-mcp.git"
+  }
 }