# وكلاء الذكاء الاصطناعي وMCP

تبني وكيل ذكاء اصطناعي يقوم بعمليات حسابية فلكية حقيقية بدلاً من التخيلات؟ AstroWay يتصل بـ **Claude (Anthropic), ChatGPT-4 (OpenAI), Llama 3.3 (Groq), DeepSeek, Google Gemini, Mistral** — عبر MCP، llms.txt، أو استدعاءات HTTP مباشرة. ثلاث طرق للتكامل — اختر حسب نوع وكيلك:

- **`llms.txt`** — ملفات اكتشاف للوكلاء الذين يقرأون الوثائق (Cursor IDE، Windsurf، Claude في المتصفح، خطوط أنابيب RAG المخصصة على LangChain/LlamaIndex).
- **خادم MCP** — بدون كود لـ Claude Desktop، Cursor IDE، Windsurf، VS Code (llm CLI) وأي عميل متوافق مع MCP (بما في ذلك GPT مع MCP عبر OpenAI Realtime API).
- **API HTTP** — الوصول المباشر من وكيلك أو إطارك الخاص (LangChain، LlamaIndex، AutoGen، CrewAI).

## llms.txt — اكتشاف لوكلاء الذكاء الاصطناعي

يعرض الموقع ملفين قابلين للقراءة آليًا بتنسيق [llms.txt](https://llmstxt.org/):

- **[`/llms.txt`](https://api.astroway.info/llms.txt)** — فهرس لجميع صفحات الوثائق مجمعة حسب الأقسام (مرجع API، حالات الاستخدام، أمثلة، المنتجات). صغير الحجم، يتناسب مع أي نافذة سياق.
- **[`/llms-full.txt`](https://api.astroway.info/llms-full.txt)** — محتوى الوثائق كاملاً كنص عادي في ملف واحد. مناسب للفهرسة غير المتصلة بالإنترنت في قاعدة بيانات متجهية أو حقن لمرة واحدة في السياق.

### متى تستخدم

| السيناريو | الملف |
|---|---|
| Cursor/Windsurf: "اقرأ وثائق AstroWay وساعدني في التكامل" | `/llms.txt` (سيحصل الوكيل على الأقسام اللازمة بنفسه) |
| خط أنابيب RAG/قاعدة بيانات متجهة لروبوت الأسئلة الشائعة | `/llms-full.txt` (جلب واحد — المحتوى بالكامل) |
| Claude/ChatGPT في المتصفح: "إليك APIنا، ابنِ عميلاً" | الصق `/llms-full.txt` في السياق |
| وكيل إنتاجي ينفذ استدعاءات | خادم MCP أو API HTTP (انظر أدناه) |

### مثال: سحب إلى وكيلك الخاص

```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">
يتم إعادة توليد الملفات تلقائيًا مع كل إصدار للموقع. الضمان: يتطابق إصدار API في نهاية `/llms.txt` مع الإصدار الحالي من الإنتاج.
</Aside>

## خادم MCP (موصى به لـ Claude Desktop)

بروتوكول سياق النموذج (MCP) — معيار مفتوح لربط الأدوات بنماذج الذكاء الاصطناعي. يوفر خادم 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` | حساب الخريطة Natal |
| `synastry` | السيناستري لشخصين |
| `daily_horoscope` | الأبراج اليومية |
| `interpret_natal` | تفسير خريطة Natal بواسطة الذكاء الاصطناعي |
| `human_design` | خريطة التصميم البشري الكاملة |
| `transits` | الترانزيت الحالي |

القائمة الكاملة تحتوي على 25 أداة تغطي الحسابات الأساسية والتفسيرات بواسطة الذكاء الاصطناعي.

### مثال حوار مع Claude

> **المستخدم:** ابنِ خريطة Natal لشخص ولد في 14 يوليو 1990 الساعة 14:30 في كييف. ماذا تعني الشمس في السرطان في البيت العاشر؟
>
> **Claude:** *يستخدم `natal_chart` للحساب، ثم `interpret_placement` للتفسير. يعيد مواقع الكواكب بالبيانات الحقيقية وتفسيراً معقولاً.*

## API HTTP

للعملاء الذين لا يدعمون MCP — استخدم API HTTP مباشرة.

### لتوليد المحتوى

<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 — التفسير جاهز بواسطة الذكاء الاصطناعي
    // result.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'] — التفسير جاهز بواسطة الذكاء الاصطناعي
    # result['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']       — التفسير جاهز بواسطة الذكاء الاصطناعي
    // $result['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>

## السيناريوهات

### مساعد فلكي شخصي

خادم MCP + Claude/ChatGPT. يسأل المستخدم — يحسب الوكيل ويفسر. الميزانية: خطة مجانية للاستخدام الشخصي.

### بوت محتوى للتواصل الاجتماعي

توليد أبراج يومية لـ 12 علامة عبر `/horoscope/daily`. 12 طلب يومياً = 240 نقطة. خطة مجانية مع هامش كبير.

### منصة تدريب الذكاء الاصطناعي

`/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="تفسيرات وأبراج بواسطة الذكاء الاصطناعي" />
  <LinkCard title="الخطط" href="/pricing/" description="من مجاني إلى Enterprise" />
</CardGrid>