Metadata-Version: 2.4
Name: docauto-mcp
Version: 0.2.0
Summary: Model Context Protocol server for the DocAuto document-generation API.
Project-URL: Homepage, https://docauto.com.br
Project-URL: Documentation, https://docauto.com.br/docs/mcp
Project-URL: Repository, https://github.com/gzucob/docauto
Author: DocAuto
License-Expression: MIT
Keywords: ai,docauto,documents,mcp,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<2,>=1.12
Requires-Dist: uvicorn>=0.30
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# DocAuto MCP server

A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes
the DocAuto document-generation workflow to AI assistants. It is a thin client
over the public `/api/v1` surface — it holds no secrets and enforces no
business logic; multi-tenancy and validation live in the backend.

- **Transport:** stdio (local) and a hosted Streamable-HTTP server at
  `https://mcp.docauto.com.br/mcp` (add it as a remote connector — no install).
- **Auth (local):** OAuth 2.0 Device Authorization Grant against the Keycloak
  `docauto-cli` public client. You sign in once in your browser; tokens are
  cached at `~/.docauto/mcp-tokens.json` (0600) and refreshed automatically.

## Install

The server is a standalone Python package (it is **not** part of the backend).
Requires Python ≥ 3.11.

```bash
# run on demand, no install:
uvx docauto-mcp
# or install it:
pipx install docauto-mcp
```

From a checkout (dev): `pip install ./mcp`.

## Configure your MCP client

### Claude Desktop — automatic

The package ships a setup helper that writes `claude_desktop_config.json` for
you (handling the Windows Store/MSIX config-path quirk):

```bash
docauto-mcp-install            # register the installed `docauto-mcp` command
docauto-mcp-install --command uvx   # zero-install: run via `uvx docauto-mcp`
docauto-mcp-install --print    # print the JSON block instead of writing it
```

### Claude Desktop — manual

```json
{
  "mcpServers": {
    "docauto": {
      "command": "docauto-mcp"
    }
  }
}
```

If `docauto-mcp` is not on your PATH, use the `uvx` form
(`"command": "uvx", "args": ["docauto-mcp"]`) or point `command` at the script
inside your virtualenv.

### Claude Code (CLI)

```bash
claude mcp add docauto -- uvx docauto-mcp
```

### Cursor / VS Code / other clients

These accept a remote MCP server by URL — see the **hosted** server below
(`https://mcp.docauto.com.br/mcp`), which needs no local install.

### Environment overrides (optional)

Defaults target production; override only for local dev:

| Variable | Default |
|---|---|
| `DOCAUTO_MCP_ISSUER` | `https://auth.docauto.com.br/realms/docauto` |
| `DOCAUTO_MCP_API_BASE` | `https://api.docauto.com.br` (server-to-server; set to the internal service in-cluster) |
| `DOCAUTO_MCP_PUBLIC_API_BASE` | `https://api.docauto.com.br` (public base for user-facing links, e.g. signed download URLs) |
| `DOCAUTO_MCP_PUBLIC_APP_BASE` | `https://docauto.com.br` (public frontend base for the upload page link) |
| `DOCAUTO_MCP_CLIENT_ID` | `docauto-cli` |
| `DOCAUTO_MCP_HOME` | `~/.docauto` (token cache location) |

## Logging in

You sign in with your normal DocAuto account (the MCP server does not create a
different kind of account):

1. Call **`login_start`** — it returns a verification URL and a short code.
2. Open the URL, sign in (email/password or Google), and approve.
3. Call **`login_finish`** — it completes the login and caches your tokens.

After that the assistant can use the tools below; tokens refresh silently until
the session expires.

## Prompts

- **`generate_documents`** (argument: `output_format` = `pdf` | `docx`) — a
  guided template that drives the whole batch-generation flow. Available in any
  client that surfaces MCP prompts, over both transports.

## Tools

- **Session:** `login_start`, `login_finish`, `logout`, `whoami`, `doctor`,
  `workflow_guide` — `doctor` reports the version, the configured endpoints, API
  reachability, and sign-in state (no secrets)
- **Templates:** `list_templates`, `get_template`, `upload_template`, `delete_template`
- **Datasets:** `list_datasets`, `get_dataset`, `preview_dataset`, `upload_dataset`, `delete_dataset`
- **Generation:** `validate_mapping`, `create_generation_job`, `get_job`, `list_jobs`, `cancel_job`, `delete_job`, `list_job_documents`
- **Downloads:** `download_document`, `download_job_zip` — over stdio these save
  to the user's local Downloads folder; over the hosted HTTP transport
  `download_job_zip` returns a short-lived signed URL the user opens in a browser
  (the ZIP is never streamed through the model, so there is no size cap)
- **Uploads (hosted HTTP only):** over stdio `upload_template`/`upload_dataset`
  read a local path; over the hosted transport they take only a `filename` and
  return an `upload_url` the user opens to send the file (the bytes never pass
  through the model), plus an `upload_ref` to poll with `check_upload` until the
  result is `ready`

## Typical flow

`login_start` → `login_finish` → `whoami` → `upload_template(path)` →
`upload_dataset(path)` → `validate_mapping(...)` →
`create_generation_job(...)` → poll `get_job(job_id)` →
`download_job_zip(job_id, dest)`.

The `field_mapping` maps each template variable to a dataset column, e.g.
`{"nome_cliente": "nome_cliente", "cpf": "cpf"}`. `output_format` is `pdf`
(default) or `docx`.

## Development

```bash
# unit tests (no MCP SDK needed — auth/client/tools are isolated)
python -m pytest tests
```
