> ## Documentation Index
> Fetch the complete documentation index at: https://docs.penquify.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect penquify to Claude Desktop, Cursor, or Windsurf via MCP.

## Overview

Penquify ships with a built-in MCP (Model Context Protocol) server that exposes 5 tools for document and photo generation. Use it with Claude Desktop, Cursor, Windsurf, or any MCP-compatible client.

## Setup

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "penquify": {
      "command": "python3",
      "args": ["-m", "penquify.mcp"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key",
        "PENQUIFY_OUTPUT": "~/penquify-output"
      }
    }
  }
}
```

### Cursor / Windsurf

Add to your `.cursor/mcp.json` or equivalent:

```json theme={null}
{
  "mcpServers": {
    "penquify": {
      "command": "python3",
      "args": ["-m", "penquify.mcp"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key"
      }
    }
  }
}
```

## Available Tools

### penquify\_generate\_document

Generate a logistics document (PDF + PNG) from structured data.

**Parameters:**

| Name            | Type     | Required | Description                                                                  |
| --------------- | -------- | -------- | ---------------------------------------------------------------------------- |
| `doc_type`      | `string` | No       | Template: `guia_despacho`, `factura_sii`, `purchase_order`, `bill_of_lading` |
| `doc_number`    | `string` | Yes      | Document number                                                              |
| `date`          | `string` | Yes      | Date (DD/MM/YYYY)                                                            |
| `emitter_name`  | `string` | Yes      | Emitter company name                                                         |
| `receiver_name` | `string` | No       | Receiver company name                                                        |
| `oc_number`     | `string` | No       | Purchase order reference                                                     |
| `items`         | `array`  | Yes      | Items: `[{description, qty, unit, unit_price?}]`                             |
| `observations`  | `string` | No       | Handwritten notes                                                            |

**Returns:** File paths (html, png, pdf).

### penquify\_generate\_photos

Generate realistic smartphone photos of a document image.

**Parameters:**

| Name              | Type       | Required | Description                                             |
| ----------------- | ---------- | -------- | ------------------------------------------------------- |
| `image_path`      | `string`   | Yes      | Path to document PNG/PDF                                |
| `presets`         | `string[]` | No       | Preset names (default: `full_picture`, `folded_skewed`) |
| `doc_description` | `string`   | No       | Key fields to preserve                                  |

**Returns:** List of `{name, path, ok}` results.

### penquify\_generate\_dataset

Full pipeline: document data to PDF to realistic photos.

**Parameters:**

| Name            | Type       | Required | Description                                                  |
| --------------- | ---------- | -------- | ------------------------------------------------------------ |
| `doc_number`    | `string`   | Yes      | Document number                                              |
| `date`          | `string`   | Yes      | Date                                                         |
| `emitter_name`  | `string`   | Yes      | Emitter company name                                         |
| `receiver_name` | `string`   | No       | Receiver company name                                        |
| `oc_number`     | `string`   | No       | Purchase order reference                                     |
| `items`         | `array`    | Yes      | Items: `[{description, qty, unit, unit_price?}]`             |
| `presets`       | `string[]` | No       | Presets (default: `full_picture`, `folded_skewed`, `blurry`) |

**Returns:** Document files + photo results.

### penquify\_text\_to\_config

Convert natural language to a photo variation JSON config.

**Parameters:**

| Name          | Type     | Required | Description                  |
| ------------- | -------- | -------- | ---------------------------- |
| `description` | `string` | Yes      | Natural language description |

**Returns:** PhotoVariation JSON config.

### penquify\_list\_presets

List all available photo variation presets and camera models.

**Parameters:** None.

**Returns:** Lists of preset names, camera names, and preset details.

## Environment Variables

| Variable          | Default             | Description                          |
| ----------------- | ------------------- | ------------------------------------ |
| `GEMINI_API_KEY`  | --                  | Required for photo generation        |
| `PENQUIFY_OUTPUT` | `~/penquify-output` | Output directory for generated files |