# Agenti AI e MCP
Stai costruendo un agente AI che deve fare vere e proprie **calcoli astrologici** invece di allucinazioni? AstroWay si collega a **Claude (Anthropic), ChatGPT-4 (OpenAI), Llama 3.3 (Groq), DeepSeek, Google Gemini, Mistral** — tramite MCP, llms.txt o chiamate HTTP dirette. Tre modi per integrarlo: scegli in base al tipo di agente:
- **`llms.txt`** — file di discovery per agenti che leggono la documentazione (Cursor IDE, Windsurf, Claude nel browser, pipeline RAG personalizzate con LangChain/LlamaIndex).
- **Server MCP** — zero-code per Claude Desktop, Cursor IDE, Windsurf, VS Code (llm CLI) e qualsiasi client compatibile con MCP (inclusi GPT con MCP tramite OpenAI Realtime API).
- **HTTP API** — chiamata diretta dal tuo agente o framework (LangChain, LlamaIndex, AutoGen, CrewAI).
## llms.txt — discovery per agenti AI
Il sito espone due file machine-readable in formato [llms.txt](https://llmstxt.org/):
- **[`/llms.txt`](https://api.astroway.info/llms.txt)** — indice di tutte le pagine della documentazione raggruppate per sezioni (API Reference, Use Cases, Examples, Products). È piccolo, entra in qualsiasi *context window*.
- **[`/llms-full.txt`](https://api.astroway.info/llms-full.txt)** — contenuto completo della documentazione in un unico file plain-text. Ideale per l'indicizzazione offline in un database vettoriale o per un singolo caricamento nel *context*.
### Quando usarlo
| Scenario | File |
|---|---|
| Cursor/Windsurf: «leggi la docs di AstroWay e aiutami con l'integrazione» | `/llms.txt` (l'agente recupererà automaticamente le sezioni necessarie) |
| Pipeline RAG personalizzata / database vettoriale per un chatbot FAQ | `/llms-full.txt` (un'unica fetch — l'intero corpus) |
| Claude/ChatGPT nel browser: «ecco la nostra API, costruisci un client» | Incolla `/llms-full.txt` nel prompt |
| Agente in produzione con esecuzione di chiamate | Server MCP o HTTP API (vedi sotto) |
### Esempio: pull nella tua applicazione
```ts
const docs = await fetch('https://api.astroway.info/llms-full.txt').then(r => r.text());
const systemPrompt = `You are an integration assistant for AstroWay API.
Documentation:
${docs}
When the user asks how to do X, return a working code snippet using their API key.`;
```
## Server MCP (consigliato per Claude Desktop)
Il Model Context Protocol (MCP) è uno standard aperto per collegare strumenti ai modelli AI. Il server MCP di AstroWay offre 25 strumenti per calcoli e interpretazioni astrologiche.
### Configurazione per Claude Desktop
Aggiungi a `claude_desktop_config.json`:
```json
{
"mcpServers": {
"astroway": {
"command": "npx",
"args": ["@astroway/mcp"],
"env": {
"ASTROWAY_API_KEY": "aw_live_tua_chiave_qui"
}
}
}
}
```
Dopo il riavvio di Claude Desktop, vedrai 25 strumenti astrologici.
### Cosa può fare il server MCP
| Strumento | Funzione |
|---|---|
| `natal_chart` | Calcolo della carta natale |
| `synastry` | Sinastria tra due persone |
| `daily_horoscope` | Oroscopo giornaliero |
| `interpret_natal` | Interpretazione AI della carta natale |
| `human_design` | Carta completa di Human Design |
| `transits` | Transiti attuali |
Lista completa: 25 strumenti che coprono i principali calcoli e interpretazioni AI.
### Esempio di dialogo con Claude
> **Utente:** Costruisci la carta natale di una persona nata il 14 luglio 1990 alle 14:30 a Kiev. Cosa significa il Sole in Cancro nel 10° casa?
>
> **Claude:** *Usa `natal_chart` per il calcolo, poi `interpret_placement` per l'interpretazione. Restituisce le posizioni planetarie con dati reali e un'interpretazione significativa.*
## HTTP API
Per agenti AI senza supporto MCP — usa direttamente l'HTTP API.
### Per la generazione di contenuti
```ts
// L'agente AI chiama /interpret/natal per l'interpretazione
const r = await fetch('https://api.astroway.info/v1/interpret/natal', {
method: 'POST',
headers: {
'X-Api-Key': process.env.ASTROWAY_API_KEY!,
'Content-Type': 'application/json',
},
body: JSON.stringify({
date: '1990-07-14',
time: '14:30:00',
timezoneOffset: 3,
latitude: 50.4501,
longitude: 30.5234,
}),
});
const result = await r.json();
// result.text — interpretazione AI pronta
// result.disclaimer — disclaimer da mostrare
```
```python
r = requests.post(
'https://api.astroway.info/v1/interpret/natal',
headers={'X-Api-Key': os.environ['ASTROWAY_API_KEY']},
json={
'date': '1990-07-14',
'time': '14:30:00',
'timezoneOffset': 3,
'latitude': 50.4501,
'longitude': 30.5234,
},
)
result = r.json()
# result['text'] — interpretazione AI pronta
# result['disclaimer'] — disclaimer da mostrare
```
```bash frame="terminal"
curl -X POST https://api.astroway.info/v1/interpret/natal \
-H "X-Api-Key: $ASTROWAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"date": "1990-07-14",
"time": "14:30:00",
"timezoneOffset": 3,
"latitude": 50.4501,
"longitude": 30.5234
}'
```
```php
'https://api.astroway.info/v1/']);
$r = $aw->post('interpret/natal', [
'headers' => ['X-Api-Key' => getenv('ASTROWAY_API_KEY')],
'json' => [
'date' => '1990-07-14',
'time' => '14:30:00',
'timezoneOffset' => 3,
'latitude' => 50.4501,
'longitude' => 30.5234,
],
]);
$result = json_decode($r->getBody(), true);
// $result['text'] — interpretazione AI pronta
// $result['disclaimer'] — disclaimer da mostrare
```
### Per calcoli + LLM personalizzato
```ts
// 1. Ottieni i dati grezzi tramite /chart (più economico — 20 crediti)
const chart = await fetch('https://api.astroway.info/v1/chart', { ... });
const data = await chart.json();
// 2. Passa i dati al tuo LLM
const prompt = `Interpret this natal chart: ${JSON.stringify(data.planets)}`;
const llmResponse = await myLLM.generate(prompt);
```
## Casi d'uso
### Assistente astrologico personale
Server MCP + Claude/ChatGPT. L'utente chiede — l'agente calcola e interpreta. Budget: piano Free per uso personale.
### Chatbot per contenuti social
Generazione quotidiana di oroscopi per 12 segni tramite `/horoscope/daily`. 12 richieste al giorno = 240 crediti. Piano Free con ampio margine.
### Piattaforma di coaching AI
`/interpret/natal` + `/interpret/transits` per ogni cliente. 100 clienti/giorno = 10.000 crediti/giorno. Piano Pro.