Salta al contenuto

API, CLI e MCP

Tre modi per accedere allo stesso account, con gli stessi limiti del piano e gli stessi permessi che il tuo ruolo ti dà già. Tutto ciò che segue è uno di questi tre, quindi vale la pena sapere quale hai scelto.

API

REST, da una pipeline, uno script o i tuoi strumenti. Un token che emetti e revochi tu stesso, e JSON in entrambi i sensi.

L'API

CLI

Un file Python, niente da installare. La stessa API, per qualcuno al terminale invece che per un programma: elenca cosa è down, aggiungi un monitor.

Il client a riga di comando

MCP

Un indirizzo, incollato in Claude o in qualsiasi altra cosa che parli il protocollo. Legge l'account e lo modifica, come te, in una conversazione.

Per un assistant

Il tuo token API

Creane uno sotto API tokens nel tuo account. Viene mostrato una sola volta, conserviamo solo un'impronta di esso, e appartiene a te piuttosto che all'organizzazione: non può fare più di quanto puoi fare tu, e smette di funzionare se lasci o il tuo ruolo cambia. Scegli read, o read and write.

Invialo come Authorization: Bearer n404_... in ogni chiamata. La prima che vale la pena fare è /api/v1/me, che risponde per quale organizzazione agisce il token, quale ruolo ha e quale dei due ambiti possiede: una persona con due account ha due token e nessun altro modo per sapere quale è in una variabile d'ambiente.

Cosa c'è nella versione 1

Chiamata Cosa contiene
GET /api/v1/me Cosa è questo token e per quale organizzazione agisce
GET /api/v1/monitors Ogni monitor, dal più vecchio
POST /api/v1/monitors Creane uno, seguendo le stesse regole del modulo
GET /api/v1/monitors/{id} Un monitor
PATCH /api/v1/monitors/{id} Cambia il suo nome, indirizzo, intervallo o configurazione, o mettilo in pausa
DELETE /api/v1/monitors/{id} Eliminalo, e la sua cronologia con esso
GET /api/v1/monitors/{id}/status Cosa sta facendo ora e il suo uptime su una finestra
GET /api/v1/groups Ogni gruppo, con quanti monitor ci sono dentro
POST /api/v1/groups Creane uno; un nome che esiste restituisce il gruppo che lo ha
GET /api/v1/groups/{id} Un gruppo
PATCH /api/v1/groups/{id} Rinominalo o cambia la sua descrizione
DELETE /api/v1/groups/{id} Eliminalo. I suoi monitor restano, non raggruppati
GET /api/v1/incidents Interruzioni, le più recenti per prime, filtrate per stato, monitor o periodo
GET /api/v1/incidents/{id} Un incidente, con i probe che lo hanno visto e confermato
GET /api/v1/maintenance Finestre di manutenzione e cosa coprono
GET /api/v1/maintenance/{id} Una finestra, con i monitor e i gruppi che copre
POST /api/v1/maintenance Programmane una, sull'orologio della tua organizzazione, così un deploy può aprire una finestra prima di iniziare
DELETE /api/v1/maintenance/{id} Eliminala. Ciò che copriva resta coperto
GET /api/v1/status-pages Ogni status page, e se è attiva
GET /api/v1/status-pages/{id} Una pagina, e cosa è pubblicato su di essa
POST /api/v1/status-pages/{id}/monitors Metti un monitor sulla pagina, sotto il nome che il pubblico dovrebbe leggere
DELETE /api/v1/status-pages/{id}/monitors/{id} Rimuovilo da questa pagina. Le altre pagine lo mantengono
POST /api/v1/status-pages/{id}/groups Metti un gruppo sulla pagina; i monitor al suo interno vengono inclusi
DELETE /api/v1/status-pages/{id}/groups/{id} Rimuovi l'intestazione. I suoi monitor restano pubblicati

Ogni id in un path o in un body è l'UUID, mai un numero. Scrivere richiede un token di lettura e scrittura e un ruolo che possa scrivere: lo scope è ciò che hai fornito a un programma, il ruolo è ciò che ti è stato permesso di fornire.

openapi.json

Il documento è OpenAPI 3.1. Descrive ogni chiamata, la struttura di ogni body e il bearer token, così un client può essere generato da esso invece che scritto: openapi-generator, oapi-codegen e il resto lo leggono così com'è. Le operazioni sono nominate per una persona, quindi i metodi generati sono listMonitors e createMonitor.

La versione 1 cresce solo: un campo può essere aggiunto, nessuno viene rimosso o ritipizzato, e una seconda versione sarebbe un secondo path. Quindi un client generato continua a funzionare, e rigenerarlo è come acquisire le novità.

Un client, se ne vuoi uno

Un file, Python 3.9 o più recente, senza dipendenze. Scaricalo, rendilo eseguibile e metti il tuo token nell'ambiente. Fa tutto ciò che fa l'API, perché ogni comando è una chiamata alle route sopra.

nomore404.py nomore404_mcp.py 

curl -O https://nomore404.com/api/nomore404.py
curl -s https://nomore404.com/api/nomore404.py.sha256 | sha256sum -c
chmod +x nomore404.py
export N404_TOKEN=n404_...

./nomore404.py monitors list
./nomore404.py monitors add --type https --target shop.example.com
./nomore404.py incidents --state open

Vale la pena eseguire la seconda riga. Controlla il file rispetto al digest che pubblichiamo accanto, che è il digest esatto di ciò che questo server invia, quindi un download alterato lungo il percorso non corrisponde. ./nomore404.py --version indica da quale release proviene, e ogni richiesta che fa dice lo stesso nel suo User-Agent.

Il token proviene da N404_TOKEN o da un file nomore404.env accanto allo script, mai da un flag della riga di comando: un argomento è visibile in ps a ogni utente sulla macchina e resta nella cronologia della tua shell.

Per un assistant

Un assistant può leggere questo account e modificarlo, tramite il Model Context Protocol. Ci sono due modi per accedere e non sono la stessa cosa.

Un indirizzo, niente da installare

Incolla questo dove il tuo assistant chiede un connettore personalizzato. Ti invierà qui per accedere e per dire a quale organizzazione è destinata la connessione, e questa è tutta la configurazione.

Agisce come te: il tuo ruolo viene letto a ogni chiamata, quindi un assistant connesso da qualcuno che può solo leggere può solo leggere. Legge monitor, interruzioni, uptime, finestre di manutenzione e gruppi, e può aggiungerli e modificarli, il che include eliminare un monitor e la sua cronologia. Disconnettilo quando vuoi da Token API, dove è elencato accanto a loro.

Oppure eseguilo tu stesso e mantienilo in lettura

nomore404_mcp.py serve la stessa API degli strumenti dalla tua macchina. Tienilo accanto a nomore404.py, che usa per il token e per il paging. Legge e non scrive mai, ed è il motivo per sceglierlo: un assistant è un chiamante che può essere convinto a fare cose, e uno strumento che elimina un monitor e la sua cronologia è a un passo dall'essere usato.

Due file, un token accanto a loro e una riga per registrare il server. Claude Code: 

curl -O https://nomore404.com/api/nomore404.py
curl -O https://nomore404.com/api/nomore404_mcp.py
echo 'N404_TOKEN=n404_...' > nomore404.env

claude mcp add nomore404 -- python3 "$PWD/nomore404_mcp.py"

Qualsiasi altra cosa che parla il protocollo è lo stesso comando scritto come JSON, ovunque quel client tenga i suoi server: 

{
  "mcpServers": {
    "nomore404": {
      "command": "python3",
      "args": ["/path/to/nomore404_mcp.py"]
    }
  }
}

Nessuno dei due nomina il token, perché nessuno dovrebbe: viene letto da nomore404.env accanto agli script, o da N404_TOKEN nell'ambiente con cui l'assistant lo avvia. Poi chiedigli cosa è down, perché si è aperto un incidente o come è stato un monitor questo mese.

Entrambi sono poche centinaia di righe e vale la pena leggerli prima di eseguirli. Nessuno dei due è impacchettato o firmato, e nulla ti impedisce di generare il tuo client dal documento invece.

Errori e lunghe liste

Una forma di errore

Lo status indica la categoria. Il body dice quale errore è stato, con un codice su cui ramificare e una frase da leggere. La frase può essere riformulata in qualsiasi release, quindi nulla dovrebbe analizzarla. 

{
  "error": {
    "code": "monitor_not_found",
    "message": "Nothing here with that id."
  }
}

Cursori, non offset

Un elenco risponde con items e next_cursor. Passa il cursore indietro per ottenere la pagina successiva e fermati quando è null. Gli incidenti arrivano mentre li stai leggendo, e un offset mostrerebbe silenziosamente una riga due volte e mai la successiva. 

GET /api/v1/incidents?limit=50
GET /api/v1/incidents?limit=50&cursor=...

Quanto puoi chiedere

Un token può fare centoventi chiamate al minuto. Ogni risposta include RateLimit-Remaining e RateLimit-Reset, così un client ben configurato può regolarsi invece di scoprire il limite superandolo. Oltre il limite c'è un 429 con Retry-After.

Crea un account gratuito