{
  "markdown": "# 📦 PDF Kit MCP Server\n\n<!-- MCP name format for registry validation -->\n<!-- mcp-name: com.hellobasestation/pdfkit -->\n\nAn AI-powered Model Context Protocol (MCP) server that enables Claude and other AI assistants to work with PDFs using natural language instructions. Fill forms, merge documents, extract data, and split PDFs - all through simple conversation.\n\n## ✨ Overview\n\nTransform tedious PDF tasks into simple conversations. Just tell your AI assistant what you need, and let PDF Kit handle the rest.\n\n**Current Features:**\n- 📝 **Form Filling**: Automatically fill PDF forms with natural language instructions\n\n**Coming Soon:**\n- 🔗 **PDF Merging**: Combine multiple PDFs into one document\n- 📊 **Data Extraction**: Extract structured data from PDFs\n- ✂️ **PDF Splitting**: Split PDFs by page ranges or criteria\n\n**Perfect for:**\n- 📋 Tax forms and government documents\n- 🏢 Business applications and contracts\n- 🏥 Medical intake forms\n- 📄 Document management and organization\n- 📊 Data processing workflows\n\n## 🚀 Features\n\n- **Natural Language Instructions**: Describe tasks in plain English\n- **Intelligent Processing**: AI automatically understands and executes PDF operations\n- **Multiple Transport Options**: stdio (Claude Desktop) or HTTP (remote/web)\n- **Secure API Integration**: Built on BaseStation's proven PDF processing API\n- **Real-time Job Status**: Track processing progress with job IDs\n- **Extensible Architecture**: Easy to add new PDF tools and capabilities\n- **Error Handling**: Clear error messages and validation\n\n## 📦 Installation\n\n### Option 1: Via Claude Desktop (Recommended)\n\n1. Install the MCP server via Claude Desktop settings\n2. Add to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"pdfkit\": {\n      \"command\": \"npx\",\n      \"args\": [\"pdfkit-mcp\"],\n      \"env\": {\n        \"BASESTATION_API_URL\": \"https://app.hellobasestation.com\",\n        \"BASESTATION_API_KEY\": \"your-api-key-here\"\n      }\n    }\n  }\n}\n```\n\n### Option 2: Via npm (Global Install)\n\n```bash\nnpm install -g pdfkit-mcp\n```\n\nThen configure in your MCP client.\n\n### Option 3: From Source\n\n```bash\ngit clone https://github.com/Base-Station-Inc/pdfkit-mcp.git\ncd pdfkit-mcp\nnpm install\n```\n\n**Requirements:**\n- Node.js v20 or higher\n- BaseStation API key ([get one here](https://hellobasestation.com))\n\n## ⚙️ Configuration\n\nSet these environment variables in your MCP client or hosting environment.\n\n- **BASESTATION_API_KEY** (required)\n  - API key for BaseStation requests.\n- **BASESTATION_API_URL** (optional)\n  - Default: `https://app.hellobasestation.com`\n- **MAX_PDF_MB** (optional)\n  - Max allowed decoded PDF size in MB. Default: `15`.\n- **REQUEST_TIMEOUT_MS** (optional)\n  - Timeout for outbound API requests. Default: `15000`.\n- **PORT** (optional, HTTP mode only)\n  - HTTP server port. Default: `4000`.\n\nExample (Claude Desktop, stdio via npx):\n\n```json\n{\n  \"mcpServers\": {\n    \"pdfkit\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"pdfkit-mcp\"],\n      \"env\": {\n        \"BASESTATION_API_KEY\": \"<your-api-key>\",\n        \"BASESTATION_API_URL\": \"https://app.hellobasestation.com\",\n        \"MAX_PDF_MB\": \"15\",\n        \"REQUEST_TIMEOUT_MS\": \"15000\"\n      }\n    }\n  }\n}\n```\n\nExample (HTTP mode, local):\n\n```bash\nexport BASESTATION_API_KEY=your_api_key\nexport PORT=4000\nnpm run start:http\n```\n\n## 🎯 Quick Start\n\n### With Claude Desktop\n\nOnce installed, simply ask Claude:\n\n> \"Fill out this PDF form with the following information: Name: John Doe, Email: john@example.com...\"\n>\n> *(Coming soon: \"Merge these three PDF files\" or \"Extract all the email addresses from this PDF\")*\n\n### As HTTP Server\n\nStart the server:\n\n```bash\nnode index.js\n# Server runs on http://localhost:4000\n```\n\nExpose via ngrok:\n\n```bash\nngrok http 4000\n```\n\nThe server will output:\n```\nPDF Kit MCP server running on http://localhost:4000\nMCP endpoint: http://localhost:4000/mcp\nHealth check: http://localhost:4000/health\n\nRun 'ngrok http 4000' to expose this server\n```\n\n### Exposing with ngrok\n\nTo make your MCP server accessible from external applications:\n\n1. Start the MCP server:\n```bash\nnode index.js\n```\n\n2. In a separate terminal, run ngrok:\n```bash\nngrok http 4000\n```\n\n3. ngrok will provide a public URL (e.g., `https://abc123.ngrok.io`)\n\n4. Use the MCP endpoint at:\n```\nhttps://abc123.ngrok.io/mcp\n```\n\n## Endpoints\n\n- **`/mcp`** - Main MCP endpoint for protocol communication\n- **`/health`** - Health check endpoint (returns server status)\n\n### Health Check Example\n\n```bash\ncurl http://localhost:4000/health\n```\n\nResponse:\n```json\n{\n  \"status\": \"ok\",\n  \"name\": \"pdfkit-mcp\",\n  \"version\": \"1.0.7\"\n}\n```\n\n## Available Tools\n\n### `basestation.create_autofill_job`\n\nCreates a BaseStation autofill job for PDF form filling.\n\n**Parameters:**\n- `instructions` (string, required): Natural language instructions for how to fill the form\n- `formFile` (string, required): Base64-encoded PDF file to fill\n- `callbackUrl` (string, optional): Optional callback URL for job completion notification\n\n**Returns:**\n- `job_id`: The BaseStation job ID\n- `upload_page_url`: URL to the upload page for the job\n- `instructions_summary`: Parsed summary of the instructions\n\n**Example Usage (from MCP client):**\n```javascript\n{\n  \"name\": \"basestation.create_autofill_job\",\n  \"arguments\": {\n    \"instructions\": \"Fill out the form with: Name: John Doe, Email: john@example.com\",\n    \"formFile\": \"<base64-encoded-pdf>\",\n    \"callbackUrl\": \"https://myapp.com/webhook\"\n  }\n}\n```\n\n## Architecture\n\n```\n┌─────────────────┐\n│   MCP Client    │\n│ (e.g., Claude)  │\n└────────┬────────┘\n         │\n         │ HTTP/MCP Protocol\n         │\n         ▼\n┌─────────────────┐\n│  MCP Server     │\n│  (index.js)     │\n└────────┬────────┘\n         │\n         │ Imports & Executes\n         │\n         ▼\n┌─────────────────┐        ┌──────────────────┐\n│  Tool Handler   │───────▶│  BaseStation API │\n│(basestation.js) │        │  (External)      │\n└─────────────────┘        └──────────────────┘\n```\n\n## File Structure\n\n```\nDoc-Base-Station-MCP/\n├── index.js              # Main MCP server (HTTP transport)\n├── tools/\n│   └── basestation.js    # BaseStation tool definition and handler\n├── package.json          # Node.js dependencies\n├── README.md            # This file\n└── docs/                # Internal guides\n    ├── LAUNCH_CHECKLIST.md\n    ├── PUBLISHING.md\n    └── ASSETS_NEEDED.md\n```\n\n## Dependencies\n\n- `@modelcontextprotocol/sdk` - Official MCP TypeScript SDK\n- `express` - Web framework for HTTP server (v5)\n- `node-fetch` - HTTP client for API calls\n\n## Development\n\n### Project Configuration\n\nThe project uses ES modules. Key configuration in `package.json`:\n\n```json\n{\n  \"type\": \"module\",\n  \"dependencies\": {\n    \"@modelcontextprotocol/sdk\": \"^1.20.1\",\n    \"node-fetch\": \"^3.3.2\",\n    \"express\": \"^5.1.0\"\n  }\n}\n```\n\n### Adding New Tools\n\nTo add new tools to the MCP server:\n\n1. Create a new tool file in `tools/` directory\n2. Export a `TOOL_DEFINITION` object with the tool schema\n3. Export a handler function that implements the tool logic\n4. Import and register in `index.js`\n\nExample structure:\n```javascript\n// tools/mytool.js\nexport const TOOL_DEFINITION = {\n  name: \"my.tool\",\n  description: \"Description of what the tool does\",\n  inputSchema: {\n    type: \"object\",\n    properties: {\n      param1: { type: \"string\", description: \"Parameter description\" }\n    },\n    required: [\"param1\"]\n  }\n};\n\nexport async function handleMyTool(args) {\n  // Implementation\n  return {\n    content: [{ type: \"text\", text: \"Result\" }]\n  };\n}\n```\n\n## Troubleshooting\n\n### Port Already in Use\n\nChange the port using the `PORT` environment variable:\n```bash\nPORT=8080 node index.js\n```\n\n### Connection Issues with ngrok\n\n- Ensure the MCP server is running before starting ngrok\n- Check that ngrok is pointing to the correct port\n- Verify firewall settings allow incoming connections\n\n## License\n\nMIT\n\n## Resources\n\n- [Model Context Protocol Documentation](https://modelcontextprotocol.io)\n- [BaseStation API Documentation](https://hellobasestation.com)\n- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)",
  "bytes": 8103,
  "sha": "9df7652bd13fb0cc2296cac743551cd34b3c37c825d3ae007e8d2c497413b410",
  "repo_slug": "base-station-inc/pdfkit-mcp",
  "fonte": "npm",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_hellobasestation_pdfkit_86c6dff8/readme"
}