# Agenți AI și MCP
Construiești un agent AI care să facă calcule astrologice reale în loc să halucineze? AstroWay se conectează la **Claude (Anthropic), ChatGPT-4 (OpenAI), Llama 3.3 (Groq), DeepSeek, Google Gemini, Mistral** — prin MCP, fișiere llms.txt sau apeluri HTTP directe. Trei moduri de integrare — alege în funcție de tipul agentului tău:
- **`llms.txt`** — fișiere de descoperire pentru agenți care citesc documentația (Cursor IDE, Windsurf, Claude în browser, pipeline-uri RAG personalizate pe LangChain/LlamaIndex).
- **Server MCP** — zero-code pentru Claude Desktop, Cursor IDE, Windsurf, VS Code (llm CLI) și orice client compatibil MCP (inclusiv GPT cu MCP prin OpenAI Realtime API).
- **HTTP API** — apel direct din propriul agent sau framework (LangChain, LlamaIndex, AutoGen, CrewAI).
## llms.txt — descoperire pentru agenți AI
Site-ul expune două fișiere machine-readable în format [llms.txt](https://llmstxt.org/):
- **[`/llms.txt`](https://api.astroway.info/llms.txt)** — indexul tuturor paginilor de documentație grupate pe secțiuni (API Reference, Use Cases, Examples, Products). Mic, încăpe în orice context window.
- **[`/llms-full.txt`](https://api.astroway.info/llms-full.txt)** — conținutul întregii documentații într-un singur fișier text simplu. Potrivit pentru indexare offline în baze de date vectoriale sau încărcare unică în context.
### Când să le folosești
| Scenariu | Fișier |
|---|---|
| Cursor/Windsurf „citește docs astroway și ajută cu integrarea” | `/llms.txt` (agentul va prelua singur secțiunile necesare) |
| Pipeline RAG personalizat / bază de date vectorială pentru un bot de FAQ | `/llms-full.txt` (un singur fetch — tot corpusul) |
| Claude/ChatGPT în browser: „iată API-ul nostru, construiește un client” | `/llms-full.txt` lipit în prompt |
| Agent de producție care face apeluri | Server MCP sau HTTP API (vezi mai jos) |
### Exemplu: pull în propriul agent
```ts
const docs = await fetch('https://api.astroway.info/llms-full.txt').then(r => r.text());
const systemPrompt = `Ești un asistent de integrare pentru API-ul AstroWay.
Documentație:
${docs}
Când utilizatorul întreabă cum să facă X, returnează un snippet de cod funcțional folosind cheia lui API.`;
```
## Server MCP (recomandat pentru Claude Desktop)
Model Context Protocol (MCP) este un standard deschis pentru conectarea instrumentelor la modele AI. Serverul MCP AstroWay oferă 25 de instrumente pentru calcule și interpretări astrologice.
### Configurare pentru Claude Desktop
Adaugă în `claude_desktop_config.json`:
```json
{
"mcpServers": {
"astroway": {
"command": "npx",
"args": ["@astroway/mcp"],
"env": {
"ASTROWAY_API_KEY": "aw_live_your_key_here"
}
}
}
}
```
După repornirea lui Claude Desktop, vei vedea cele 25 de instrumente astrologice.
### Ce poate face serverul MCP
| Instrument | Ce face |
|---|---|
| `natal_chart` | Calculul hărții natale |
| `synastry` | Sinastria a două persoane |
| `daily_horoscope` | Horoscop zilnic |
| `interpret_natal` | Interpretare AI a hărții natale |
| `human_design` | Hartă completă HD |
| `transits` | Tranzite curente |
Lista completă include 25 de instrumente care acoperă calculele de bază și interpretările AI.
### Exemplu de dialog cu Claude
> **Utilizator:** Construiește-mi harta natală pentru o persoană născută pe 14 iulie 1990 la 14:30 în Kiev. Ce înseamnă Soarele în Rac în casa a 10-a?
>
> **Claude:** *Folosește `natal_chart` pentru calcul, apoi `interpret_placement` pentru interpretare. Returnează pozițiile planetelor cu date reale și o interpretare semnificativă.*
## HTTP API
Pentru agenți AI fără suport MCP — folosește HTTP API-ul direct.
### Pentru generare de conținut
```ts
// Agentul AI apelează /interpret/natal pentru interpretare
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 — interpretare AI gata
// result.disclaimer — disclaimer pentru afișare
```
```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'] — interpretare AI gata
# result['disclaimer'] — disclaimer pentru afișare
```
```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'] — interpretare AI gata
// $result['disclaimer'] — disclaimer pentru afișare
```
### Pentru calcule + propriul LLM
```ts
// 1. Obține datele brute prin /chart (mai ieftin — 20 de credite)
const chart = await fetch('https://api.astroway.info/v1/chart', { ... });
const data = await chart.json();
// 2. Trimite datele către propriul LLM
const prompt = `Interpretează această hartă natală: ${JSON.stringify(data.planets)}`;
const llmResponse = await myLLM.generate(prompt);
```
## Scenarii
### Asistent astrologic personal
Server MCP + Claude/ChatGPT. Utilizatorul întreabă — agentul calculează și interpretează. Buget: planul Free pentru utilizare personală.
### Bot de conținut pentru rețele sociale
Generare zilnică de horoscop pentru cele 12 zodii prin `/horoscope/daily`. 12 cereri pe zi = 240 de credite. Planul Free are un stoc mare.
### Platformă de coaching AI
`/interpret/natal` + `/interpret/transits` pentru fiecare client. 100 de clienți/zi = 10.000 de credite/zi. Planul Pro.