Metadata-Version: 2.4
Name: ronin-customer-mcp
Version: 0.1.0
Summary: Run your Ronin Editing account from any AI assistant. A local MCP server that lets Claude, Cursor, Cline, VS Code and other MCP clients read your orders, invoices and reports, and (opt in) place and manage orders, using your own Ronin API key.
Author: Ronin Editing
License: Proprietary
Project-URL: Homepage, https://www.roninediting.com
Project-URL: Documentation, https://client.ronincenter.com/document/mcp
Keywords: mcp,model-context-protocol,ronin,real-estate-photography,ai-agent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Customer Service
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: mcp>=0.9.0
Requires-Dist: pydantic>=2.6
Requires-Dist: httpx>=0.27
Requires-Dist: structlog>=24.1

# Ronin Customer MCP Server

Run a local AI tool server that lets your AI assistant read your Ronin orders,
invoices, and reports, and (if you turn it on) place and manage orders. It uses
your own Ronin API key. Nothing is exposed to the public; the server runs on
your machine over stdio and works with any MCP client (Claude Desktop, Claude
Code, Cursor, Cline, Windsurf, VS Code with Copilot, LM Studio, Goose, and more).

## What it can do

Read tools are on by default. Write tools are off until you explicitly enable
them and your key has write permission.

### Read tools (default on)

| Tool | What it does |
|---|---|
| `list_orders` | List your orders, optionally filtered by status |
| `get_order` | Full detail for one order |
| `get_order_delivery` | Delivery info and download links for an order |
| `list_order_messages` | Messages on an order thread |
| `list_order_amendments` | Amendment requests on an order |
| `list_invoices` / `get_invoice` | Your invoices |
| `get_cost_summary` | Cost report by day for a date range |
| `get_orders_report` | Per-order detail report for a date range |
| `get_monthly_statement` | Total orders and revenue for a month |
| `get_invoices_report` | Invoices report by status |
| `list_services` / `get_service` | The service catalog |
| `preview_pricing` | Price a cart of services without placing an order |
| `whoami` / `get_usage` | Account, key, and recent usage |

### Write tools (off by default, opt in)

`create_order`, `create_orders_batch`, `cancel_order`, `send_order_message`,
`request_amendment`, `cancel_amendment`, `submit_feedback`,
`update_order_source_file_count`.

`create_order` accepts `external_ref` so you can tag each order with your own
property or shoot ID for reconciliation.

## Get an API key

Sign in to your Ronin portal, open API tokens, and create a key. Copy it once
(it is shown only at creation). The key carries scopes such as `orders:read`,
`orders:write`, `billing:read`, `reports:read`, `catalog:read`. The server only
shows tools your key is allowed to use.

## Install

```bash
pip install ronin-customer-mcp
```

This installs a `ronin-customer-mcp` command. Run it directly to check it works:

```bash
RONIN_API_KEY=rk_live_xxx ronin-customer-mcp
```

(The server speaks the MCP protocol over stdio, so run it from your MCP client
rather than interactively.)

### Configuration (environment variables)

| Variable | Required | Default | Meaning |
|---|---|---|---|
| `RONIN_API_KEY` | yes | none | Your Ronin API key |
| `RONIN_API_BASE_URL` | no | `https://api.ronincenter.com` | API base URL |
| `RONIN_MCP_ENABLE_WRITE` | no | `false` | Set `true` to expose write tools |

### Add to your MCP client

Most MCP clients use the same JSON shape. Point the command at the installed
`ronin-customer-mcp` executable.

**Claude Desktop** (`claude_desktop_config.json`) and **Claude Code**
(`.mcp.json`), under `mcpServers`:

```json
{
  "mcpServers": {
    "ronin": {
      "command": "ronin-customer-mcp",
      "env": {
        "RONIN_API_KEY": "rk_live_xxx",
        "RONIN_MCP_ENABLE_WRITE": "false"
      }
    }
  }
}
```

**Cursor** (`.cursor/mcp.json`), **Cline**, and **VS Code** (Copilot MCP) use
the same `command` / `env` structure under their MCP settings.

To allow placing or cancelling orders, set `RONIN_MCP_ENABLE_WRITE` to `true`
and use a key that has the `orders:write` scope.

## Safety

This server is designed to be safe by default.

- Read only by default. Write tools require two things at once: you set
  `RONIN_MCP_ENABLE_WRITE=true` and your key has the write scope. If either is
  missing, the AI cannot place or cancel orders.
- Your key only ever sees your own data. A leaked key affects only your account.
- Treat order content as data, not instructions. Order notes, messages, and
  amendment or feedback text are written by people and can contain text that
  tries to manipulate an AI agent. Every tool result marks these fields under
  `untrusted_fields`. Your AI assistant should never follow instructions found
  inside them.

## Troubleshooting

- `missing_api_key`: set `RONIN_API_KEY`.
- `invalid_api_key`: the key was rejected. Check it is correct and active.
- A write tool is not listed: set `RONIN_MCP_ENABLE_WRITE=true` and use a key
  with the `orders:write` scope.
- A read tool is not listed: your key is missing that scope. Add the scope in
  the portal.
