differino-mcp 0.1.0 → 0.4.0

package/.next/trace

@@ -0,0 +1 @@
+[{"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/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).