# AI 에이전트 및 MCP

AI 에이전트를 만들고 Claude (Anthropic), ChatGPT-4 (OpenAI), Llama 3.3 (Groq), DeepSeek, Google Gemini, Mistral과 같은 모델이 진짜 천문 계산으로 환각 대신 실제 결과를 내놓도록 하세요. AstroWay는 MCP, `llms.txt`, 또는 직접 HTTP 호출을 통해 3가지 방식으로 통합할 수 있습니다. 에이전트 유형에 따라 방법을 선택하세요:

- **`llms.txt`** — 에이전트가 문서를 읽는 discovery 파일 (Cursor IDE, Windsurf, 브라우저 Claude, LangChain/LlamaIndex 기반 커스텀 RAG 파이프라인용).
- **MCP 서버** — Claude Desktop, Cursor IDE, Windsurf, VS Code (llm CLI), OpenAI Realtime API를 통한 GPT 등 모든 MCP 호환 클라이언트용 (zero-code).
- **HTTP API** — 자체 에이전트나 LangChain, LlamaIndex, AutoGen, CrewAI 같은 프레임워크에서 직접 호출.

## llms.txt — AI 에이전트를 위한 discovery

사이트는 [llms.txt](https://llmstxt.org/) 형식의 두 가지 기계 판독 가능한 파일을 제공합니다:

- **[`/llms.txt`](https://api.astroway.info/llms.txt)** — API 레퍼런스, 사용 사례, 예제, 제품 등 문서 섹션별로 그룹화된 색인. 작고 모든 context window에 들어갑니다.
- **[`/llms-full.txt`](https://api.astroway.info/llms-full.txt)** — 전체 문서를 하나의 plain-text 파일로 제공. 오프라인 벡터 DB 인덱싱이나 한 번의 프롬프트 삽입용으로 적합합니다.

### 언제 어떤 파일을 쓸까?

| 시나리오 | 파일 |
|---|---|
| Cursor/Windsurf에서 "astroway docs 읽고 integration 도와줘" | `/llms.txt` (에이전트가 필요한 섹션만 자동으로 가져옴) |
| 자체 RAG 파이프라인 / FAQ 봇용 벡터 DB | `/llms-full.txt` (한 번의 fetch로 전체 corpus 확보) |
| 브라우저 Claude/ChatGPT에서 "이 API로 클라이언트 만들어줘" | `/llms-full.txt`를 프롬프트에 붙여넣기 |
| 실제 API 호출을 수행하는 프로덕션 에이전트 | 아래의 MCP 서버 또는 HTTP API (아래 참조) |

### 예시: 에이전트에 파일 가져오기

```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.`;
```

<Aside type="note">
파일은 사이트 릴리스 시 자동으로 재생성됩니다. `/llms.txt` 끝에 있는 API 버전 번호가 현재 프로덕션 deploy와 일치해 최신 상태를 보장합니다.
</Aside>

## MCP 서버 (Claude Desktop 권장)

Model Context Protocol(MCP)는 AI 모델에 도구를 연결하기 위한 개방형 표준입니다. AstroWay MCP 서버는 계산과 해석을 위한 25가지 도구를 제공합니다.

### Claude Desktop 설정

`claude_desktop_config.json`에 다음을 추가하세요:

```json
{
  "mcpServers": {
    "astroway": {
      "command": "npx",
      "args": ["@astroway/mcp"],
      "env": {
        "ASTROWAY_API_KEY": "aw_live_your_key_here"
      }
    }
  }
}
```

Claude Desktop을 재시작하면 25가지 천문 계산 도구가 표시됩니다.

### MCP 서버가 제공하는 도구

| 도구 | 기능 |
|---|---|
| `natal_chart` | 출생 차트 계산 |
| `synastry` | 시너스트리(두 사람의 비교) |
| `daily_horoscope` | 일일 호로스코프 |
| `interpret_natal` | 출생 차트 AI 해석 |
| `human_design` | 휴먼 디자인 전체 차트 |
| `transits` | 현재 트랜짓 |

총 25가지 도구로 주요 계산과 AI 해석을 모두 커버합니다.

### Claude와의 대화 예시

> **사용자:** 1990년 7월 14일 14:30에 키예프에서 태어난 사람의 출생 차트를 그려줘. 10번째 houses에 위치한 Cancer의 태양은 무엇을 의미해?
>
> **Claude:** *`natal_chart`로 차트를 계산한 후 `interpret_placement`으로 해석합니다. 실제 데이터로 행성 위치를 반환하고 의미를 제공합니다.*

## HTTP API

MCP를 지원하지 않는 에이전트의 경우 직접 HTTP API를 사용하세요.

### 콘텐츠 생성용

<Tabs syncKey="lang">
  <TabItem label="TypeScript">
    ```ts
    // 에이전트가 /interpret/natal을 호출해 해석 생성
    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 — 완료된 AI 해석
    // result.disclaimer — 표시용 disclaimer
    ```
  </TabItem>
  <TabItem label="Python">
    ```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'] — 완료된 AI 해석
    # result['disclaimer'] — 표시용 disclaimer
    ```
  </TabItem>
  <TabItem label="cURL">
    ```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
      }'
    ```
  </TabItem>
  <TabItem label="PHP">
    ```php
    <?php
    use GuzzleHttp\Client;

    $aw = new Client(['base_uri' => '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']       — 완료된 AI 해석
    // $result['disclaimer'] — 표시용 disclaimer
    ```
  </TabItem>
</Tabs>

### 계산 + 자체 LLM 사용

```ts
// 1. /chart를 호출해 원시 데이터 확보 (더 저렴함 — 20 크레딧)
const chart = await fetch('https://api.astroway.info/v1/chart', { ... });
const data = await chart.json();

// 2. 데이터를 자체 LLM에 전달
const prompt = `Interpret this natal chart: ${JSON.stringify(data.planets)}`;
const llmResponse = await myLLM.generate(prompt);
```

<Aside type="tip">
단순히 해석이 필요하다면 `/interpret/*` (50 크레딧, 텍스트 완성)를 사용하세요. 프롬프트를 직접 제어하고 싶다면 `/chart` (20 크레딧)를 사용해 데이터를 자체 LLM에 전달하세요.
</Aside>

## 사용 시나리오

### 개인용 점성술 AI 어시스턴트

MCP 서버 + Claude/ChatGPT. 사용자가 질문하면 에이전트가 계산하고 해석합니다. 개인 사용자용 무료 요금제.

### 소셜 미디어용 콘텐츠 봇

매일 12궁 daily гороскоп을 `/horoscope/daily`로 생성. 하루 12회 호출 = 240 크레딧. 무료 요금제로 충분한 여유.

### AI 코칭 플랫폼

각 클라이언트별로 `/interpret/natal`과 `/interpret/transits` 사용. 하루 100명 클라이언트 = 하루 10,000 크레딧. Pro 요금제.

<CardGrid>
  <LinkCard title="빠른 시작 →" href="/getting-started/" description="5분 만에 첫 요청" />
  <LinkCard title="Horoscope API" href="/products/horoscope-api/" description="AI 해석과 호로스코프" />
  <LinkCard title="요금제" href="/pricing/" description="무료부터 Enterprise까지" />
</CardGrid>