# ToolDash MCP

**Offline PDF and text tools for AI agents.** An [MCP](https://modelcontextprotocol.io) server that lets Claude Desktop, Cursor, VS Code and any other MCP client merge PDFs, pull out pages, inspect documents and clean up text — entirely on your own machine.

No upload. No API key. No account. No network call of any kind: the PDF work is done locally by [`pdf-lib`](https://github.com/Hopding/pdf-lib), so a confidential contract never leaves your laptop.

[![Powered by ToolDash](https://img.shields.io/badge/Powered%20by-ToolDash-0f766e)](https://tooldash.app)

---

## Tools

| Tool | What it does | Writes files? |
| --- | --- | --- |
| `pdf_info` | Page count, per-page dimensions and metadata of a PDF | No |
| `merge_pdfs` | Combine two or more PDFs into one, in the given order | Yes |
| `extract_pdf_pages` | Copy a page selection (`"1-3,7,10-12"`) into a new PDF | Yes |
| `clean_text` | Collapse whitespace, strip invisible characters, normalize punctuation, optionally remove URLs | No |

The two tools that write files refuse to replace an existing file unless you pass `overwrite: true`, so an agent retrying a call cannot quietly destroy a document.

## Requirements

Node.js 20 or newer.

## Install

No install step — your MCP client runs it on demand with `npx`. Add the server to your client's config and restart it.

### Claude Desktop

Edit `claude_desktop_config.json`:

- **macOS** — `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows** — `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux** — `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "tooldash": {
      "command": "npx",
      "args": ["-y", "tooldash-mcp"]
    }
  }
}
```

Restart Claude Desktop. The tools appear under the tools icon in the chat box.

### Cursor

Create `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for every project):

```json
{
  "mcpServers": {
    "tooldash": {
      "command": "npx",
      "args": ["-y", "tooldash-mcp"]
    }
  }
}
```

Then enable the server under **Settings → MCP**.

### VS Code (GitHub Copilot agent mode)

Create `.vscode/mcp.json`:

```json
{
  "servers": {
    "tooldash": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "tooldash-mcp"]
    }
  }
}
```

### Running from a clone

```bash
git clone https://github.com/LassiB999/tooldash-mcp.git
cd tooldash-mcp
npm install
npm test
```

Then point your client at `node /absolute/path/to/tooldash-mcp/server.js` instead of `npx`.

Paths may be absolute, relative to the client's working directory, or start with `~`. Surrounding quotes are stripped, so a path pasted as `"/home/you/file.pdf"` still works.

## Restricting file access

The server reads and writes wherever your user account can. To confine it to one directory, set `TOOLDASH_MCP_ROOT` — any path outside it is refused with a clear error:

```json
{
  "mcpServers": {
    "tooldash": {
      "command": "npx",
      "args": ["-y", "tooldash-mcp"],
      "env": { "TOOLDASH_MCP_ROOT": "/home/you/Documents/pdfs" }
    }
  }
}
```

## Usage examples

Ask your assistant in plain language — "merge these two PDFs and put the result on my desktop" — and it will fill in the calls below. The raw JSON is here for testing.

### `pdf_info`

```json
{ "path": "/home/you/Documents/report.pdf" }
```

```
report.pdf: 12 page(s), 248.3 KB. Title: "Q3 Report".
```

### `merge_pdfs`

```json
{
  "inputPaths": ["/home/you/Documents/cover.pdf", "/home/you/Documents/report.pdf"],
  "outputPath": "/home/you/Documents/final.pdf",
  "overwrite": false
}
```

### `extract_pdf_pages`

Pages are 1-based. Order is preserved, so `"3,1-2"` gives you page 3 first. A descending range like `"5-1"` reverses those pages.

```json
{
  "inputPath": "/home/you/Documents/report.pdf",
  "pages": "1-3,7,10-12",
  "outputPath": "/home/you/Documents/excerpt.pdf"
}
```

### `clean_text`

```json
{
  "text": "Hello   world  \r\n\r\n\r\n\r\nSecond   line   ",
  "collapseBlankLines": true,
  "normalizeQuotes": false,
  "removeUrls": false
}
```

`removeUrls` strips **every** http/https URL. The server is offline, so it cannot tell a working link from a dead one — it does not pretend to.

## How it handles failure

Bad input comes back as a readable error result the model can act on, never as a crash: a missing file, a password-protected PDF, a page number past the end of the document, or an output path that already exists each produce a message saying what to do next. The server keeps running.

Diagnostics go to `stderr` only. `stdout` carries protocol frames and nothing else — the tests would fail if anything leaked into it.

## Development

```bash
npm test                # 15 end-to-end tests: a real MCP client over stdio, on real PDFs
npm run inspect         # open the MCP Inspector against this server
```

## Powered by [ToolDash](https://tooldash.app)

ToolDash is a set of free, browser-based utilities — PDF, text, image, colour, developer and calculator tools — that run entirely in your tab with nothing uploaded. This server brings the same idea to your editor.

- **[tooldash.app](https://tooldash.app)** — the full tool collection
- **[PDF Factory](https://pdffactory.pages.dev)** — the browser PDF studio these PDF tools mirror
- **[Al-Katib](https://katib.tooldash.app)** — Arabic keyboard and writing pad

## License

MIT