pdfdancer-mcp

<p align="center"> <img src="media/logo-orange-60h.webp" alt="PDFDancer logo" height="60"> </p> # pdfdancer-mcp **Add PDFDancer to your AI coding assistant** Edit text in any real-world PDF. Even ones you didn't create. PDFDancer edits inbound PDFs like a real document format: paragraphs, lines, glyphs, vectors, forms, plus ML-driven font handling for missing or embedded fonts. `pdfdancer-mcp` is a Model Context Protocol (MCP) server that connects PDFDancer to MCP-compatible AI coding assistants so they can write, run, and refactor PDFDancer SDK code inside your projects (TypeScript, Python, and Java). Use it to build and maintain services, workflows, and tooling that transform PDFs you didn’t create. Ideal for ingestion pipelines, document workflows, and AI agents that need to modify PDFs in production. --- ## For Users ### Requirements - **Node.js** >= v18.0.0 - **MCP Client**: Cursor, Claude Code, VS Code, Windsurf, Zed, or any other MCP-compatible client ### Installation Add this MCP server to your preferred AI coding assistant. Choose your client below for specific installation instructions. <details> <summary><b>Install in Cursor</b></summary> #### Option 1: One-Click Installation (Recommended) Click the button below to install pdfdancer-mcp in Cursor: [](cursor://anysphere.cursor-deeplink/mcp/install?name=pdfdancer&config=eyJjb21tYW5kIjoibnB4IC15IEBwZGZkYW5jZXIvcGRmZGFuY2VyLW1jcCJ9) #### Option 2: Manual Configuration 1. Open Cursor Settings 2. Navigate to the "MCP" section 3. Add the following configuration: ```json { "mcpServers": { "pdfdancer-mcp": { "command": "npx", "args": ["-y", "@pdfdancer/pdfdancer-mcp"] } } } ``` </details> <details> <summary><b>Install in Claude Code</b></summary> #### Option 1: CLI Command (Recommended) Run this command in your terminal: ```bash claude mcp add --transport stdio pdfdancer-mcp -- npx -y @pdfdancer/pdfdancer-mcp ``` Verify installation with: `claude mcp list` #### Option 2: Manual Configuration Add the following to your Claude Code MCP settings configuration file: **Location**: `~/.config/claude/claude_desktop_config.json` (Linux/macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) ```json { "mcpServers": { "pdfdancer-mcp": { "command": "npx", "args": ["-y", "@pdfdancer/pdfdancer-mcp"] } } } ``` After adding the configuration, restart Claude Code to activate the MCP server. </details> <details> <summary><b>Install in Claude Desktop</b></summary> #### Option 1: Desktop Extensions (Easiest - Coming Soon) When available, navigate to Settings > Extensions > Browse extensions and search for "pdfdancer-mcp" for one-click installation. #### Option 2: Manual Configuration Add the following to your Claude Desktop MCP settings configuration file: **Location**: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) ```json { "mcpServers": { "pdfdancer-mcp": { "command": "npx", "args": ["-y", "@pdfdancer/pdfdancer-mcp"] } } } ``` After adding the configuration, restart Claude Desktop to activate the MCP server. </details> <details> <summary><b>Install in Windsurf</b></summary> #### Option 1: Using Settings UI (Recommended) 1. Open Windsurf Settings (click the Windsurf icon in bottom right, or Cmd+Shift+P / Ctrl+Shift+P and type "Open Windsurf Settings") 2. Navigate to Advanced Settings > Cascade > Model Context Protocol 3. Click the MCP servers button (hammer icon), then Configure 4. Add the server using the configuration interface #### Option 2: Manual Configuration Edit the `mcp_config.json` file and add: ```json { "mcpServers": { "pdfdancer-mcp": { "command": "npx", "args": ["-y", "@pdfdancer/pdfdancer-mcp"] } } } ``` </details> <details> <summary><b>Install in VS Code / VS Code Insiders</b></summary> When using MCP-compatible extensions in VS Code: 1. Install an MCP client extension (such as Cline, Roo Code, or similar) 2. Open the extension's settings 3. Add the MCP server configuration: ```json { "mcpServers": { "pdfdancer-mcp": { "command": "npx", "args": ["-y", "@pdfdancer/pdfdancer-mcp"] } } } ``` </details> <details> <summary><b>Install in Cline (VS Code Extension)</b></summary> #### Option 1: Using AI Assistant (Easiest) In the Cline chatbot, use this prompt: ``` install the MCP server named `@pdfdancer/pdfdancer-mcp` for Cline - ensure the mcp settings are updated ``` #### Option 2: Using MCP Servers UI 1. Click the MCP Servers icon in Cline's top navigation bar 2. Select "Configure MCP Servers" 3. Browse the MCP marketplace or add manually #### Option 3: Manual Configuration Edit `cline_mcp_settings.json`: ```json { "mcpServers": { "pdfdancer-mcp": { "command": "npx", "args": ["-y", "@pdfdancer/pdfdancer-mcp"] } } } ``` </details> <details> <summary><b>Install in Zed</b></summary> #### Option 1: Extension Method (Recommended - If Available) 1. Open Command Palette (search for "zed: extensions") 2. Check the extensions marketplace for "pdfdancer-mcp" 3. Install the extension if available - Zed will guide you through setup #### Option 2: Custom Server via UI 1. Open the Agent Panel's Settings view (or use the "agent: open settings" action) 2. In the Context Servers section, click "+ Add Context Server" 3. Enter the server name: `pdfdancer-mcp` 4. Click Add Server and configure: - **Command**: `npx` - **Args**: `-y @pdfdancer/pdfdancer-mcp` #### Option 3: Manual Configuration Open Zed settings (`~/.config/zed/settings.json`) and add: ```json { "assistant": { "version": "2", "mcp_servers": [ { "id": "pdfdancer-mcp", "command": "npx", "args": ["-y", "@pdfdancer/pdfdancer-mcp"] } ] } } ``` Verify by checking the indicator dot next to the server name in Agent Panel settings - green means it's running correctly. </details> <details> <summary><b>Install in Augment Code</b></summary> #### Option 1: Easy MCP (Recommended) Augment Code's "Easy MCP" feature provides one-click integrations for popular tools. Check the Easy MCP panel in settings for quick installation. #### Option 2: UI Configuration 1. Open Augment Code settings 2. Navigate to MCP Servers 3. Click "Add Server" 4. Enter: - **Name**: `pdfdancer-mcp` - **Command**: `npx` - **Args**: `-y @pdfdancer/pdfdancer-mcp` #### Option 3: Manual Configuration Edit your Augment Code configuration file: ```json { "augment.advanced": { "mcpServers": [{ "name": "pdfdancer-mcp", "command": "npx", "args": ["-y", "@pdfdancer/pdfdancer-mcp"] }] } } ``` </details> <details> <summary><b>Install in Roo Code</b></summary> #### Option 1: Using MCP Settings Panel (Recommended) 1. Click the Roo Code MCP icon 2. Click "Edit Global MCP" 3. Paste the configuration below inside the `mcpServers` object 4. Save the file #### Option 2: Manual Configuration Edit `mcp_settings.json` (Global) or `.roo/mcp.json` (Project-level): ```json { "mcpServers": { "pdfdancer-mcp": { "command": "npx", "args": ["-y", "@pdfdancer/pdfdancer-mcp"] } } } ``` **Note**: Global configuration applies across all workspaces, while project-level is specific to your project's root. </details> <details> <summary><b>Install in Gemini CLI</b></summary> Add to your Gemini CLI configuration: ```json { "mcpServers": { "pdfdancer-mcp": { "command": "npx", "args": ["-y", "@pdfdancer/pdfdancer-mcp"] } } } ``` </details> <details> <summary><b>Install in Qwen Coder</b></summary> Add to your Qwen Coder MCP settings: ```json { "mcpServers": { "pdfdancer-mcp": { "command": "npx", "args": ["-y", "@pdfdancer/pdfdancer-mcp"] } } } ``` </details> <details> <summary><b>Install in JetBrains AI Assistant</b></summary> **Requirements**: IntelliJ IDEA 2025.1+ or other JetBrains IDE with AI Assistant 251.26094.80.5+ #### Option 1: Import from Claude (Easiest) 1. Go to Settings | Tools | AI Assistant | Model Context Protocol (MCP) 2. Click "Import from Claude" 3. Select the pdfdancer-mcp server from your Claude Desktop configuration #### Option 2: Add via Settings UI 1. Open IDE settings (Ctrl+Alt+S or Cmd+,) 2. Navigate to Tools → AI Assistant → Model Context Protocol (MCP) 3. Click "Add Command" or use the Add option 4. Configure: - **Name**: `pdfdancer-mcp` - **Command**: `npx` - **Args**: `-y @pdfdancer/pdfdancer-mcp` #### Option 3: Manual Configuration Add to your MCP configuration: ```json { "mcpServers": { "pdfdancer-mcp": { "command": "npx", "args": ["-y", "@pdfdancer/pdfdancer-mcp"] } } } ``` **Note**: Version 2025.2+ includes built-in MCP server support for external clients. </details> <details> <summary><b>Install in Amazon Q Developer CLI</b></summary> Configure in your Amazon Q Developer CLI settings: ```json { "mcpServers": { "pdfdancer-mcp": { "command": "npx", "args": ["-y", "@pdfdancer/pdfdancer-mcp"] } } } ``` </details> <details> <summary><b>Install in Warp</b></summary> Add to Warp's AI configuration: ```json { "mcpServers": { "pdfdancer-mcp": { "command": "npx", "args": ["-y", "@pdfdancer/pdfdancer-mcp"] } } } ``` </details> <details> <summary><b>Install in GitHub Copilot CLI</b></summary> Configure in your GitHub Copilot CLI settings: ```json { "mcpServers": { "pdfdancer-mcp": { "command": "npx", "args": ["-y", "@pdfdancer/pdfdancer-mcp"] } } } ``` </details> <details> <summary><b>Install in BoltAI</b></summary> Add to BoltAI MCP configuration: ```json { "mcpServers": { "pdfdancer-mcp": { "command": "npx", "args": ["-y", "@pdfdancer/pdfdancer-mcp"] } } } ``` </details> <details> <summary><b>Install in Perplexity Desktop</b></summary> Configure in Perplexity Desktop settings: ```json { "mcpServers": { "pdfdancer-mcp": { "command": "npx", "args": ["-y", "@pdfdancer/pdfdancer-mcp"] } } } ``` </details> <details> <summary><b>Install in Docker</b></summary> Add to your Docker container configuration: ```dockerfile FROM node:18 RUN npx -y @pdfdancer/pdfdancer-mcp ``` Or use in docker-compose: ```yaml services: pdfdancer-mcp: image: node:18 command: npx -y @pdfdancer/pdfdancer-mcp ``` </details> <details> <summary><b>Other MCP-Compatible Clients</b></summary> For any other MCP-compatible client, use the following standard configuration: ```json { "mcpServers": { "pdfdancer-mcp": { "command": "npx", "args": ["-y", "@pdfdancer/pdfdancer-mcp"] } } } ``` Consult your client's documentation for the specific location of the MCP configuration file. </details> #### Custom Documentation Endpoint (Optional) If you're using a custom PDFDancer documentation endpoint, you can configure it via environment variable: ```json { "mcpServers": { "pdfdancer-mcp": { "command": "npx", "args": ["-y", "@pdfdancer/pdfdancer-mcp"], "env": { "PDFDANCER_DOCS_BASE_URL": "https://your-docs-endpoint.com" } } } } ``` ### Available Tools The MCP server provides the following tools for accessing PDFDancer documentation: - **`help`** – Display comprehensive overview of PDFDancer SDK capabilities with multi-language code samples (TypeScript, Python, Java) demonstrating common PDF manipulation tasks. - **`version`** – Get the current version of the pdfdancer-mcp server. - **`search-docs`** – Search the official PDFDancer SDK documentation by keyword. Returns matching documentation routes with titles, content snippets, and relevance scores (max 10 results). Use this to find information about PDFDancer features, APIs, and usage examples. - **`get-docs`** – Retrieve the full documentation content for a specific route. After finding relevant documentation with `search-docs`, use this tool to get the complete markdown content including code examples, detailed explanations, and API references. ### Typical Workflow 1. **Install the server** in your MCP-compatible client (Cursor, Claude Code, Windsurf, Zed, etc.). 2. **Open a codebase that uses PDFDancer** (or ask your assistant to add the SDK). 3. **Describe the behavior you want in code** – for example: "add a step that redacts email addresses in every inbound PDF", "add a function that moves this header up 20px", or "create a job that stamps a footer on all pages". 4. **Let the agent write and refactor the code** using the PDFDancer SDKs through this MCP server, then run tests or sample PDFs. 5. **Commit and ship your workflow** once the code and resulting PDFs behave as expected. ### Demo: Using PDFDancer MCP with Claude Code Once you've installed the PDFDancer MCP server, you can prompt Claude Code to build PDF applications. Here's a real terminal session: <img src="demo-screenshot.png" alt="PDFDancer MCP Demo Terminal Session" width="100%"> **What happened:** 1. User prompted: `create a typescript project which creates a pdf with the words "Hello World" on it. Use pdfdancer` 2. Claude Code searched the PDFDancer documentation using the MCP 3. Created a complete TypeScript project with proper setup 4. Built and ran the project 5. Generated `output.pdf` with "Hello World" text The PDFDancer MCP enables Claude Code to instantly provide accurate, up-to-date documentation and code examples without hallucinating APIs. --- ## For Developers ### Development ```bash npm install npm run dev # starts the server via tsx for quick iteration npm run build # emits ESM output to dist/ npm run lint # type-check without emitting files ``` ### Publishing to npm The package is configured to automatically build and lint before publishing: ```bash # Login to npm (first time only) npm login # Publish to npm (prepublishOnly script runs automatically) npm run publish:npm ``` Or use the standard npm publish command: ```bash npm publish ``` The `prepublishOnly` script ensures the package is linted and built before each publish. ### Local testing 1. Build the distributable files so the CLI matches the eventual npm artifact: ```bash npm run build ``` 2. Launch the stdio server exactly as `npx` would, but pointing to the local package directory: ```bash npx -y . ``` 3. Alternatively, run the compiled output directly with Node: ```bash node dist/index.js ``` 4. For the fastest inner loop while editing TypeScript, use: ```bash npm run dev ``` Any MCP-compatible client (Claude Desktop, MCP CLI, etc.) can now connect to the running process over stdio. ### Configuration Set `PDFDANCER_DOCS_BASE_URL` to point to your PDFDancer documentation service endpoint if different from the default. The server defaults to the official PDFDancer documentation service. Example: ```bash export PDFDANCER_DOCS_BASE_URL=https://your-docs-endpoint.com npx -y . # or npm run dev ```