# Maizapp MCP API

Maizapp expone un servidor MCP (Model Context Protocol) que permite a asistentes
de inteligencia artificial y agentes consultar los datos de una organización de
forma segura y de solo lectura.

## Empieza aquí (guía para usuarios de Maizapp)

Si eres usuario de Maizapp, lo único que necesitas hacer tú es generar tu API key:

1. En Maizapp ve a Configuración → API Keys (solo el dueño de la organización).
2. Crea una key con los permisos que quieras dar y cópiala (se muestra una sola vez).
3. Dale la key a tu asistente de IA junto con esta documentación y pídele que se
   conecte. Tu agente puede encargarse de toda la configuración técnica.

Si eres un agente de IA ayudando a un usuario a conectarse: pídele su API key
(él la genera en Configuración → API Keys dentro de Maizapp) y configura la
conexión por él usando el endpoint y las instrucciones de abajo.

## Endpoint

- URL: https://www.maizapp.com/api/mcp
- Transporte: Streamable HTTP (MCP)
- Métodos: POST (mensajes JSON-RPC), GET (stream), DELETE (cerrar sesión)

## Autenticación

Cada petición debe incluir una API key en el encabezado de autorización:

```
Authorization: Bearer mz_live_TU_API_KEY
```

Las API keys las genera el dueño de la organización dentro de Maizapp
(Configuración → API Keys). Cada key está limitada a su organización y a los
permisos (scopes) que se le asignen. Todo el acceso es de SOLO LECTURA.

## Scopes disponibles

- `orders:read` — leer pedidos
- `products:read` — leer productos
- `inventory:read` — leer inventario
- `customers:read` — leer clientes

## Conexión

### Conector remoto (Claude, ChatGPT y otros)

Agrega un servidor MCP remoto con la URL del endpoint y, como autenticación,
el encabezado `Authorization: Bearer <API_KEY>`.

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "maizapp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://www.maizapp.com/api/mcp",
        "--header",
        "Authorization: Bearer mz_live_TU_API_KEY"
      ]
    }
  }
}
```

### Prueba con curl

```bash
curl -X POST https://www.maizapp.com/api/mcp \
  -H "Authorization: Bearer mz_live_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## Herramientas (tools)

### list_orders
- Permiso requerido: `orders:read`
- Lista pedidos de la organización. Permite filtrar por estado, búsqueda de cliente y rango de fechas (sobre la fecha programada).
- Parámetros:
  - `status` (PENDING | PREPARED | ON_ROUTE | DELIVERED | CANCELLED): Estado del pedido
  - `search` (string): Nombre o teléfono del cliente
  - `from` (string (YYYY-MM-DD)): Fecha inicial
  - `to` (string (YYYY-MM-DD)): Fecha final
  - `limit` (number (1-100)): Máximo de resultados (default 20)

### get_order
- Permiso requerido: `orders:read`
- Obtiene el detalle de un pedido por su ID, incluyendo productos y pagos.
- Parámetros:
  - `orderId` (string) — requerido: ID del pedido

### list_products
- Permiso requerido: `products:read`
- Lista productos de la organización. Permite buscar por nombre, SKU o código interno.
- Parámetros:
  - `search` (string): Nombre, SKU o código interno
  - `activeOnly` (boolean): Solo productos activos (default true)
  - `limit` (number (1-100)): Máximo de resultados (default 50)

### check_inventory
- Permiso requerido: `inventory:read`
- Consulta el stock actual de los productos. Permite filtrar solo los que están en o por debajo del stock mínimo.
- Parámetros:
  - `lowStockOnly` (boolean): Solo productos bajos de mínimo
  - `search` (string): Nombre del producto
  - `limit` (number (1-100)): Máximo de resultados (default 50)

### list_customers
- Permiso requerido: `customers:read`
- Lista clientes de la organización. Permite buscar por nombre, teléfono o código de cliente.
- Parámetros:
  - `search` (string): Nombre, teléfono o código de cliente
  - `limit` (number (1-100)): Máximo de resultados (default 50)

## Ejemplos de uso en lenguaje natural

- ¿Cuántos pedidos pendientes tengo para hoy?
- Dame el detalle del pedido #1043.
- ¿Qué productos están por debajo del stock mínimo?
- Busca al cliente Tortillería La Esperanza y dime su saldo de crédito.
- Lista los pedidos entregados esta semana.

## Seguridad

- Cada API key solo accede a los datos de su propia organización.
- El acceso es de solo lectura: no es posible crear, modificar ni eliminar datos.
- Las keys pueden revocarse en cualquier momento; al revocarlas dejan de funcionar de inmediato.
- Trata tus API keys como contraseñas: no las compartas ni las publiques.