apapyr-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,73 @@
+# aPapyr MCP Server
+
+Extract structured data from documents using AI agents. This MCP server lets Claude Code, Cursor, Windsurf, and any MCP-compatible AI assistant natively extract data from invoices, receipts, tax forms, bank statements, and contracts.
+
+## Quick Setup
+
+### 1. Get an API Key
+
+Sign up at [apapyr.com](https://apapyr.com/dashboard.html) (free tier: 50 pages/month).
+
+### 2. Add to Claude Code
+
+```bash
+claude mcp add apapyr -- npx @apapyr/mcp-server
+```
+
+Then set your API key:
+
+```bash
+export APAPYR_API_KEY=sk_live_your_key
+```
+
+### 3. Add to Cursor / VS Code
+
+Add to your MCP settings (`.cursor/mcp.json` or VS Code MCP config):
+
+```json
+{
+  "mcpServers": {
+    "apapyr": {
+      "command": "npx",
+      "args": ["@apapyr/mcp-server"],
+      "env": {
+        "APAPYR_API_KEY": "sk_live_your_key"
+      }
+    }
+  }
+}
+```
+
+## What You Can Do
+
+Once connected, just ask your AI assistant naturally:
+
+- *"Extract the data from invoice.pdf"*
+- *"Parse this receipt and give me the total"*
+- *"What fields can you extract from a W-2?"*
+- *"How many pages have I used this month?"*
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `extract_document` | Extract structured data from a PDF or image |
+| `get_extraction` | Get a previous extraction result by ID |
+| `list_extractions` | List recent extractions |
+| `get_usage` | Check current plan usage and limits |
+| `list_document_schemas` | See supported document types and fields |
+
+## Supported Documents
+
+- **Invoices** — vendor, total, tax, due date, line items
+- **Receipts** — merchant, total, tax, tip, payment method
+- **W-2 Tax Forms** — employer, wages, withholdings
+- **Bank Statements** — balances, transactions
+- **Contracts** — parties, dates, key terms
+
+## Links
+
+- [Website](https://apapyr.com)
+- [API Docs](https://apapyr.com/docs.html)
+- [Dashboard](https://apapyr.com/dashboard.html)
+- [Free Tool](https://apapyr.com/free-tool.html)

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "apapyr-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for aPapyr — Extract structured data from documents via AI agents",
+  "main": "src/index.js",
+  "bin": {
+    "apapyr-mcp": "src/index.js"
+  },
+  "keywords": ["mcp", "document-extraction", "invoice", "receipt", "ocr", "ai-agent", "claude", "cursor"],
+  "author": "aPapyr",
+  "license": "MIT",
+  "homepage": "https://apapyr.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/apapyr/mcp-server"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": ["src/"]
+}

package/src/index.js

@@ -0,0 +1,335 @@
+#!/usr/bin/env node
+
+/**
+ * aPapyr MCP Server
+ *
+ * Lets AI agents (Claude Code, Cursor, Copilot, etc.) extract structured data
+ * from documents via the aPapyr API.
+ *
+ * Setup:
+ *   1. Get an API key at https://apapyr.com/dashboard.html
+ *   2. Add to your MCP config:
+ *      {
+ *        "mcpServers": {
+ *          "apapyr": {
+ *            "command": "npx",
+ *            "args": ["@apapyr/mcp-server"],
+ *            "env": { "APAPYR_API_KEY": "sk_live_..." }
+ *          }
+ *        }
+ *      }
+ */
+
+const { Server } = require("@modelcontextprotocol/sdk/server/index.js");
+const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
+const {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} = require("@modelcontextprotocol/sdk/types.js");
+const fs = require("fs");
+const path = require("path");
+
+const API_URL = process.env.APAPYR_API_URL || "https://api.apapyr.com";
+const API_KEY = process.env.APAPYR_API_KEY || "";
+
+// ─── API Helper ──────────────────────────────────────────────────────────────
+
+async function apiRequest(method, endpoint, body, isFormData) {
+  const headers = {
+    Authorization: `Bearer ${API_KEY}`,
+  };
+
+  if (!isFormData) {
+    headers["Content-Type"] = "application/json";
+  }
+
+  const response = await fetch(`${API_URL}${endpoint}`, {
+    method,
+    headers,
+    body: isFormData ? body : body ? JSON.stringify(body) : undefined,
+  });
+
+  const data = await response.json();
+  if (!response.ok) {
+    throw new Error(data.detail || `API error: ${response.status}`);
+  }
+  return data;
+}
+
+async function extractDocument(filePath, documentType) {
+  const resolvedPath = path.resolve(filePath);
+
+  if (!fs.existsSync(resolvedPath)) {
+    throw new Error(`File not found: ${resolvedPath}`);
+  }
+
+  const fileBuffer = fs.readFileSync(resolvedPath);
+  const fileName = path.basename(resolvedPath);
+
+  // Build multipart form data
+  const boundary = "----aPapyrMCP" + Math.random().toString(36).slice(2);
+  const parts = [];
+
+  // File part
+  parts.push(
+    `--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="${fileName}"\r\nContent-Type: application/octet-stream\r\n\r\n`
+  );
+  parts.push(fileBuffer);
+  parts.push("\r\n");
+
+  // document_type part
+  parts.push(
+    `--${boundary}\r\nContent-Disposition: form-data; name="document_type"\r\n\r\n${documentType}\r\n`
+  );
+
+  parts.push(`--${boundary}--\r\n`);
+
+  const body = Buffer.concat(
+    parts.map((p) => (typeof p === "string" ? Buffer.from(p) : p))
+  );
+
+  const response = await fetch(`${API_URL}/v1/extract`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${API_KEY}`,
+      "Content-Type": `multipart/form-data; boundary=${boundary}`,
+    },
+    body,
+  });
+
+  const data = await response.json();
+  if (!response.ok) {
+    throw new Error(data.detail || `Extraction failed: ${response.status}`);
+  }
+  return data;
+}
+
+// ─── MCP Server ──────────────────────────────────────────────────────────────
+
+const server = new Server(
+  {
+    name: "apapyr",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "extract_document",
+        description:
+          "Extract structured data from a document (invoice, receipt, W-2, bank statement, or contract). Reads a PDF or image file and returns clean JSON with field values and confidence scores.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            file_path: {
+              type: "string",
+              description:
+                "Absolute or relative path to the document file (PDF, PNG, JPG, or WEBP)",
+            },
+            document_type: {
+              type: "string",
+              enum: [
+                "auto",
+                "invoice",
+                "receipt",
+                "w2",
+                "bank_statement",
+                "contract",
+              ],
+              description:
+                "Type of document. Use 'auto' to detect automatically. Default: auto",
+              default: "auto",
+            },
+          },
+          required: ["file_path"],
+        },
+      },
+      {
+        name: "get_extraction",
+        description:
+          "Retrieve the result of a previous document extraction by its ID.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            extraction_id: {
+              type: "string",
+              description: "The extraction ID returned from extract_document",
+            },
+          },
+          required: ["extraction_id"],
+        },
+      },
+      {
+        name: "list_extractions",
+        description:
+          "List recent document extractions with their status and metadata.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            limit: {
+              type: "number",
+              description: "Number of results to return (max 100). Default: 10",
+              default: 10,
+            },
+          },
+        },
+      },
+      {
+        name: "get_usage",
+        description:
+          "Check current API usage — pages used, remaining quota, and plan details.",
+        inputSchema: {
+          type: "object",
+          properties: {},
+        },
+      },
+      {
+        name: "list_document_schemas",
+        description:
+          "List all supported document types and the fields that will be extracted from each.",
+        inputSchema: {
+          type: "object",
+          properties: {},
+        },
+      },
+    ],
+  };
+});
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    if (!API_KEY) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: "Error: APAPYR_API_KEY environment variable is not set. Get your API key at https://apapyr.com/dashboard.html",
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    let result;
+
+    switch (name) {
+      case "extract_document": {
+        const filePath = args.file_path;
+        const docType = args.document_type || "auto";
+        result = await extractDocument(filePath, docType);
+
+        // Format a nice summary
+        const summary = [];
+        summary.push(`Document Type: ${result.document_type || "auto"}`);
+        summary.push(
+          `Confidence: ${result.confidence ? (result.confidence * 100).toFixed(0) + "%" : "N/A"}`
+        );
+        summary.push(
+          `Processing Time: ${result.processing_time_ms ? result.processing_time_ms + "ms" : "N/A"}`
+        );
+        if (result.cached) summary.push("(cached result)");
+        if (result.validation_warnings && result.validation_warnings.length > 0) {
+          summary.push(`Warnings: ${result.validation_warnings.join(", ")}`);
+        }
+        summary.push("");
+        summary.push("Extracted Data:");
+        summary.push(JSON.stringify(result.data, null, 2));
+
+        return {
+          content: [{ type: "text", text: summary.join("\n") }],
+        };
+      }
+
+      case "get_extraction": {
+        result = await apiRequest("GET", `/v1/extract/${args.extraction_id}`);
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(result, null, 2) },
+          ],
+        };
+      }
+
+      case "list_extractions": {
+        const limit = args.limit || 10;
+        result = await apiRequest(
+          "GET",
+          `/v1/extractions?limit=${limit}`
+        );
+        const lines = result.extractions.map(
+          (e) =>
+            `${e.id} | ${e.file_name || "—"} | ${e.document_type || "auto"} | ${e.confidence ? (e.confidence * 100).toFixed(0) + "%" : "—"} | ${e.created_at}`
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                lines.length > 0
+                  ? `ID | File | Type | Confidence | Date\n${"-".repeat(60)}\n${lines.join("\n")}`
+                  : "No extractions found.",
+            },
+          ],
+        };
+      }
+
+      case "get_usage": {
+        result = await apiRequest("GET", "/v1/usage");
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Plan: ${result.plan}\nPages Used: ${result.used} / ${result.limit}\nRemaining: ${result.remaining}\nOverage Price: ${result.overage_price_per_page}/page`,
+            },
+          ],
+        };
+      }
+
+      case "list_document_schemas": {
+        result = await apiRequest("GET", "/v1/schemas");
+        const schemaText = Object.entries(result.schemas)
+          .map(
+            ([type, schema]) =>
+              `${type}:\n  Fields: ${schema.fields.join(", ")}${schema.has_line_items ? `\n  Line Items: ${schema.line_item_fields.join(", ")}` : ""}`
+          )
+          .join("\n\n");
+        return {
+          content: [{ type: "text", text: schemaText }],
+        };
+      }
+
+      default:
+        return {
+          content: [{ type: "text", text: `Unknown tool: ${name}` }],
+          isError: true,
+        };
+    }
+  } catch (error) {
+    return {
+      content: [{ type: "text", text: `Error: ${error.message}` }],
+      isError: true,
+    };
+  }
+});
+
+// ─── Start ───────────────────────────────────────────────────────────────────
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((error) => {
+  console.error("MCP server error:", error);
+  process.exit(1);
+});