Espone API JSON e MCP HTTP per far lavorare gli agenti sul CRM.

Gli agenti autenticati con token Bearer possono leggere today/pipeline e annotare attività, con host MCP allineati a quelli di produzione.

Co-authored-by: Cursor <cursoragent@cursor.com>

README.md

@@ -163,6 +163,66 @@ Pipeline stages: Da contattare → Contattato → Ha risposto → Interessato
 4. Metti un reverse proxy (Caddy/Nginx) con HTTPS davanti alla porta 3000
 5. Esegui backup periodici con `bin/backup`
 
+## API JSON per agenti
+
+I client HTML restano su cookie di sessione. Gli agenti (Cursor, Claude Code, Codex) usano un token Bearer.
+
+1. Nel CRM: **Token API** (menu utente, oppure Impostazioni piattaforma se sei admin)
+2. Crea un token: il valore `crm_…` si vede **una sola volta**
+3. Header: `Authorization: Bearer crm_…`
+
+Endpoint v1 (tutti tranne `GET /api/v1/projects` richiedono `:project_code`):
+
+| Metodo | Path | Ruolo |
+|--------|------|--------|
+| GET | `/api/v1/projects` | progetti accessibili |
+| GET | `/api/v1/p/:project_code/today` | task scaduti / oggi / in arrivo + opportunità ferme |
+| GET | `/api/v1/p/:project_code/search?q=` | org, contatti, opportunità |
+| GET | `/api/v1/p/:project_code/organizations/:id` | scheda operativa |
+| POST | `/api/v1/p/:project_code/tasks` | crea task |
+| POST | `/api/v1/p/:project_code/tasks/:id/complete` | completa task |
+| POST | `/api/v1/p/:project_code/activities` | annota timeline |
+| PATCH | `/api/v1/p/:project_code/opportunities/:id/stage` | cambia stage pipeline |
+
+L’agente agisce come l’utente del token (stessi progetti, stesso `created_by`). Fuori da questa v1: mailing, utenti, delete, import CSV.
+
+Esempio:
+
+```bash
+curl -sS -H "Authorization: Bearer crm_…" \
+  http://localhost:3001/api/v1/p/matchlivetv/today
+```
+
+## MCP (Cursor CLI / Claude Code / Codex)
+
+Gli agenti parlano con il CRM su **HTTP**: `http://localhost:3001/mcp` (stesso Bearer del token API). Non serve Ruby sull’host.
+
+1. Avvia il CRM (`docker compose up`)
+2. Crea un token in **Token API**
+3. Esporta il token e lancia l’agente dalla root del repo:
+
+```bash
+export CRM_API_TOKEN='crm_…'
+# Cursor CLI:
+agent "Interagisci col CRM su MatchLiveTV: cosa c'è da fare oggi?"
+# Claude Code:
+claude "Interagisci col CRM su MatchLiveTV: cosa c'è da fare oggi?"
+```
+
+Config già nel repo (il token sta solo in env, non nei file):
+
+- Cursor / Cursor CLI: [`.cursor/mcp.json`](.cursor/mcp.json)
+- Claude Code: [`.mcp.json`](.mcp.json)
+- Codex: copia [mcp/codex.config.toml.example](mcp/codex.config.toml.example) in `~/.codex/config.toml`
+
+Istruzioni per gli agenti: [AGENTS.md](AGENTS.md).
+
+Tool: `list_projects`, `today`, `search`, `get_organization`, `create_task`, `complete_task`, `create_activity`, `update_opportunity_stage`.
+
+Stdio (`mcp/server.rb` / `bin/crm-mcp`) resta come alternativa se un client non parla HTTP.
+
+Esempio in chat: *«Interagisci col CRM e fai alcune cose per me su MatchLiveTV.»*
+
 ## Sviluppo locale senza Docker (opzionale)
 
 ```bash
@@ -174,8 +234,7 @@ bin/dev   # server + tailwind watch
 ## Volutamente fuori scope (fase successiva)
 
 - Integrazioni Gmail/SMTP avanzate, sync email, calendario
-- Stripe, webhook, API REST pubblica
-- Multi-tenant / multi-progetto
+- Stripe, webhook
 - Dark mode, BI avanzata, microservizi
 
 ## Licenza