# Developer resources — Susurros del Ruiz

Susurros del Ruiz runs a read-only **MCP (Model Context Protocol) server** that
exposes the farm's operational data: harvests, lots, inventory, sales,
profitability and payroll. It is meant for AI assistants and internal tooling,
not for public consumption.

Last updated: 2026-09-08. Canonical domain: https://susurrosdelruiz.com

## Is this for you?

**Yes**, if you are building an assistant or a tool that needs live figures
from this specific farm and you have been given an API key by Susurros del
Ruiz.

**No**, if you are looking for a public product catalogue, prices, or a way to
place an order. There is no public commerce API. For buying mangosteen, pulp
or powder, write to gerencia@susurrosdelruiz.com or call **+57 300 230 1391**.
See [/agent-instructions.md](https://susurrosdelruiz.com/agent-instructions.md).

## MCP server

| | |
|---|---|
| Endpoint | `https://ifapivzvphsdkrhcrmwk.supabase.co/functions/v1/mcp` |
| Protocol | Model Context Protocol, JSON-RPC over HTTP |
| Methods | `initialize`, `tools/list`, `tools/call` |
| Auth | `Authorization: Bearer szr_live_…` |
| Access | Read-only. No method writes, deletes or mutates anything. |
| Keys | Issued by Susurros del Ruiz. Only a SHA-256 hash is stored; keys are revocable. |

Keys are not self-service. Request one at gerencia@susurrosdelruiz.com,
explaining what you are building.

### Connecting from a client

Most MCP clients reach a remote server through `mcp-remote`:

```json
{
  "mcpServers": {
    "susurros": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://ifapivzvphsdkrhcrmwk.supabase.co/functions/v1/mcp",
        "--header", "Authorization: Bearer szr_live_YOUR_KEY"
      ]
    }
  }
}
```

### Listing the tools

```bash
curl -s https://ifapivzvphsdkrhcrmwk.supabase.co/functions/v1/mcp \
  -H "Authorization: Bearer szr_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

### Available tools

All are read-only and return JSON.

| Tool | What it returns |
|---|---|
| `kpis` | Headline indicators by module (panel, farm, commercial) |
| `pyg` | Profit and loss |
| `flujo_caja` | Monthly cash flow: income, outflow and net, by `YYYY-MM` |
| `cartera` | Receivables by client: invoiced, paid, outstanding |
| `ventas` | Sales with total, client, channel, payment status and linked pick |
| `rentabilidad_cliente` | Profitability by client |
| `rentabilidad_producto` | Profitability by product |
| `rentabilidad_lote` | Profitability by lot |
| `lotes` | Lots with their state |
| `inventario` | Stock of raw material and finished goods |
| `curva_cosecha` | Harvest curve across the season |
| `ranking_recogedores` | Picker productivity ranking |
| `nomina` | Payroll |
| `gastos` | Expenses |
| `merma` | Loss and shrinkage |
| `alertas_integridad` | Data-integrity alerts |

## Public traceability endpoint

This one needs **no key**. It is what the QR code printed on each package
resolves to, and it is safe to call from anything.

```bash
curl -s -X POST \
  https://ifapivzvphsdkrhcrmwk.supabase.co/rest/v1/rpc/traza_publica \
  -H "apikey: PUBLIC_ANON_KEY" \
  -H "Content-Type: application/json" \
  -d '{"p_codigo":"R2-F2-1"}'
```

It returns the product name, the farm, the harvest year, the elaboration date
and the expiry, for a given lot code. The human-readable version lives at
`https://susurrosdelruiz.com/es/finca/lote/<lot-code>`.

## Machine-readable files on this domain

| Path | What it is |
|---|---|
| `/llms.txt` | What the business does, what it sells, when to consult it |
| `/agent-instructions.md` | When to use us and when not to; facts you can cite |
| `/developers.md` | This file |
| `/sitemap.xml` | Every page that exists |
| `/robots.txt` | Crawler policy; AI crawlers are allowed |

Any page returns Markdown when requested with `Accept: text/markdown`, with
`Vary: Accept`. Nonexistent paths return a real HTTP 404, and a Markdown body
when the request asked for Markdown.

## Contact

- Technical questions and key requests: gerencia@susurrosdelruiz.com
- Phone and WhatsApp: **+57 300 230 1391**