API e MCP per sviluppatori

Panoramica

farmastock.app espone un'API REST pubblica e read-only e un server MCP con gli stessi dati: la scheda dell'app FarmaStock e le guide del blog (in italiano) su farmaci, scadenze, conservazione e interazioni. Specifica completa in /openapi.json (OpenAPI 3.1), catalogo in /.well-known/api-catalog.

  • Base URL: https://farmastock.app
  • Autenticazione: nessuna
  • Formato: JSON (UTF-8), CORS aperto

Endpoint

GET /api/v1/info

Scheda dell'app: descrizione, funzionalità, prezzo, link App Store, contatti e numero di guide.

curl https://farmastock.app/api/v1/info

GET /api/v1/articles

Elenco paginato delle guide. Parametri: q (parole da cercare, max 100 caratteri), limit (1-50, default 20), offset (default 0).

curl "https://farmastock.app/api/v1/articles?q=tachipirina&limit=5"

GET /api/v1/articles/{slug}

Metadati e testo completo in markdown di una guida.

curl https://farmastock.app/api/v1/articles/farmaci-scaduti-cosa-fare

Markdown

Home, blog, guide e pagine principali rispondono in markdown se la richiesta invia Accept: text/markdown. Ogni guida è anche un file statico in /content/blog/<slug>.md.

curl -H "Accept: text/markdown" https://farmastock.app/blog/farmaci-scaduti-cosa-fare/

Rate limit

60 richieste ogni 60 secondi per indirizzo IP, condivise tra API e MCP. Ogni risposta riporta gli header IETF RateLimit-Policy: "default";q=60;w=60 e RateLimit: "default";r=<rimanenti>;t=<secondi>. Oltre il limite la risposta è 429 con Retry-After.

Errori

Gli errori sotto /api/ usano application/problem+json (RFC 9457) con i campi type, title, status, detail, code e resolution.

  • invalid_parameter, invalid_slug — 400
  • not_found, article_not_found — 404
  • method_not_allowed — 405
  • rate_limited — 429
  • internal_error — 500

Server MCP

Endpoint Streamable HTTP (JSON-RPC 2.0, senza autenticazione): https://farmastock.app/mcp. Descrittori in /.well-known/mcp/server-card.json e /server.json.

  • get_app_info — scheda dell'app
  • search_articles — cerca tra le guide (query, limit, offset)
  • get_article — testo markdown di una guida (slug)

Risorse: la scheda dell'app (JSON) e llms.txt.

Claude Code

claude mcp add --transport http farmastock https://farmastock.app/mcp

Da riga di comando

curl -X POST https://farmastock.app/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_articles","arguments":{"query":"antibiotici"}}}'

Per esplorarlo in modo interattivo: npx @modelcontextprotocol/inspectorcon trasporto Streamable HTTP e l'URL qui sopra.

Condizioni d'uso

I contenuti delle guide sono informativi e non sostituiscono il parere del medico o del farmacista. Se li riusi, cita la fonte con il link all'articolo. Per usi intensivi o domande scrivi a simone.ruggiero97@gmail.com.