distill-mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lakshman GK
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# distill-mcp
+
+An MCP server that connects any MCP-compatible client to Distill, converting
+local documents to clean, token-efficient Markdown before the LLM reads them.
+Typical token reduction is 40–80% compared to raw document text, letting the
+model fit more content into its context window and reason over it faster.
+
+Works with Claude Desktop, Claude Code, Cursor, Windsurf, and any other
+MCP client that supports tool calling.
+
+## Two Modes
+
+| | Lightweight | Full (Docker) |
+|---|---|---|
+| Requires Docker | No | Yes |
+| DOCX, XLSX, PPTX, native PDF, HTML | Yes | Yes |
+| Scanned PDF (OCR) | No | Yes |
+| Audio (MP3, WAV, etc.) | No | Yes |
+| Quality score | No | Yes |
+| Install time | ~2 min | ~10 min |
+
+**Lightweight** needs only Python and pip. **Full** needs Docker with
+the Distill service running. See the setup guides for details.
+
+## Quick install
+
+No global install required:
+
+```bash
+npx -y distill-mcp-server
+```
+
+Then configure Claude Desktop — see
+[Lightweight setup](docs/lightweight-setup.md) or
+[Full setup](docs/full-setup.md) for step-by-step instructions.
+
+## Configuration
+
+Add the server to your `claude_desktop_config.json`.
+
+**Lightweight mode — macOS / Linux:**
+
+```json
+{
+  "mcpServers": {
+    "distill-mcp": {
+      "command": "npx",
+      "args": ["-y", "distill-mcp-server"],
+      "env": {
+        "DISTILL_MCP_CONFIG": "{\"mode\":\"lightweight\",\"python_path\":\"python3\"}"
+      }
+    }
+  }
+}
+```
+
+**Lightweight mode — Windows:**
+
+```json
+{
+  "mcpServers": {
+    "distill-mcp": {
+      "command": "npx",
+      "args": ["-y", "distill-mcp-server"],
+      "env": {
+        "DISTILL_MCP_CONFIG": "{\"mode\":\"lightweight\",\"python_path\":\"py\"}"
+      }
+    }
+  }
+}
+```
+
+**Full mode — all platforms:**
+
+```json
+{
+  "mcpServers": {
+    "distill-mcp": {
+      "command": "npx",
+      "args": ["-y", "distill-mcp-server"],
+      "env": {
+        "DISTILL_MCP_CONFIG": "{\"mode\":\"full\",\"distill_url\":\"http://localhost:7860\"}"
+      }
+    }
+  }
+}
+```
+
+Full config key reference is in the setup guides:
+[Lightweight](docs/lightweight-setup.md#config-reference) |
+[Full](docs/full-setup.md#config-reference)
+
+## CLAUDE.md snippet
+
+Paste this into your project's `CLAUDE.md` so Claude knows how to use the
+tool automatically. Copy the block below as-is:
+
+```markdown
+## Document Conversion — distill-mcp
+
+When the user references a local file path (e.g. a PDF, DOCX, PPTX, XLSX,
+HTML, or audio file), ALWAYS call the `convert_and_save` tool before reading
+or reasoning about the document. Do not read the original file directly via
+filesystem tools — use only the Markdown returned by `convert_and_save` as
+the document content.
+
+### Rules
+
+1. Call `convert_and_save` with the absolute file path before doing anything
+   else with the document.
+2. Use ONLY the Markdown output from `convert_and_save` as the document
+   content. Never read the original file with filesystem tools.
+3. If the response includes `"overwritten": true`, tell the user that a
+   previous cached version was replaced before proceeding.
+4. If the response includes any `warnings`, surface them to the user before
+   proceeding with the document content.
+5. If `convert_and_save` returns an unsupported format error, tell the user
+   which formats are supported and suggest switching modes if applicable.
+
+### Supported formats
+
+| Category | Lightweight | Full (Docker) |
+|---|---|---|
+| Word | .docx, .doc, .odt | .docx, .doc, .odt |
+| Excel | .xlsx, .xlsm, .csv | .xlsx, .xlsm, .csv |
+| PowerPoint | .pptx, .ppt | .pptx, .ppt |
+| PDF | .pdf (native text) | .pdf (native + scanned OCR) |
+| HTML | .html, .htm | .html, .htm |
+| Audio | — | .mp3, .wav, .m4a, .flac, .ogg |
+| Other | — | .epub, .json, .sql, .wsdl, .wsd |
+
+### Usage
+
+Say "convert using distill" followed by the file path:
+> Convert using distill C:\Users\me\Documents\report.pdf to markdown
+```
+
+The snippet is also available in
+[docs/CLAUDE.md-snippet.md](docs/CLAUDE.md-snippet.md).
+
+## Supported formats
+
+| Category | Extensions | Lightweight | Full |
+|---|---|---|---|
+| Microsoft Word | `.docx`, `.doc`, `.odt` | Yes | Yes |
+| Microsoft Excel | `.xlsx`, `.xlsm`, `.csv` | Yes | Yes |
+| Microsoft PowerPoint | `.pptx`, `.ppt` | Yes | Yes |
+| PDF (native text) | `.pdf` | Yes | Yes |
+| PDF (scanned/OCR) | `.pdf` | No | Yes |
+| HTML | `.html`, `.htm` | Yes | Yes |
+| Audio | `.mp3`, `.wav`, `.m4a`, `.flac`, `.ogg` | No | Yes |
+| EPUB | `.epub` | No | Yes |
+| JSON | `.json` | No | Yes |
+| SQL | `.sql` | No | Yes |
+| WSDL | `.wsdl`, `.wsd` | No | Yes |
+
+## Privacy
+
+All processing happens locally. In lightweight mode, documents are converted
+by the distill-core Python library on your machine — no data leaves your
+computer. In full mode, documents are sent to the Distill Docker service
+running locally on your machine — no data is sent to external services.
+
+## Built on
+
+[Distill](https://github.com/nicholasgasior/distill) — document-to-Markdown
+conversion engine.
+
+## License
+
+MIT

package/docs/CLAUDE.md-snippet.md

@@ -0,0 +1,46 @@
+# CLAUDE.md Snippet for distill-mcp
+
+Paste the block below into your project's `CLAUDE.md` file. This tells Claude
+how to use the `convert_and_save` tool when it encounters document file paths.
+
+---
+
+```markdown
+## Document Conversion — distill-mcp
+
+When the user references a local file path (e.g. a PDF, DOCX, PPTX, XLSX,
+HTML, or audio file), ALWAYS call the `convert_and_save` tool before reading
+or reasoning about the document. Do not read the original file directly via
+filesystem tools — use only the Markdown returned by `convert_and_save` as
+the document content.
+
+### Rules
+
+1. Call `convert_and_save` with the absolute file path before doing anything
+   else with the document.
+2. Use ONLY the Markdown output from `convert_and_save` as the document
+   content. Never read the original file with filesystem tools.
+3. If the response includes `"overwritten": true`, tell the user that a
+   previous cached version was replaced before proceeding.
+4. If the response includes any `warnings`, surface them to the user before
+   proceeding with the document content.
+5. If `convert_and_save` returns an unsupported format error, tell the user
+   which formats are supported and suggest switching modes if applicable.
+
+### Supported formats
+
+| Category | Lightweight | Full (Docker) |
+|---|---|---|
+| Word | .docx, .doc, .odt | .docx, .doc, .odt |
+| Excel | .xlsx, .xlsm, .csv | .xlsx, .xlsm, .csv |
+| PowerPoint | .pptx, .ppt | .pptx, .ppt |
+| PDF | .pdf (native text) | .pdf (native + scanned OCR) |
+| HTML | .html, .htm | .html, .htm |
+| Audio | — | .mp3, .wav, .m4a, .flac, .ogg |
+| Other | — | .epub, .json, .sql, .wsdl, .wsd |
+
+### Usage
+
+Say "convert using distill" followed by the file path:
+> Convert using distill C:\Users\me\Documents\report.pdf to markdown
+```

package/docs/full-setup.md

@@ -0,0 +1,149 @@
+# Full Mode Setup
+
+Full mode sends documents to the Distill REST API running in Docker. It supports
+all lightweight formats plus scanned PDFs (via OCR) and audio transcription.
+
+## Prerequisites
+
+- **Node.js 22 or later**
+  Download from [nodejs.org](https://nodejs.org/) if not already installed.
+  Verify: `node --version`
+
+- **Docker Desktop installed and running**
+  If Docker is not installed, download it from
+  <https://docs.docker.com/get-docker/>
+
+  After installing, verify Docker is running:
+  ```bash
+  docker info
+  ```
+  This should print system information without errors.
+
+- **Distill service running via Docker**
+  From your Distill project directory:
+  ```bash
+  docker compose up -d
+  ```
+  Verify the service is up:
+  ```bash
+  curl http://localhost:7860/docs
+  ```
+  You should see an HTML page (Swagger UI). If the command fails, check that
+  Docker is running and the container started without errors
+  (`docker compose logs`).
+
+> **If you skip this step** and launch the MCP server, the first conversion
+> will fail with:
+> ```
+> Distill service is not running. Start it with: docker compose up -d
+> Then restart Claude Desktop.
+> ```
+> This same error appears whether Docker is not installed, Docker is installed
+> but not running, or the Distill container has not been started. If you see
+> this error, start by confirming Docker is installed and running, then start
+> the Distill service with `docker compose up -d`.
+
+## Installation
+
+No global install required. The server runs via `npx`:
+
+```bash
+npx -y distill-mcp-server
+```
+
+## Configuration
+
+Open your `claude_desktop_config.json`:
+
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+Add the distill server to the `mcpServers` section.
+
+**macOS / Linux / Windows** (config is identical on all platforms):
+
+```json
+{
+  "mcpServers": {
+    "distill-mcp": {
+      "command": "npx",
+      "args": ["-y", "distill-mcp-server"],
+      "env": {
+        "DISTILL_MCP_CONFIG": "{\"mode\":\"full\",\"distill_url\":\"http://localhost:7860\"}"
+      }
+    }
+  }
+}
+```
+
+If Distill is running on a non-default host or port, change `distill_url`:
+
+```json
+"DISTILL_MCP_CONFIG": "{\"mode\":\"full\",\"distill_url\":\"http://192.168.1.50:7860\"}"
+```
+
+## Config reference
+
+| Key | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `mode` | string | Yes | — | Must be `"full"` |
+| `distill_url` | string | No | `http://localhost:7860` | Distill service base URL |
+| `cache_dir` | string | No | `~/Documents/distill-cache` | Directory where converted `.md` files are saved |
+
+## Supported formats
+
+Full mode supports everything in lightweight mode, plus additional formats.
+
+| Category | Extensions |
+|---|---|
+| Microsoft Word | `.docx`, `.doc`, `.odt` |
+| Microsoft Excel | `.xlsx`, `.xlsm`, `.csv` |
+| Microsoft PowerPoint | `.pptx`, `.ppt` |
+| PDF (native text and scanned/OCR) | `.pdf` |
+| HTML | `.html`, `.htm` |
+| Audio | `.mp3`, `.wav`, `.m4a`, `.flac`, `.ogg` |
+| EPUB | `.epub` |
+| JSON | `.json` |
+| SQL | `.sql` |
+| WSDL | `.wsdl`, `.wsd` |
+
+## Quality score
+
+Full mode returns a `quality_score` (0.0–1.0) with every conversion. It
+measures heading, table, and list preservation plus token efficiency.
+
+- **0.70 and above:** Good conversion. No warning.
+- **Below 0.70:** A warning is included in the response:
+  ```
+  Quality score 0.65 is below threshold (0.70). The conversion completed
+  but some structure may be lost. Check the document for complex tables
+  or non-standard formatting.
+  ```
+
+The conversion is always returned regardless of the score — the warning is
+informational, not a failure. The 0.70 threshold is fixed and not configurable.
+
+## Test it
+
+Restart Claude Desktop (fully quit and reopen, including the system tray icon
+on Windows). The distill connector should appear in the connectors list.
+
+In a new conversation, type:
+
+> Convert using distill C:\Users\me\Documents\report.pdf to markdown
+
+Claude will call the `convert_and_save` tool, send the file to Distill, and
+return the Markdown content. The converted file is also saved to your cache
+directory.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `Distill service is not running` | Docker not installed, not running, or container not started | Install Docker from [docs.docker.com/get-docker](https://docs.docker.com/get-docker/), start it, then run `docker compose up -d` |
+| Health check timeout | Docker Desktop not running, or wrong `distill_url` | Verify Docker is running (`docker info`), check the URL matches your Distill service |
+| Quality score warning | Document has complex tables or non-standard formatting | Review the converted Markdown for accuracy. The conversion is still usable |
+| `File not found` | Path must be absolute | Provide the full path, e.g. `C:\Users\me\Documents\report.pdf`, not `report.pdf` |
+| Tool does not appear in Claude Desktop | Config JSON is malformed or server failed to start | Check `%APPDATA%\Claude\logs\mcp-server-distill.log` (Windows) or `~/Library/Logs/Claude/mcp-server-distill.log` (macOS) for errors |
+| Claude asks to upload instead of using the tool | Model did not auto-select the tool | Include "distill" in your prompt: "Convert using distill ..." |
+| "Taking longer than usual" during conversion | Large file — Distill needs more time | This is normal for large documents. The conversion will complete |

package/docs/lightweight-setup.md

@@ -0,0 +1,113 @@
+# Lightweight Mode Setup
+
+Lightweight mode shells out to the distill-core Python library to convert
+documents. No Docker required.
+
+## Prerequisites
+
+- **Node.js 22 or later**
+  Download from [nodejs.org](https://nodejs.org/) if not already installed.
+  Verify: `node --version`
+
+- **Python 3**
+  The Python command differs by operating system:
+  - **Windows:** Install from [python.org](https://www.python.org/downloads/).
+    The standard launcher is invoked as `py`.
+  - **macOS/Linux:** Typically pre-installed. Invoked as `python3`.
+  Verify: `py --version` (Windows) or `python3 --version` (macOS/Linux)
+
+- **distill-core Python package**
+  Install via pip:
+  - **Windows:** `py -m pip install distill-core`
+  - **macOS/Linux:** `python3 -m pip install distill-core`
+
+## Installation
+
+No global install required. The server runs via `npx`:
+
+```bash
+npx -y distill-mcp-server
+```
+
+## Configuration
+
+Open your `claude_desktop_config.json`:
+
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+Add the distill server to the `mcpServers` section.
+
+**macOS / Linux:**
+
+```json
+{
+  "mcpServers": {
+    "distill-mcp": {
+      "command": "npx",
+      "args": ["-y", "distill-mcp-server"],
+      "env": {
+        "DISTILL_MCP_CONFIG": "{\"mode\":\"lightweight\",\"python_path\":\"python3\"}"
+      }
+    }
+  }
+}
+```
+
+**Windows:**
+
+```json
+{
+  "mcpServers": {
+    "distill-mcp": {
+      "command": "npx",
+      "args": ["-y", "distill-mcp-server"],
+      "env": {
+        "DISTILL_MCP_CONFIG": "{\"mode\":\"lightweight\",\"python_path\":\"py\"}"
+      }
+    }
+  }
+}
+```
+
+The only difference is `python_path` — `"python3"` on macOS/Linux, `"py"` on
+Windows.
+
+## Config reference
+
+| Key | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `mode` | string | Yes | — | Must be `"lightweight"` |
+| `python_path` | string | No | `"py"` (Windows) / `"python3"` (macOS/Linux) | Path to Python binary |
+| `cache_dir` | string | No | `~/Documents/distill-cache` | Directory where converted `.md` files are saved |
+
+## Supported formats
+
+| Category | Extensions |
+|---|---|
+| Microsoft Word | `.docx`, `.doc`, `.odt` |
+| Microsoft Excel | `.xlsx`, `.xlsm`, `.csv` |
+| Microsoft PowerPoint | `.pptx`, `.ppt` |
+| PDF (native text only) | `.pdf` |
+| HTML | `.html`, `.htm` |
+
+Scanned/image PDFs are not supported in lightweight mode. Use
+[full mode](full-setup.md) for OCR and audio transcription.
+
+## Test it
+
+Restart Claude Desktop (fully quit and reopen). In a new conversation, type:
+
+> Convert using distill C:\Users\me\Documents\report.pdf to markdown
+
+Claude will call the `convert_and_save` tool and return the Markdown content.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `ModuleNotFoundError: No module named 'distill'` | distill-core is not installed | Run `py -m pip install distill-core` (Windows) or `python3 -m pip install distill-core` (macOS/Linux) |
+| `No module named distill.__main__` | Wrong invocation — distill-core has no CLI entry point | Ensure `python_path` is set correctly (`py` on Windows, `python3` on macOS/Linux). The server uses the Python API, not `python -m distill` |
+| `File not found` | Path must be absolute | Provide the full path, e.g. `C:\Users\me\Documents\report.pdf`, not `report.pdf` |
+| `Unsupported format` | File extension is not in the lightweight supported list | Check the supported formats table above. For scanned PDFs and audio, switch to [full mode](full-setup.md) |
+| Claude asks to upload instead of using the tool | Model did not auto-select the tool | Include "distill" in your prompt: "Convert using distill ..." |

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "distill-mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for Distill — convert documents to token-efficient Markdown in any MCP-compatible client",
+  "type": "module",
+  "engines": { "node": ">=22.0.0" },
+  "bin": {
+    "distill-mcp-server": "./src/index.js"
+  },
+  "files": [
+    "src/",
+    "docs/lightweight-setup.md",
+    "docs/full-setup.md",
+    "docs/CLAUDE.md-snippet.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node --test"
+  },
+  "keywords": [
+    "mcp",
+    "claude",
+    "distill",
+    "markdown",
+    "document-conversion",
+    "model-context-protocol"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lakshgk/distill-mcp"
+  },
+  "homepage": "https://github.com/lakshgk/distill-mcp#readme"
+}

package/src/cache.js

@@ -0,0 +1,28 @@
+import { mkdir, writeFile, access } from 'node:fs/promises';
+import { join, basename, extname } from 'node:path';
+
+export async function save(markdown, sourcePath, cacheDir) {
+  const sourceBase = basename(sourcePath);
+  const ext = extname(sourceBase);
+  const nameWithoutExt = ext ? sourceBase.slice(0, -ext.length) : sourceBase;
+  const cacheFilename = `${nameWithoutExt}.md`;
+  const targetPath = join(cacheDir, cacheFilename);
+
+  let overwritten = false;
+
+  try {
+    try {
+      await access(targetPath);
+      overwritten = true;
+    } catch {
+      overwritten = false;
+    }
+
+    await mkdir(cacheDir, { recursive: true });
+    await writeFile(targetPath, markdown, 'utf-8');
+
+    return { cachedAt: targetPath, overwritten };
+  } catch (err) {
+    return { cachedAt: null, overwritten: false, saveError: err.message };
+  }
+}

package/src/config.js

@@ -0,0 +1,52 @@
+import { homedir, platform } from 'node:os';
+import { join } from 'node:path';
+import { ConfigError } from './errors.js';
+
+const VALID_MODES = ['lightweight', 'full'];
+
+// Windows: "py" is the standard launcher; macOS/Linux: "python3"
+const DEFAULT_PYTHON_PATH = platform() === 'win32' ? 'py' : 'python3';
+
+function getDefaultCacheDir() {
+  const home = homedir();
+  return join(home, 'Documents', 'distill-cache');
+}
+
+export function loadConfig() {
+  const raw = process.env.DISTILL_MCP_CONFIG;
+
+  if (!raw) {
+    throw new ConfigError(
+      'DISTILL_MCP_CONFIG environment variable is not set. See README for configuration instructions.'
+    );
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new ConfigError(
+      'DISTILL_MCP_CONFIG is not valid JSON. See README for configuration instructions.'
+    );
+  }
+
+  const { mode, cache_dir, distill_url, python_path } = parsed;
+
+  if (!mode || !VALID_MODES.includes(mode)) {
+    throw new ConfigError(
+      `Invalid or missing "mode". Must be one of: ${VALID_MODES.join(', ')}. See README for configuration instructions.`
+    );
+  }
+
+  let resolvedCacheDir = cache_dir || getDefaultCacheDir();
+  if (typeof resolvedCacheDir === 'string' && resolvedCacheDir.startsWith('~')) {
+    resolvedCacheDir = join(homedir(), resolvedCacheDir.slice(1));
+  }
+
+  return {
+    mode,
+    cache_dir: resolvedCacheDir,
+    distill_url: distill_url || 'http://localhost:7860',
+    python_path: python_path || DEFAULT_PYTHON_PATH,
+  };
+}

package/src/errors.js

@@ -0,0 +1,59 @@
+class DistillMcpError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'DistillMcpError';
+    this.code = code;
+  }
+}
+
+class ConfigError extends DistillMcpError {
+  constructor(message) {
+    super('CONFIG_ERROR', message);
+    this.name = 'ConfigError';
+  }
+}
+
+class FileNotFoundError extends DistillMcpError {
+  constructor(message) {
+    super('FILE_NOT_FOUND_ERROR', message);
+    this.name = 'FileNotFoundError';
+  }
+}
+
+class UnsupportedFormatError extends DistillMcpError {
+  constructor(message) {
+    super('UNSUPPORTED_FORMAT_ERROR', message);
+    this.name = 'UnsupportedFormatError';
+  }
+}
+
+class DistillUnavailableError extends DistillMcpError {
+  constructor(message) {
+    super('DISTILL_UNAVAILABLE_ERROR', message);
+    this.name = 'DistillUnavailableError';
+  }
+}
+
+class CacheWriteError extends DistillMcpError {
+  constructor(message) {
+    super('CACHE_WRITE_ERROR', message);
+    this.name = 'CacheWriteError';
+  }
+}
+
+class ConversionError extends DistillMcpError {
+  constructor(message) {
+    super('CONVERSION_ERROR', message);
+    this.name = 'ConversionError';
+  }
+}
+
+export {
+  DistillMcpError,
+  ConfigError,
+  FileNotFoundError,
+  UnsupportedFormatError,
+  DistillUnavailableError,
+  CacheWriteError,
+  ConversionError,
+};

package/src/index.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { loadConfig } from './config.js';
+import { ConfigError } from './errors.js';
+import { handle as handleConvertAndSave } from './tools/convert_and_save.js';
+
+async function main() {
+  let config;
+  try {
+    config = loadConfig();
+  } catch (err) {
+    if (err instanceof ConfigError) {
+      process.stderr.write(`Configuration error: ${err.message}\n`);
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  const server = new McpServer({
+    name: 'distill-mcp',
+    version: '0.1.0',
+  });
+
+  server.tool(
+    'convert_and_save',
+    'YOU HAVE ACCESS TO THE LOCAL FILESYSTEM THROUGH THIS TOOL. When a user asks to convert, read, or process a document and provides a file path, ALWAYS use this tool — do NOT ask them to upload. This tool accepts an absolute file path (e.g. C:/Users/name/Documents/report.pdf) and converts the file to clean Markdown using the Distill document processing engine running locally. Supports DOCX, PDF, XLSX, PPTX, HTML, audio files, and more. Returns high-quality Markdown and saves a cached copy.',
+    {
+      file_path: z.string().describe('Absolute path to the document to convert'),
+    },
+    async (args, extra) => {
+      try {
+        return await handleConvertAndSave(args, config, extra);
+      } catch (err) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: `Unexpected error: ${err.message}` }],
+        };
+      }
+    }
+  );
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  process.stderr.write(`Fatal error: ${err.message}\n`);
+  process.exit(1);
+});

package/src/modes/full.js

@@ -0,0 +1,68 @@
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { ConversionError, DistillUnavailableError } from '../errors.js';
+
+const SERVICE_DOWN_MESSAGE =
+  'Distill service is not running. Start it with: docker compose up -d\nThen restart Claude Desktop.';
+
+export async function convert(filePath, config) {
+  const url = `${config.distill_url}/api/convert`;
+
+  let fileBuffer;
+  try {
+    fileBuffer = await readFile(filePath);
+  } catch (err) {
+    throw new ConversionError(`Failed to read file: ${err.message}`);
+  }
+
+  const form = new FormData();
+  form.append('file', new Blob([fileBuffer]), basename(filePath));
+  form.append('output_format', 'markdown');
+
+  let response;
+  try {
+    response = await fetch(url, { method: 'POST', body: form });
+  } catch {
+    throw new DistillUnavailableError(SERVICE_DOWN_MESSAGE);
+  }
+
+  if (!response.ok) {
+    let detail;
+    try {
+      const body = await response.json();
+      detail = body.detail || `HTTP ${response.status}`;
+    } catch {
+      detail = `HTTP ${response.status}`;
+    }
+    throw new ConversionError(detail);
+  }
+
+  const data = await response.json();
+
+  return {
+    markdown: data.markdown,
+    quality_score: data.quality?.overall ?? null,
+    warnings: data.warnings || [],
+  };
+}
+
+export async function checkHealth(config) {
+  const url = `${config.distill_url}/`;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 3000);
+
+  try {
+    const response = await fetch(url, { signal: controller.signal });
+    if (!response.ok) {
+      throw new DistillUnavailableError(SERVICE_DOWN_MESSAGE);
+    }
+    return true;
+  } catch (err) {
+    if (err instanceof DistillUnavailableError) {
+      throw err;
+    }
+    throw new DistillUnavailableError(SERVICE_DOWN_MESSAGE);
+  } finally {
+    clearTimeout(timeout);
+  }
+}

package/src/modes/lightweight.js

@@ -0,0 +1,47 @@
+import { execFile } from 'node:child_process';
+import { ConversionError } from '../errors.js';
+
+export async function convert(filePath, config) {
+  const pythonPath = config.python_path;
+
+  return new Promise((resolve, reject) => {
+    let proc;
+    try {
+      proc = execFile(
+        pythonPath,
+        [
+          '-c',
+          `import distill, sys, io; sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8'); result = distill.convert(sys.argv[1]); print(result.markdown)`,
+          filePath,
+        ],
+        { maxBuffer: 50 * 1024 * 1024, encoding: 'utf-8' },
+        (error, stdout, stderr) => {
+          if (error) {
+            reject(
+              new ConversionError(
+                stderr ? stderr.trim() : error.message
+              )
+            );
+            return;
+          }
+          resolve({ markdown: stdout });
+        }
+      );
+    } catch (err) {
+      reject(
+        new ConversionError(
+          `Failed to spawn subprocess: ${err.message}`
+        )
+      );
+      return;
+    }
+
+    proc.on('error', (err) => {
+      reject(
+        new ConversionError(
+          `Failed to spawn subprocess: ${err.message}`
+        )
+      );
+    });
+  });
+}

package/src/tools/convert_and_save.js

@@ -0,0 +1,154 @@
+import { access } from 'node:fs/promises';
+import { resolve, extname } from 'node:path';
+import { convert as lightweightConvert } from '../modes/lightweight.js';
+import { convert as fullConvert, checkHealth } from '../modes/full.js';
+import { save } from '../cache.js';
+
+let healthChecked = false;
+
+const LIGHTWEIGHT_EXTENSIONS = new Set([
+  '.docx', '.doc', '.odt',
+  '.xlsx', '.xlsm', '.csv',
+  '.pptx', '.ppt',
+  '.pdf',
+  '.html', '.htm',
+]);
+
+const FULL_EXTENSIONS = new Set([
+  ...LIGHTWEIGHT_EXTENSIONS,
+  '.mp3', '.wav', '.m4a', '.flac', '.ogg',
+  '.epub', '.json', '.sql', '.wsdl', '.wsd',
+]);
+
+const QUALITY_THRESHOLD = 0.70;
+
+function errorResponse(text) {
+  return {
+    isError: true,
+    content: [{ type: 'text', text }],
+  };
+}
+
+async function sendProgress(extra, progress, total, message) {
+  const token = extra?._meta?.progressToken;
+  if (token === undefined || !extra?.sendNotification) return;
+  try {
+    await extra.sendNotification({
+      method: 'notifications/progress',
+      params: { progressToken: token, progress, total, message },
+    });
+  } catch {
+    // Progress notifications are best-effort
+  }
+}
+
+export async function handle(args, config, extra) {
+  try {
+    const filePath = args.file_path;
+
+    if (!filePath || typeof filePath !== 'string' || filePath.trim() === '') {
+      return errorResponse('file_path is required and must be a non-empty string.');
+    }
+
+    const resolvedPath = resolve(filePath);
+
+    if (resolvedPath.includes('..')) {
+      return errorResponse('Path traversal is not allowed.');
+    }
+
+    try {
+      await access(resolvedPath);
+    } catch {
+      return errorResponse(`File not found: ${resolvedPath}`);
+    }
+
+    const ext = extname(resolvedPath).toLowerCase();
+    await sendProgress(extra, 1, 4, 'Validating file');
+
+    const supportedExtensions = config.mode === 'full' ? FULL_EXTENSIONS : LIGHTWEIGHT_EXTENSIONS;
+
+    if (!supportedExtensions.has(ext)) {
+      const modeLabel = config.mode === 'full' ? 'full' : 'lightweight';
+      const extList = [...supportedExtensions].join(' ');
+      return errorResponse(
+        `Unsupported format: ${ext}. Supported formats in ${modeLabel} mode: ${extList}.` +
+        (config.mode === 'lightweight' ? ' Switch to full mode for scanned PDF and audio.' : '')
+      );
+    }
+
+    if (config.mode === 'full' && !healthChecked) {
+      await sendProgress(extra, 2, 5, 'Checking Distill service');
+      try {
+        await checkHealth(config);
+        healthChecked = true;
+      } catch (err) {
+        return errorResponse(err.message);
+      }
+    }
+
+    await sendProgress(extra, config.mode === 'full' ? 3 : 2, config.mode === 'full' ? 5 : 4, 'Converting document with Distill');
+
+    let result;
+    try {
+      if (config.mode === 'full') {
+        result = await fullConvert(resolvedPath, config);
+      } else {
+        result = await lightweightConvert(resolvedPath, config);
+      }
+    } catch (err) {
+      if (err.message && /scanned/i.test(err.message)) {
+        return errorResponse(
+          'This PDF appears to be scanned. Switch to full mode for OCR support.'
+        );
+      }
+      return errorResponse(err.message);
+    }
+
+    const { markdown } = result;
+    await sendProgress(extra, config.mode === 'full' ? 4 : 3, config.mode === 'full' ? 5 : 4, 'Saving to cache');
+
+    const cacheResult = await save(markdown, resolvedPath, config.cache_dir);
+
+    const warnings = [];
+
+    if (config.mode === 'full') {
+      if (result.warnings && result.warnings.length > 0) {
+        for (const w of result.warnings) {
+          warnings.push(typeof w === 'string' ? w : w.message || JSON.stringify(w));
+        }
+      }
+      if (result.quality_score != null && result.quality_score < QUALITY_THRESHOLD) {
+        warnings.push(
+          `Quality score ${result.quality_score} is below threshold (0.70). The conversion ` +
+          'completed but some structure may be lost. Check the document for complex tables ' +
+          'or non-standard formatting.'
+        );
+      }
+    }
+
+    if (cacheResult.saveError) {
+      warnings.push(`Cache save failed: ${cacheResult.saveError}`);
+    }
+
+    await sendProgress(extra, config.mode === 'full' ? 5 : 4, config.mode === 'full' ? 5 : 4, 'Done');
+
+    const response = {
+      markdown,
+      cached_at: cacheResult.cachedAt,
+      overwritten: cacheResult.overwritten,
+      source_file: resolvedPath,
+      format_detected: ext.slice(1),
+      mode: config.mode,
+      ...(config.mode === 'full' && result.quality_score != null
+        ? { quality_score: result.quality_score }
+        : {}),
+      warnings,
+    };
+
+    return {
+      content: [{ type: 'text', text: JSON.stringify(response, null, 2) }],
+    };
+  } catch (err) {
+    return errorResponse(`Unexpected error: ${err.message}`);
+  }
+}