# AMI — Agent Mobile Identity Protocol

> Protocolo estándar para que un agente AI solicite, contrate y active una identidad móvil
> (SIM, eSIM o número de teléfono). v1 cubre el flujo de contratación y aprovisionamiento;
> la operación (llamadas, SMS, WhatsApp) llega en v2.

AMI expone un MCP server con 11 tools y una REST API JSON. El agente recorre:
solicitud → oferta → datos cliente → contrato → firma → MobileIdentity activa.
Lo único simulado actualmente es la SIM física; el resto del flujo es real.

## Conexión (recomendado para agentes)

**Cero instalación, cero API key local — usa el MCP HTTP remoto:**

- URL: https://ami-mcp-http.onrender.com/mcp/
- Transporte: streamable-http
- Auth MCP: ninguna (la API key vive ya en el servidor de Render).

Cualquier cliente MCP que soporte transporte streamable-http se enchufa
directamente. Esta es la forma recomendada para agentes corriendo en
máquinas remotas o CI: no requiere clonar el repo, ni instalar Python, ni
gestionar `AMI_API_KEY` localmente.

## Conexión alternativa (stdio local)

Sólo si el cliente MCP no soporta HTTP remoto:

- Instalador one-liner: `curl -fsSL https://ami-mock-api.onrender.com/install.sh | sh`
- Repo: https://github.com/Gamino17/AMI
- Requiere setear `AMI_API_KEY` propia para hablar con el backend.

## Acceso REST directo

Para clientes no-MCP, la API REST está documentada en /openapi.json. Auth con
header `Authorization: Bearer <AMI_API_KEY>`.

## Tools MCP (namespace ami.*)

- ami.search_sim_options: Lista países, tipos de SIM/eSIM y capacidades disponibles.
- ami.request_sim_offer: Crea una SIMRequest y devuelve la oferta inmediata del partner telco.
- ami.accept_offer: Acepta una oferta antes de generar contrato.
- ami.submit_customer_data: Envía los datos legales/fiscales del cliente y los vincula a la solicitud.
- ami.create_contract: Genera el contrato y devuelve la URL de firma.
- ami.get_contract_status: Consulta el estado actual de un contrato.
- ami.confirm_signature_status: Comprueba si el contrato ya está firmado.
- ami.activate_sim_identity: Inicia el provisioning con el partner telco tras la firma.
- ami.get_identity_status: Consulta el estado de una MobileIdentity activa.
- ami.cancel_request: Cancela una SIMRequest antes de la activación.
- ami.list_events: Devuelve los últimos AuditEvents (debug e inspección).

## Endpoints REST

- GET /v1/health — Healthcheck (público).
- GET /v1/sim-options — Países y SIMs disponibles.
- POST /v1/sim-requests — Crea SIMRequest y oferta.
- POST /v1/sim-requests/{id}/cancel — Cancela una SIMRequest.
- POST /v1/sim-requests/{id}/customer-data — Vincula datos del cliente.
- POST /v1/offers/{id}/accept — Acepta una oferta.
- POST /v1/contracts — Crea contrato y signature_url.
- GET /v1/contracts/{id} — Consulta el contrato.
- GET /v1/sign/{id} — Página HTML de firma (pública).
- POST /v1/sign/{id}/confirm — Callback del form de firma (público).
- POST /v1/mobile-identities/activate — Activa la MobileIdentity tras la firma.
- GET /v1/mobile-identities/{id} — Consulta una MobileIdentity.
- GET /v1/events — Últimos AuditEvents.
- POST /v1/demo/quick — Flujo end-to-end completo en una llamada (público, sin auth).
- GET /identity/{id} — Página pública de una MobileIdentity activa.
- GET /spec — Spec del protocolo renderizada en HTML.

## Documentación

- Repo y README: https://github.com/Gamino17/AMI
- Spec completa (markdown en GitHub): https://github.com/Gamino17/AMI/blob/main/docs/SPEC.md
- Spec renderizada en HTML: /spec
- OpenAPI 3.1: /openapi.json
- Identidad móvil pública (ejemplo): /identity/<mobile_identity_id>
- Demo end-to-end sin auth: POST /v1/demo/quick