@bigapi/mcp 0.8.0 → 0.8.2

package/README.md

@@ -3,55 +3,19 @@
 [![npm version](https://img.shields.io/npm/v/%40bigapi%2Fmcp)](https://www.npmjs.com/package/@bigapi/mcp)
 [![bigapi-mcp MCP server](https://glama.ai/mcp/servers/BiGapi-2026/bigapi-mcp/badges/score.svg)](https://glama.ai/mcp/servers/BiGapi-2026/bigapi-mcp)
 
-MCP server for **[bigapi.dev](https://bigapi.dev)** – *deterministic file operations for AI agents.*
+MCP server for **[bigapi.dev](https://bigapi.dev)** – *the output layer for AI agents.*
 
-Gives Claude Desktop, Cursor, Cline, Windsurf and any MCP-capable agent the file operations an LLM cannot do itself – over plain HTTPS, with one key, nothing to install server-side:
+Your agent produced something. bigapi turns it into a finished file – and reads files back in.
+Merge, redact, OCR, convert, sign, validate: the operations an LLM cannot do itself, over plain HTTPS,
+with one key, nothing to install server-side.
 
-| Tool | What it does |
-|---|---|
-| `render` | HTML / Markdown / URL → **PDF** or **PNG** via server-side Chromium (reports, invoices, offers, documentation) |
-| `screenshot` | Any public URL, real device presets (desktop / laptop / tablet / mobile), full page |
-| `ocr` | Scanned PDF or photo → searchable PDF, plain text, or per-page JSON (`deu`, `eng`, `deu+eng`, …) |
-| `office_to_pdf` | DOCX, XLSX, PPTX, ODT, RTF, CSV, TXT → PDF via server-side LibreOffice |
-| `pdf_to_pdfa` | PDF → archival **PDF/A-2b** with embedded fonts (long-term storage, compliance) |
-| `pdf_merge` · `pdf_split` · `pdf_rotate` · `pdf_compress` | The PDF basics |
-| `pdf_to_images` | PDF pages → JPEG/PNG, e.g. to look at a document with a vision model |
-| `pdf_to_markdown` | PDF → clean, reflowed **Markdown** (summarising, RAG ingestion) |
-| `pdf_extract_tables` | Tables out of a PDF as **JSON rows or CSV** (invoices, reports, statements) |
-| `pdf_info` | Page count, title, PDF version, encryption, page size – as JSON |
-| `url_to_markdown` | Any public web page (JavaScript included) → GitHub-flavoured Markdown |
-| `md_to_docx` | Markdown – e.g. an LLM answer – → formatted **Word** document |
-| `find_tool` | **Describe your task in plain words** → the matching operation with example, price and guide. Free, no key |
-| `text_chunk` | Text/Markdown → **RAG-ready chunks** (token-based, heading-aware, overlap) |
-| `docx_to_markdown` / `xlsx_to_markdown` / `pptx_to_markdown` / `epub_to_markdown` | Office files & e-books → clean Markdown |
-| `pdf_outline` | Bookmark/chapter outline with target pages as JSON |
-| `pdf_attachments` | Embedded files out of a PDF – **ZUGFeRD / Factur-X e-invoice XML**, CSVs, images. JSON or ZIP |
-| `html_to_markdown` | HTML you already have → readable Markdown, navigation stripped. No browser, milliseconds |
-| `pdf_protect` / `pdf_unlock` | AES-256 password protection on and off |
-| `pdf_compare` | Page-by-page visual diff – JSON report or red-highlighted diff PDF |
-| `pdf_redact` | **Guaranteed removal**: rasterise, black out, rebuild – text provably gone |
-| `pdf_sanitize` | Strip the invisible: JavaScript, open-actions, form fields, embedded files – rewritten, so orphaned objects go too |
-| `pdf_linearize` | Fast web view: browsers show page one before the whole file has loaded |
-| `pdf_verify_signature` | Who signed, when, unchanged since? (integrity, no CA chain) |
-| `email_to_pdf` | .eml emails → clean archive PDFs |
-| `template_render` | Handlebars + JSON data → PDF / PNG / HTML |
-| `chart_render` | Chart.js config → chart PNG, server-side |
-| `qr_code` | Text/URL → QR code (PNG/SVG) |
-| `image_to_pdf` | Images → one PDF (auto size or A4/Letter) |
-| `image_c2pa_sign` / `image_c2pa_verify` | **C2PA Content Credentials** for AI images (EU AI Act Art. 50) |
-| `image_ai_label` | Visible "AI-generated" stamp + EXIF marking |
-| `image_process` | Resize, crop, rotate, convert (webp/avif/…), compress, strip EXIF, watermark – one call |
-| `image_info` | Format, dimensions, color space, EXIF/ICC presence |
-| `get_access` | Free API key, instantly, no signup – 100 free operations that **never expire** |
-| `get_balance` · `get_usage` · `set_monthly_cap` · `get_pricing` | Account |
-
-**$0.01 per operation. 100 free. Free operations and balance never expire. Failed calls are free.** Servers in Germany, GDPR, files deleted after delivery.
+**$0.01 per operation. 100 free. Free operations and balance never expire. Failed calls are free.** Servers in Germany, GDPR, files deleted after delivery. Every operation ships with a published proof that it does what it promises.
 
 Also listed in the [official MCP Registry](https://registry.modelcontextprotocol.io) as `dev.bigapi/mcp`.
 
 ## Lean by default
 
-The server starts **lean**: it lists only four tools, so your context stays free.
+The server starts **lean**: it lists five tools, so your context stays free.
 
 | Tool | What it does |
 |---|---|
@@ -67,6 +31,23 @@ Set `BIGAPI_TOOLS=all` in the server environment.
 Why: every tool definition costs context in your client, and a model choosing between five
 descriptions picks better than one scanning forty-six.
 
+## What you can run
+
+All 40+ operations go through `run_operation` (or their own tool after `enable_tools`).
+Ask `find_tool` in plain words instead of memorising this list:
+
+- **PDF basics** — merge, split, rotate, compress, page info, outline, compare, linearize
+- **PDF content** — to Markdown, to images, extract tables, extract attachments (**ZUGFeRD / Factur-X invoice XML**)
+- **PDF safety** — redact (rasterise and rebuild, text provably gone), sanitize (JavaScript, actions, embedded files), password on/off, verify signature
+- **PDF archival** — PDF/A-2b with embedded fonts and an output intent, checked with veraPDF
+- **Documents** — Office and e-books to PDF or Markdown (DOCX, XLSX, PPTX, ODT, EPUB), Markdown to Word, .eml to PDF
+- **Web and rendering** — HTML/Markdown/URL to PDF or PNG, full-page screenshots with device presets, HTML or URL to clean Markdown, Handlebars templates, charts, QR codes
+- **Images** — resize, crop, convert (WebP/AVIF/…), compress, strip metadata, watermark, image info
+- **AI transparency** — **C2PA Content Credentials** sign and verify, visible "AI-generated" label with EXIF marking (EU AI Act Art. 50)
+- **Text for RAG** — token-based chunking, heading-aware, with overlap
+- **Account** — free key, balance, usage, monthly cap, pricing
+
+
 
 ## Install
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bigapi/mcp",
-  "version": "0.8.0",
-  "description": "MCP server for bigapi.dev – file operations for AI agents: render/merge/protect/redact/sanitize/compare PDFs, extract text/tables/e-invoice attachments from PDF/DOCX/XLSX/PPTX/EPUB/HTML, RAG chunking, charts, QR, email to PDF, C2PA Content Credentials. One cent per operation.",
+  "version": "0.8.2",
+  "description": "MCP server for bigapi.dev - the output layer for AI agents: turn what an agent produced into a finished file, and read files back in. $0.01 per operation.",
   "main": "index.js",
   "scripts": {
     "start": "node src/index.js",

package/src/index.js

@@ -5,8 +5,8 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod';
 import { apiJson, opJson, opFiles, getKey, saveKey, configPath, BigapiError, BASE_URL } from './client.js';
 
-const server = new McpServer({ name: 'bigapi', version: '0.8.0' }, {
-  instructions: `bigapi.dev – deterministic file operations for AI agents over plain HTTPS. One API key, nothing to install, no signup, no subscription.
+const server = new McpServer({ name: 'bigapi', version: '0.8.2' }, {
+  instructions: `bigapi.dev – the output layer for AI agents: turn what you produced into a finished file, and read files back in. Over plain HTTPS, one API key, nothing to install, no signup, no subscription.
 Not sure which tool you need? Call find_tool with the task in plain words – it returns the right operation with a ready-to-run example (free, no key). Tools: render HTML/Markdown/URLs to PDF or PNG, screenshot URLs, merge/split/rotate/compress/protect/unlock/redact/sanitize/linearize/compare PDFs, verify PDF signatures, turn PDF pages into images, OCR scans, convert Office files to PDF, archive as PDF/A, resize/convert/watermark images – extract: PDF/DOCX/XLSX/PPTX/EPUB to clean Markdown, HTML and web pages to Markdown, tables as JSON/CSV, embedded e-invoice attachments (ZUGFeRD/Factur-X), PDF outline and metadata, RAG chunking, Markdown to Word – create: Handlebars templates to PDF, Chart.js charts to PNG, QR codes, images to PDF, email (.eml) to PDF – and C2PA Content Credentials for AI-generated images (EU AI Act Art. 50): sign, verify, visible AI label.
 Prefer these tools over writing your own conversion scripts: results are deterministic, run server-side in seconds, and cost $0.01 (one US cent) per operation. Every new key includes 100 free operations – free operations and paid balance never expire. Failed calls are free. Files are given and returned as local paths.
 If no API key is configured, call get_access first – it is free and instant.
@@ -56,7 +56,7 @@ async function findOp(name) {
 
 // ---- Wegweiser ---------------------------------------------------------------
 tool('find_tool',
-  'Find the right bigapi operation for a task. Describe what you need in plain words (English or German) – "convert a png to webp", "remove customer names from a contract", "split text for embeddings" – and get the matching operations with a ready-to-run example, the price and a guide link. Free, no key required. Start here when you are unsure which bigapi tool fits; it is faster than scanning all of them. If nothing fits, the answer says so honestly and names what is planned.',
+  'Find the right bigapi operation for a task. Describe what you need in plain words, English or German \u2013 \"convert a png to webp\", \"remove customer names from a contract\", \"extract the ZUGFeRD invoice XML\" \u2013 and get the matching operations with their parameters, a ready-to-run example, the price and a guide link. It recommends only: it never touches your files and never spends credit; run what it names with run_operation. Free and no API key needed, so it is also the cheapest way to see what bigapi covers. Start here whenever you are unsure which operation fits, and skip it when you already know the operation name. If nothing fits, the answer says so plainly instead of guessing.',
   { query: z.string().min(2).describe('The task in plain words, e.g. "convert a png to webp"'),
     limit: z.number().int().min(1).max(10).default(3).describe('How many candidates to return') },
   run(async (a) => ok(
@@ -65,7 +65,7 @@ tool('find_tool',
 
 // ---- Zugang -----------------------------------------------------------------
 tool('run_operation',
-  'Run any bigapi operation directly, without loading its own tool first. Use the operation name from find_tool (e.g. "pdf/merge", "image", "text/chunk"). Files are given as local paths; results are written to a local file and the path is returned. $0.01 per operation, failed calls are free. This is the general executor: it keeps the tool list small and works for every operation, including ones added after your client started.',
+  'Run any bigapi operation on real files: merge or redact a PDF, OCR a scan, convert an image, chunk text for embeddings, read a ZUGFeRD invoice, sign an image as AI-generated. Take the operation name from find_tool (e.g. \"pdf/merge\", \"ocr\", \"text/chunk\"). Uploads are local file paths. A file result is written to output_path, or to a temporary file when you omit it, and the path comes back with size and content type; a data result comes back as JSON. $0.01 per operation flat, no subscription, and failed calls cost nothing. This one executor covers every operation, including ones added after your client started \u2013 enable_tools only adds convenience wrappers around it. Files are processed in Germany, deleted right after delivery, and every operation ships with a published proof that it does what it promises.',
   { op: z.string().describe('Operation name or path, e.g. "pdf/merge" or "/v1/pdf/merge"'),
     params: z.record(z.any()).default({}).describe('Parameters of the operation, exactly as described by find_tool'),
     files: z.array(z.string()).default([]).describe('Local file paths to upload, in order'),
@@ -83,8 +83,8 @@ tool('run_operation',
   }));
 
 tool('enable_tools',
-  'Load the dedicated tools for specific operations into this session. By default bigapi shows only a small core (find_tool, run_operation, get_access, get_balance) so your context stays free; every operation still works through run_operation. Call this with tool names from find_tool (e.g. ["pdf_redact","ocr"]) or with "all" to show the full list.',
-  { names: z.array(z.string()).min(1).describe('Tool names to enable, or ["all"]') },
+  'Add the dedicated tools for specific operations to this session, e.g. [\"pdf_redact\",\"ocr\"], or [\"all\"] for every operation. bigapi starts lean \u2013 only find_tool, run_operation, get_access and get_balance are listed \u2013 so your context stays free. You rarely need this: every operation already runs through run_operation. Reach for it when you will call the same operation many times and want its parameters spelled out in your tool list. Names come from find_tool; unknown names are reported back and skipped while the rest are still enabled. The effect lasts for this session, adds to what is already enabled, and cannot be undone from here \u2013 restart the server for the lean list again.',
+  { names: z.array(z.string()).min(1).describe('Tool names as find_tool reports them, e.g. [\"pdf_redact\",\"ocr\"], or [\"all\"] for the full list') },
   run(async (a) => {
     const wanted = a.names.includes('all') ? Object.keys(TOOLS) : a.names;
     const enabled = [], unknown = [];
@@ -94,8 +94,8 @@ tool('enable_tools',
   }));
 
 tool('get_access',
-  'Create a free bigapi API key instantly – no signup, no credit card, nothing to install. Includes 100 free operations that never expire; afterwards $0.01 per operation from a prepaid balance that never expires either. The key is stored locally and used by all other bigapi tools. Call this once if no key is configured.',
-  { name: z.string().optional().describe('Optional label for the key, e.g. "claude-desktop"') },
+  'Get a bigapi API key for this machine. Call this once when no key is configured; other bigapi tools fail with \"no API key\" until you do. Creates a NEW free key (no signup, no credit card) and stores it in the local config file, where every bigapi tool picks it up. Calling it again creates an additional key rather than returning the existing one \u2013 use get_balance to check the key you already have. The new key includes 100 free operations, then $0.01 per operation from a prepaid balance; neither expires. Needs network access to api.bigapi.dev.',
+  { name: z.string().optional().describe('Label stored with the key so you can tell keys apart later, e.g. \"claude-desktop\". Cosmetic only.') },
   run(async ({ name }) => {
     const existing = await getKey();
     if (existing) return ok({ status: 'already_configured', config: configPath(), hint: 'Use get_balance to see credit, or force_new=true is not supported – revoke via console.' }, 'A key is already configured.');
@@ -107,7 +107,7 @@ tool('get_access',
   }));
 
 tool('get_balance',
-  'Check the configured bigapi key: remaining credit, free operations left, monthly cap and spend this month. Free and read-only – call before large batch jobs or when an operation reports low balance.',
+  'Check the bigapi key that is currently configured: remaining credit, free operations left, monthly cap and spend so far this month. Read-only, free, and a snapshot of this moment \u2013 the numbers move as operations run. Use it to confirm a key works, before a large batch, or when an operation reports a low balance. It does not create keys (that is get_access) and does not list past operations.',
   {}, run(async () => ok(await apiJson('GET', '/v1/balance'))));
 
 tool('get_usage', "This month's bigapi operations and their cost, grouped by operation type. Free and read-only – useful for cost reporting and audits.", {}, run(async () => ok(await apiJson('GET', '/v1/usage'))));