differino-mcp

MCP (Model Context Protocol) server for Differino -- compare PDF, DOCX, and TXT documents from any AI agent.

Setup

1. Install

pnpm add -g differino-mcp

2. Get an API Key

1. Sign up at differino.com
2. Go to Settings → API Key
3. Click Generate Key and copy it

3. Add to Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "differino": {
      "command": "pnpm",
      "args": ["dlx", "differino-mcp"],
      "env": {
        "DIFFERINO_API_KEY": "dfn_your_api_key_here"
      }
    }
  }
}

Local development

From the repository root:

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 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
• 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.

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:

• 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

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:

{
  "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. 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, 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:

{
  "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:

{
  "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:

{
  "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:

{
  "name": "get_text_diff",
  "arguments": { "comparison_id": "8f14e45f-...", "max_blocks": 50 }
}

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:

{
  "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:

# 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" \
  -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"

# 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" \
  -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"

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:

# 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:

• 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

Error codes

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; 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...) and appends retryAfter / buyUrl details when the API provides them.

Supported Formats

• PDF (.pdf)
• Word (.docx)
• Plain Text (.txt)

Credits

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.

About this repository

This repo contains the source of the differino-mcp npm package: a thin MCP client for the Differino 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.

License

MIT (this MCP client only).