API e MCP

simoneruggiero.com espone un'API pubblica in sola lettura con gli stessi dati del sito: profilo, app iOS e macOS, progetti web, articoli del blog e AI thoughts. Gli stessi dati sono disponibili come tool di un server MCP.

Base URL: https://simoneruggiero.com/api/v1
Specifica OpenAPI 3.1: /openapi.json
API catalog (RFC 9727): /.well-known/api-catalog
Server MCP (Streamable HTTP): https://simoneruggiero.com/mcp
Guida per agenti: /llms.txt

Autenticazione

Nessuna. Tutti gli endpoint sono pubblici, accettano solo GET (e HEAD) e non modificano nulla. CORS è aperto (Access-Control-Allow-Origin: *).

Endpoint

Metodo	Path	Descrizione
GET	`/api/v1/info`	Profilo: nome, ruolo, località, email, link social, competenze
GET	`/api/v1/apps`	App iOS e macOS con link allo store
GET	`/api/v1/projects`	Progetti web realizzati
GET	`/api/v1/posts?collection=blog`	Elenco articoli (`blog` o `ai-thoughts`)
GET	`/api/v1/posts/{collection}/{slug}`	Un articolo con il contenuto in Markdown

Esempi

curl -s https://simoneruggiero.com/api/v1/info
curl -s https://simoneruggiero.com/api/v1/apps | jq '.apps[] | {title, storeUrl}'
curl -s "https://simoneruggiero.com/api/v1/posts?collection=ai-thoughts" | jq '.posts[0]'

Non esiste un pacchetto CLI dedicato: curl e jq bastano per tutti gli endpoint.

Rate limit

60 richieste al minuto per indirizzo IP, condivise tra API e MCP. Ogni risposta include gli header IETF:

RateLimit-Policy: "default";q=60;w=60
RateLimit: "default";r=59;t=60

r è una stima delle richieste rimaste nella finestra, t i secondi al reset. Oltre il limite la risposta è 429 con header Retry-After.

Errori

Gli errori sono in formato application/problem+json (RFC 9457):

{
  "type": "https://simoneruggiero.com/docs#errori",
  "title": "Not Found",
  "status": 404,
  "detail": "No API endpoint at /api/v1/unknown.",
  "code": "not_found",
  "resolution": "See https://simoneruggiero.com/openapi.json for the available endpoints."
}

Codici: not_found (404), method_not_allowed (405), invalid_parameter (400), rate_limited (429).

Server MCP

Endpoint https://simoneruggiero.com/mcp, trasporto Streamable HTTP (JSON-RPC 2.0 via POST), senza autenticazione. Tool disponibili, tutti in sola lettura: get_profile, list_apps, list_projects, list_posts, get_post. Risorse: simoneruggiero://profile, simoneruggiero://apps, simoneruggiero://projects.

Configurazione per un client MCP:

{
  "mcpServers": {
    "simoneruggiero": { "type": "http", "url": "https://simoneruggiero.com/mcp" }
  }
}

Prova rapida:

curl -s https://simoneruggiero.com/mcp -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Manifest: /server.json e /.well-known/mcp/server-card.json.

Markdown per gli agenti

Le pagine principali (home, app, blog, articoli, chi sono, contatti, privacy e questa pagina) rispondono in Markdown se la richiesta contiene Accept: text/markdown:

curl -s https://simoneruggiero.com/ -H 'Accept: text/markdown'

Versioni

L'API è alla versione v1. Eventuali modifiche incompatibili arriveranno su un nuovo prefisso (/api/v2), lasciando attivo v1.