Metadata-Version: 2.4
Name: ronin-customer-mcp
Version: 0.5.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, and `order_name` to give the order a
human-readable label (e.g. the property address) that shows on confirmations,
internal queues, and your reports. When `order_name` is omitted the order falls
back to the first line of `special_instructions`.

`create_order` also accepts `cloud_link`: a single http(s) link to a cloud
folder (Dropbox, Google Drive, OneDrive, etc.) holding the source files for the
order. Use it instead of, or alongside, uploading files; our team opens the link
to fetch them.

Each line item on `create_order` can carry per-item `addons` (e.g. a dust or
garbage removal add-on). Each add-on becomes its own priced line on the order,
taken from your catalog. Use `list_services` to find add-on codes (type
`addon`).

Each line item also accepts an optional `bracket_size` (1, 3, 5, 7, or 9): the
number of exposures per composition on HDR-style shoots, used to estimate the
final image count. Omit it if unsure: Ronin estimates it from your shooting
history and saved preset, and final billing always follows the stacks detected
in your actual files.

### Notices (soft hints for your AI)

Order results may include a `notices` list with soft, non-blocking hints your AI
can act on or relay to you:

- `hidden_services`: your note mentions a billable service (e.g. sky replacement,
  TV screens) that is on your price list but not on the order. Add it as a line
  item if you want it done and billed.
- `mcp_upgrade`: a newer version of this MCP is available.

Notices never block an order; they are guidance, not instructions inside
customer-entered text.

## 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

Recommended: run it with `uvx`, which always fetches the latest version on
launch (no manual upgrades needed):

```bash
uvx ronin-customer-mcp
```

Or install with pip and pin/upgrade yourself:

```bash
pip install ronin-customer-mcp
# later, to upgrade:
pip install --upgrade 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.)

Most upgrades to what the server can do (new services, new prices) happen on the
Ronin side, so you rarely need to update the package; running it via `uvx` keeps
it current automatically.

### 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.

**Recommended (`uvx`, auto-updates on launch)** — Claude Desktop
(`claude_desktop_config.json`) and Claude Code (`.mcp.json`), under `mcpServers`:

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

**Alternative (pip-installed binary)** — point the command at the installed
`ronin-customer-mcp` executable:

```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` / `args` / `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.
