# Agentes de IA e MCP
Estás a construir um agente de IA que faz cálculos astrológicos reais em vez de alucinações? O **AstroWay** conecta-se ao **Claude (Anthropic), ChatGPT-4 (OpenAI), Llama 3.3 (Groq), DeepSeek, Google Gemini, Mistral** — via MCP, arquivos `llms.txt` ou chamadas HTTP diretas. Três formas de integração — escolhe conforme o tipo de agente:
- **`llms.txt`** — arquivos de descoberta para agentes que leem documentação (Cursor IDE, Windsurf, Claude no navegador, pipelines RAG personalizados em LangChain/LlamaIndex).
- **Servidor MCP** — zero-code para o Claude Desktop, Cursor IDE, Windsurf, VS Code (CLI llm) e qualquer cliente compatível com MCP (incluindo GPT com MCP via OpenAI Realtime API).
- **HTTP API** — chamada direta do teu agente ou framework (LangChain, LlamaIndex, AutoGen, CrewAI).
## llms.txt — descoberta para agentes de IA
O site expõe dois arquivos legíveis por máquinas no formato [llms.txt](https://llmstxt.org/):
- **[`/llms.txt`](https://api.astroway.info/llms.txt)** — índice de todas as páginas da documentação agrupadas por secções (API Reference, Use Cases, Examples, Products). Pequeno, cabe em qualquer *context window*.
- **[`/llms-full.txt`](https://api.astroway.info/llms-full.txt)** — todo o conteúdo da documentação num único arquivo de texto simples. Ideal para indexação offline em base de dados vetorial ou injeção única no *context*.
### Quando usar
| Cenário | Arquivo |
|---|---|
| Cursor/Windsurf: «lê a documentação do AstroWay e ajuda com a integração» | `/llms.txt` (o agente puxa as secções necessárias sozinho) |
| Pipeline RAG personalizado / base de dados vetorial para um FAQ bot | `/llms-full.txt` (um fetch — todo o corpus) |
| Claude/ChatGPT no navegador: «aqui está a nossa API, constrói um cliente» | Colar `/llms-full.txt` na *prompt* |
| Agente de produção com execução de chamadas | Servidor MCP ou HTTP API (ver abaixo) |
### Exemplo: puxar para o teu agente
```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.`;
```
## Servidor MCP (recomendado para o Claude Desktop)
O *Model Context Protocol* (MCP) é um padrão aberto para conectar ferramentas a modelos de IA. O servidor MCP do AstroWay disponibiliza 25 ferramentas para cálculos e interpretações astrológicas.
### Configuração para o Claude Desktop
Adiciona ao `claude_desktop_config.json`:
```json
{
"mcpServers": {
"astroway": {
"command": "npx",
"args": ["@astroway/mcp"],
"env": {
"ASTROWAY_API_KEY": "aw_live_your_key_here"
}
}
}
}
```
Após reiniciares o Claude Desktop, vais ver 25 ferramentas astrológicas.
### O que o servidor MCP oferece
| Ferramenta | O que faz |
|---|---|
| `natal_chart` | Cálculo de carta natal |
| `synastry` | Sinastria de duas pessoas |
| `daily_horoscope` | Horóscopo diário |
| `interpret_natal` | Interpretação de carta natal com IA |
| `human_design` | Carta completa de Design Humano |
| `transits` | Trânsitos atuais |
São 25 ferramentas que cobrem os principais cálculos e interpretações com IA.
### Exemplo de diálogo com o Claude
> **Utilizador:** Constrói uma carta natal para uma pessoa nascida a 14 de julho de 1990 às 14:30 em Kiev. O que significa o Sol em Caranguejo na 10ª casa?
>
> **Claude:** *Usa a `natal_chart` para o cálculo e depois a `interpret_placement` para a interpretação. Devolve as posições planetárias com dados reais e uma interpretação significativa.*
## HTTP API
Para agentes de IA sem suporte a MCP — usa a HTTP API diretamente.
### Para geração de conteúdo
```ts
// Agente de IA chama /interpret/natal para interpretação
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 — interpretação pronta com IA
// result.disclaimer — aviso a ser exibido
```
```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'] — interpretação pronta com IA
# result['disclaimer'] — aviso a ser exibido
```
```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'] — interpretação pronta com IA
// $result['disclaimer'] — aviso a ser exibido
```
### Para cálculos + LLM próprio
```ts
// 1. Obtém dados brutos via /chart (mais barato — 20 créditos)
const chart = await fetch('https://api.astroway.info/v1/chart', { ... });
const data = await chart.json();
// 2. Passa os dados para o teu LLM
const prompt = `Interpret this natal chart: ${JSON.stringify(data.planets)}`;
const llmResponse = await myLLM.generate(prompt);
```
## Cenários
### Assistente astrológico pessoal
Servidor MCP + Claude/ChatGPT. O utilizador pergunta — o agente calcula e interpreta. Orçamento: Plano Free para uso pessoal.
### Bot de conteúdo para redes sociais
Geração diária de horóscopos para 12 signos via `/horoscope/daily`. 12 pedidos por dia = 240 créditos. O Plano Free tem grande margem.
### Plataforma de coaching com IA
`/interpret/natal` + `/interpret/transits` para cada cliente. 100 clientes/dia = 10 000 créditos/dia. Plano Pro.