# Agenci AI i MCP
Budujesz AI-agneta, który ma wykonywać prawdziwe obliczenia astrologiczne zamiast halucynacji? AstroWay integruje się z **Claude (Anthropic), ChatGPT-4 (OpenAI), Llama 3.3 (Groq), DeepSeek, Google Gemini, Mistral** — przez MCP, pliki `llms.txt` lub bezpośrednie wywołania HTTP. Trzy sposoby integracji — wybierz odpowiedni dla swojego agenta:
- **`llms.txt`** — pliki discovery dla agentów, które czytają dokumentację (Cursor IDE, Windsurf, Claude w przeglądarce, własne pipeline RAG na LangChain/LlamaIndex).
- **Serwer MCP** — zero-code dla Claude Desktop, Cursor IDE, Windsurf, VS Code (llm CLI) i każdego klienta zgodnego z MCP (w tym GPT z MCP przez OpenAI Realtime API).
- **HTTP API** — bezpośrednie wywołanie z własnego agenta lub frameworka (LangChain, LlamaIndex, AutoGen, CrewAI).
## Pliki `llms.txt` — discovery dla AI-agentów
Strona udostępnia dwa maszynowo czytelne pliki w formacie [llms.txt](https://llmstxt.org/):
- **[`/llms.txt`](https://api.astroway.info/llms.txt)** — indeks wszystkich stron dokumentacji pogrupowany w sekcje (API Reference, Use Cases, Examples, Products). Mały rozmiar, mieści się w każdym oknie kontekstu.
- **[`/llms-full.txt`](https://api.astroway.info/llms-full.txt)** — cała treść dokumentacji w jednym pliku plain-text. Idealny do offline’owego indeksowania w bazie wektorowej lub jednorazowego wstrzyknięcia do kontekstu.
### Kiedy używać
| Scenariusz | Plik |
|---|---|
| Cursor/Windsurf „przeczytaj docs astroway i pomóż z integracją” | `/llms.txt` (agent sam pobierze potrzebne sekcje) |
| Własny pipeline RAG / baza wektorowa dla FAQ-bota | `/llms-full.txt` (jeden fetch — cały korpus) |
| Claude/ChatGPT w przeglądarce: „oto nasze API, zbuduj klienta” | `/llms-full.txt` wklejony w prompt |
| Produkcyjny agent z wywołaniami API | Serwer MCP lub HTTP API (patrz poniżej) |
### Przykład: pobieranie do własnego agenta
```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.`;
```
## Serwer MCP (zalecany dla Claude Desktop)
Model Context Protocol (MCP) to otwarty standard do podłączania narzędzi do modeli AI. Serwer MCP AstroWay udostępnia 25 narzędzi do obliczeń i interpretacji.
### Konfiguracja dla Claude Desktop
Dodaj do `claude_desktop_config.json`:
```json
{
"mcpServers": {
"astroway": {
"command": "npx",
"args": ["@astroway/mcp"],
"env": {
"ASTROWAY_API_KEY": "aw_live_your_key_here"
}
}
}
}
```
Po restarcie Claude Desktop zobaczysz 25 astrologicznych narzędzi.
### Co potrafi serwer MCP
| Narzędzie | Co robi |
|---|---|
| `natal_chart` | Obliczanie horoskopu urodzeniowego |
| `synastry` | Synastria dwóch osób |
| `daily_horoscope` | Dzienny horoskop |
| `interpret_natal` | AI-interpretacja horoskopu urodzeniowego |
| `human_design` | Pełna karta Human Design |
| `transits` | Aktualne tranzyty |
Pełna lista — 25 narzędzi pokrywających podstawowe obliczenia i AI-interpretacje.
### Przykład dialogu z Claude
> **Użytkownik:** Stwórz horoskop urodzeniowy dla osoby urodzonej 14 lipca 1990 o 14:30 w Kijowie. Co oznacza Słońce w Raku w 10 domu?
>
> **Claude:** *Używa `natal_chart` do obliczeń, następnie `interpret_placement` do interpretacji. Zwraca pozycje planet z rzeczywistymi danymi i sensowną interpretację.*
## HTTP API
Dla AI-agentów bez wsparcia MCP — użyj bezpośrednio HTTP API.
### Do generowania treści
```ts
// AI-agent wywołuje /interpret/natal do interpretacji
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 — gotowa AI-interpretacja
// result.disclaimer — disclaimer do wyświetlenia
```
```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'] — gotowa AI-interpretacja
# result['disclaimer'] — disclaimer do wyświetlenia
```
```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'] — gotowa AI-interpretacja
// $result['disclaimer'] — disclaimer do wyświetlenia
```
### Do obliczeń + własny LLM
```ts
// 1. Pobierz surowe dane przez /chart (tańsze — 20 kredytów)
const chart = await fetch('https://api.astroway.info/v1/chart', { ... });
const data = await chart.json();
// 2. Przekaż dane do swojego LLM
const prompt = `Interpret this natal chart: ${JSON.stringify(data.planets)}`;
const llmResponse = await myLLM.generate(prompt);
```
## Scenariusze
### Osobisty asystent astrologiczny
Serwer MCP + Claude/ChatGPT. Użytkownik pyta — agent oblicza i interpretuje. Budżet: darmowy plan dla użytku osobistego.
### Bot do treści w mediach społecznościowych
Codzienna generacja horoskopów dla 12 znaków przez `/horoscope/daily`. 12 zapytań dziennie = 240 kredytów. Darmowy plan z dużym zapasem.
### Platforma AI-coaching
`/interpret/natal` + `/interpret/transits` dla każdego klienta. 100 klientów/dzień = 10 000 kredytów/dzień. Plan Pro.