# MCP - الاتصال ب Claude / Cursor

خادم بروتوكول سياق النموذج AstroWay يعرض **جميع {siteMeta.endpoints} من نقاط نهاية** كأدوات لوكيل الذكاء الاصطناعي. يدعم النظام وضعين — وكلاهما مدعومان أصليًا من قبل جميع عملاء MCP المتوافقين.

| الوضع | الرابط / الأمر | متى تختار هذا |
|---|---|---|
| **HTTP المستضاف** | `https://mcp.astroway.info/mcp` | Claude على الويب (claude.ai في المتصفح)، أو Claude Desktop / Cursor / Code للمبتدئين بدون npm، أو عندما تريد تثبيتًا بدون خطوات |
| **Stdio (npm)** | `npx @astroway/mcp` | مستخدمو Cursor المتقدمون، التطوير المحلي، المهتمون بالخصوصية (لن يغادر المفتاح جهازك أبدًا)، جاهز للعمل دون اتصال |

نفس نقطة النهاية المستضافة وحزمة npm تستخدم **نفس كتالوج الأدوات** (يتم إنشاؤه من ملف `/v1/openapi.json` واحد). المصادقة: نفس مفتاح API `aw_test_*` / `aw_live_*` — في المستضاف يتم إرساله عبر `Authorization: Bearer …` header، وفي stdio عبر متغير البيئة `ASTROWAY_API_KEY`.

Source: [github.com/astroway/astroway-mcp](https://github.com/astroway/astroway-mcp) · npm: [npmjs.com/package/@astroway/mcp](https://www.npmjs.com/package/@astroway/mcp) · hosted: [mcp.astroway.info/health](https://mcp.astroway.info/health)

## المستضاف (`mcp.astroway.info`) — بدون تثبيت

بدء سريع بدون npm — اختر عميلك. قبل التثبيت، احصل على مفتاحك من [api.astroway.info/dashboard/sign-up](https://api.astroway.info/dashboard/sign-up) (10,000 رصيد/شهر مجانًا).

<Tabs syncKey="mcp-client">
<TabItem label="Cursor (نقرة واحدة)">

انقر الزر — سيفتح Cursor، ويطلب منك التأكيد، وسيضيف السجل تلقائيًا:

<a href="cursor://anysphere.cursor-deeplink/mcp/install?name=astroway-hosted&config=eyJ1cmwiOiJodHRwczovL21jcC5hc3Ryb3dheS5pbmZvL21jcCIsImhlYWRlcnMiOnsiQXV0aG9yaXphdGlvbiI6IkJlYXJlciBZT1VSX0FQSV9LRVkifX0" style="display:inline-block;padding:0.5rem 1rem;background:#d4a84c;color:#0a0b1e;border-radius:0.375rem;font-weight:600;text-decoration:none;">Install in Cursor →</a>

:::caution[الخطوة الثانية إلزامية — وإلا لن يعمل]
Cursor لا يستطيع استبدال السري من deep link — سيتم كتابة `Bearer YOUR_API_KEY` حرفيًا في `~/.cursor/mcp.json`، مما يؤدي إلى استجابة الخادم بـ `403 invalid_format`.

**بعد النقر على الزر:**
1. **إعدادات Cursor** (⚙️ في الزاوية العلوية اليمنى) → **الأدوات & MCP** → ابحث عن `astroway-hosted` في القائمة.
2. انقر على النقاط الثلاث (`⋯`) بجوار الخادم → **تعديل التكوين**.
3. في حقل `Authorization`، استبدل `Bearer YOUR_API_KEY` بـ `Bearer aw_test_…` (أو `aw_live_…`) — مفتاحك الفعلي من [Dashboard](https://api.astroway.info/dashboard/keys).
4. احفظ → افتح قائمة MCP مرة أخرى وتأكد من أن الحالة **enabled** + نقطة خضراء + عداد `630 tools enabled`.

بديلاً عن ذلك، يمكنك تعديل الملف مباشرة: `~/.cursor/mcp.json` (`headers.Authorization`).
:::

<Aside type="note">
يفرض Cursor حدًا على طول الأسماء: `server_name:tool_name` ≤ 60 حرفًا. حوالي 50 من أصل 630 أداة (مجموعات `hellenistic_brennan_*`, `psychological_modern_*`, `numerology_kabbalistic_strict_*`) يتم تصفيتها بواسطة Cursor وغير متاحة عبر LLM. الأدوات الـ 580 الأخرى تعمل. في Claude Desktop لا يوجد مثل هذا الحد — الكتالوج الكامل متاح.
</Aside>

</TabItem>
<TabItem label="Claude Desktop (تدفق واجهة المستخدم)">

بدون تعديل ملف JSON. في أي دردشة في Claude Desktop:

1. انقر على **`+`** على اليسار من حقل الإدخال → اختر **"إضافة موصل"** من القائمة.
2. في مربع الحوار، اختر **"إضافة موصل مخصص"**.
3. **الاسم:** `astroway-hosted`
4. **الرابط:** `https://mcp.astroway.info/mcp`
5. افتح **"الإعدادات المتقدمة"** → في **"الروؤس المخصصة"** أضف:
   - **المفتاح:** `Authorization`
   - **القيمة:** `Bearer aw_live_...` (مفتاحك)
6. **إضافة** → ابحث عن `astroway-hosted` في قائمة الموصلات، وقم بتشغيل التبديل.

لا داعي لإعادة تشغيل Claude Desktop. انقر على `+` في دردشة جديدة — ستظهر `astroway-hosted` في الموصلات مع جميع الأدوات الـ 630 + 12 موجه + 14 مورد.

</TabItem>
<TabItem label="تكوين JSON (يدوي)">

لـ Cline / Continue / Windsurf أو إصدارات قديمة من Claude Desktop / Cursor:

```json
{
  "mcpServers": {
    "astroway-hosted": {
      "url": "https://mcp.astroway.info/mcp",
      "headers": {
        "Authorization": "Bearer aw_live_..."
      }
    }
  }
}
```

مسارات التكوين:
- **Claude Desktop (macOS):** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Claude Desktop (Windows):** `%APPDATA%\Claude\claude_desktop_config.json`
- **Cursor:** `~/.cursor/mcp.json` (عالميًا) أو `.cursor/mcp.json` (في مساحة العمل)
- **Cline (VS Code):** `.cline/mcp.json` في مساحة العمل
- **Continue:** `~/.continue/config.json` (كتلة `mcpServers`)
- **Windsurf:** `~/.codeium/windsurf/mcp_config.json`

بعد التعديل، أعد تشغيل العميل تمامًا (Cmd+Q → افتح مجددًا).

</TabItem>
</Tabs>

### التحقق

```bash
curl https://mcp.astroway.info/health
# {"status":"ok","version":"…","uptime_sec":…,"mcp_protocol_version":"2024-11-05"}
```

في العميل — اطلب من الذكاء الاصطناعي: *"List 5 AstroWay tool names from astroway-hosted"*. يجب أن يعيد أسماء مثل `astroway_western_chart`, `astroway_horoscope_daily`, `astroway_vedic_panchang_full`, …

### حدود المعدل

يتم حماية نقطة النهاية المستضافة بثلاث طبقات من القيود: Cloudflare DDoS + nginx `120 طلب/دقيقة/IP` + bucket في الذاكرة `60/60 ثانية/(IP+مفتاح)`. لا يقترب العملاء MCP الحقيقيون (Claude Desktop، Cursor) من هذه الحدود — فهم لا يقومون بإرسال طلبات دفعة واحدة. إذا احتاجت أتمتتك / CI إلى > 120 طلب/دقيقة — استخدم وضع **stdio** (لا توجد حدود هناك، يتصل مباشرة بـ `api.astroway.info/v1/*` مع حد معدل الاشتراك الخاص بك).

### ماذا لو كان `mcp.astroway.info` غير متاح مؤقتًا

إذا عادت نقطة النهاية المستضافة بـ 5xx، سيرى عميل MCP خطأ عند `tools/list`. هذا **لا يؤثر** على عملاء stdio — فهم يشغلون الحزمة المحلية npm التي تتصل مباشرة بـ `api.astroway.info/v1/*` بدون طبقة وسيطة مستضافة.

**البديل الاحتياطي للتكاملات الحرجة:** أضف **خادم MCP ثانٍ** في التكوين بوضع stdio — سيستخدمه العميل تلقائيًا إذا لم يستجب المستضاف لـ `tools/list`:

```json
{
  "mcpServers": {
    "astroway": {
      "url": "https://mcp.astroway.info/mcp",
      "headers": { "Authorization": "Bearer aw_live_..." }
    },
    "astroway-fallback": {
      "command": "npx",
      "args": ["-y", "@astroway/mcp"],
      "env": { "ASTROWAY_API_KEY": "aw_live_..." }
    }
  }
}
```

يمكنك رؤية وقت التشغيل الفعلي لنقطة النهاية المستضافة على [status.astroway.info](https://status.astroway.info). يتم نشر الحوادث التي تستمر أكثر من 5 دقائق كمشاكل ما بعد الحادث خلال 5 أيام عمل (وفقًا لـ [/sla/](/sla/)).

## Stdio (npm) — للتطوير المحلي

حزمة [`@astroway/mcp`](https://www.npmjs.com/package/@astroway/mcp) npm هي حزمة npm تعمل محليًا كعملية فرعية. حزمة npm واحدة، تكامل أصلي مع Claude Desktop وCursor وأي عميل MCP متوافق.

## كيف يعمل

يتم إنشاء قائمة الأدوات **عند وقت البناء** من مواصفات OpenAPI الحية ([api.astroway.info/v1/openapi.json](https://api.astroway.info/v1/openapi.json)). تلتقط كل إصدار من الحزمة تلقائيًا جميع نقاط النهاية الجديدة — لا داعي للصيانة اليدوية.

كل نقطة نهاية تصبح أداة على الشكل:
- `tools/list` يعيد وصفًا ومخطط الإدخال (مع مثال لجسم الطلب)
- `tools/call` يقوم بإرسال POST HTTP إلى `https://api.astroway.info/v1/<path>` باستخدام `ASTROWAY_API_KEY` الخاص بك
- يتم إرجاع الاستجابة للوكيل كـ JSON منظم

يتم شحن كل إصدار أيضًا مع مصداقية SLSA ([موقعة من Sigstore](https://search.sigstore.dev/)) — وهذا ضمان بأن حزمة npm مبنية من commit في repo العام.

## التثبيت

### Claude Desktop (macOS)

أضف إلى `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "astroway": {
      "command": "npx",
      "args": ["-y", "@astroway/mcp"],
      "env": {
        "ASTROWAY_API_KEY": "aw_live_..."
      }
    }
  }
}
```

أعد تشغيل Claude Desktop. ستظهر أيقونة 🛠️ في شريط الدردشة مع عدد الأدوات التي تم تحميلها.

### Cursor

أضف إلى `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "astroway": {
      "command": "npx",
      "args": ["-y", "@astroway/mcp"],
      "env": { "ASTROWAY_API_KEY": "aw_live_..." }
    }
  }
}
```

### Cline / Continue / Windsurf / Copilot / VS Code MCP

تعمل نفس أمر `npx @astroway/mcp` في أي عميل MCP متوافق. التكوين متطابق — يتغير فقط مسار الملف:

```json
{
  "mcpServers": {
    "astroway": {
      "command": "npx",
      "args": ["-y", "@astroway/mcp"],
      "env": { "ASTROWAY_API_KEY": "aw_live_..." }
    }
  }
}
```

| العميل | مسار التكوين |
|---|---|
| **Cline** (VS Code) | `.cline/mcp.json` في جذر مساحة العمل |
| **Continue** | `~/.continue/config.json` (تحت `mcpServers`) |
| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
| **GitHub Copilot Chat (VS Code)** | العلم المسبق → `mcp.json` في مساحة العمل |
| **VS Code MCP extension** | `~/.vscode/mcp.json` |

### عملاء MCP آخرون

شغل كخادم stdio:

```bash
ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp
```

<Aside type="tip">
احصل على مفتاحك من [api.astroway.info/dashboard/sign-up](https://api.astroway.info/dashboard/sign-up). الطبقة المجانية — **{siteMeta.freeCredits.toLocaleString('en-US').replace(/,/g, ' ')} رصيد/شهر**، بدون بطاقة.
</Aside>

## الخصوصية <span style="opacity:0.6">— من v1.0.0+</span>

هذا الخادم MCP **لا يرسل أي شيء إلى AstroWay** باستثناء استعلامات API التي تطلبها منه تنفيذها. لا توجدテレميتري، ولا تحليلات، ولا أي خيار opt-in/opt-out — الهدوء هو الافتراضي.

تحمل الاستعلامات الصادرة علامتي تعريف حتى يتمكن backend AstroWay من تمييز حركة مرور MCP عن HTTP المباشر في سجلاته الخاصة:

- `User-Agent: astroway-mcp/<version> (Node/<node-version>)`
- `X-Astroway-Channel: mcp`

لا يحتوي أي منهما على session ID أو بصمة جهاز أو أي شيء شخصي. هذه هي semantics User-Agent القياسية — كل أداة CLI ترسل معلومات مماثلة.

## تسجيل مجموعة فرعية <span style="opacity:0.6">— من v1.0.0+</span>

إذا كنت تستخدم جزءًا فقط من الكتالوج — سجل مجموعة فرعية للحفاظ على نافذة السياق الخاصة بـ LLM مضغوطة:

```jsonc
{
  "env": {
    "ASTROWAY_API_KEY": "aw_live_...",
    "ASTROWAY_TOOL_GROUPS": "western,vedic,relational",   // المجموعات الفرعية فقط
    "ASTROWAY_READONLY": "1"                               // تخطي ai/horoscope/reports (مدعومة بـ LLM، تستهلك رصيدًا)
  }
}
```

المجموعات الشائعة: `western`, `vedic`, `tarot`, `numerology`, `hd` (التصميم البشري)، `relational` (التزامن/التركيب/ديفيسون)، `prognostics` (التحويلات/التقدمات/العائدات)، `aspects`, `horary`, `geo`, `chinese`, `bazi`, `mayan`, `iching`, `runes`, `geomancy`. شغّل `npx @astroway/mcp --list-tools` لترى المجموعة الكاملة.

`ASTROWAY_READONLY=1` يتخطى المجموعات الثلاث التي تستدعي LLM داخليًا (`ai`, `horoscope`, `reports`) — مفيد عندما تريد حساباتCards الرياضية الخالصة بدون إنفاق رصيد على توليد نص.

## التزام الاستقرار <span style="opacity:0.6">— من v1.0.0+</span>

- **يتم تجميد الكتالوج طوال الجلسة.** 624 أداة، 12 موجه، 14 موردًا مدمجين في الحزمة المنشورة npm في وقت البناء — لا شيء يتغير أثناء الاتصال. إذا قام عميلك بتخزين `tools/list` بعد الاستدعاء الأول، فسيظل صحيحًا طوال الجلسة.
- **معرفات الأدوات مستقرة ضمن الإصدار الرئيسي.** لن يتم إعادة تسمية أو حذف الاسم تحت `astroway_<group>_<tool>` داخل `v1.x` بدون ملاحظة deprecated في `CHANGELOG.md` وتوافر متوازي لـ minor واحد.
- **شكل إدخال الأداة مستقر ضمن الإصدار الثانوي.** يتم تقديم القيود (regex، range، enum) في التصحيحات؛ يتطلب إضافة حقل إلزامي زيادة minor.
- **تحديث الكتالوج — بإعادة التثبيت.** `npm i -g @astroway/mcp@latest` (أو شكل `npx -y @astroway/mcp` في تكوينك) يسحب المجموعة الحالية عند بدء التشغيل التالي.

## أمثلة على الموجهات

بعد توصيل الخادم، اطلب من الذكاء الاصطناعي:

### خريطة الميلاد

> احسب خريطتي الميلاد — مولود في 15 مارس 1990، الساعة 14:30، كييف. صف الشمس والقمر والأفق، وابحث عن التزاماتها الوثيقة.

سيقوم Claude باستدعاء أداة `chart` بمعلماتك، وسيحصل على JSON منظم، وسيصف الخريطة بالكلمات.

### التحويلات

> ما هي التحويلات المهمة للكواكب البطيئة التي ستقع على خريطتي Natal خلال عام 2027؟

يقوم Claude بإجراء استدعاءين للأدوات: أولاً `transits` (لقطة حالية)، ثم `transit-calendar` (نطاق). يفسر الاتجاهات.

### Mahadasha الفيدية

> شغّل Mahadasha Vimshottari لشخص مولود في 22.07.1985 الساعة 06:45 في مومباي. في أي فترة يكون هذا الشخص الآن؟

من خلال أداة `vedic/dashas/vimshottari/maha` — timestamp UTC دقيق للفترة الحالية.

### التزامن

> قارن بين خريطتين: أ — 10.06.1988 الساعة 09:15 لندن، ب — 22.11.1991 الساعة 22:40 برلين. ما هي أقوى التزامات Cross؟

أداة `synastry` مع كتلتي `chart` + تفسير درجة التوافق.

### التاروت

> اسحب 3 أوراق Rider-Waite-Smith: الماضي — الحاضر — المستقبل. السؤال: «هل يجب أن أقبل الوظيفة الجديدة؟». Seed = 42.

`tarot/rider-waite/spread` مع seed ثابت للتكرار.

## قائمة بجميع الأدوات

بعد التوصيل، اسأل Claude:

> أعد سرد جميع أدوات AstroWay.

أو من سطر الأوامر:

```bash
ASTROWAY_API_KEY=aw_test_smoke npx @astroway/mcp 2>&1 | head -1
# (يشغل خادم stdio؛ استدعاءات قائمة الأدوات البروتوكولية تأتي من عميل MCP)
```

## التكوين

| المتغير | الافتراضي | الوصف | من الإصدار |
|---|---|---|---|
| `ASTROWAY_API_KEY` | *(إلزامي)* | Live: `aw_live_...`. Sandbox: `aw_test_...`. | 0.1.0 |
| `ASTROWAY_BASE_URL` | `https://api.astroway.info/v1` | تجاوز لبيئات self-hosted/staging. | 0.1.0 |
| `ASTROWAY_TOOL_GROUPS` | *(جميع المجموعات)* | قوائم مفصولة بفواصل للمجموعات الفرعية (مثل `western,vedic,relational`). | 1.0.0 |
| `ASTROWAY_READONLY` | `0` | `1` يتخطى المجموعات المدعومة بـ LLM (`ai`, `horoscope`, `reports`). | 1.0.0 |
| `LOG_LEVEL` | `error` | `silent`/`error`/`warn`/`info`/`debug` — مستوى تسجيل الدخول إلى stderr. | 0.8.0 |
| `LOG_FILE` | *(غير مكتوب)* | مسار الملف لتكرار السجلات. | 0.8.0 |
| `MCP_FLAT_TOOLS` | `0` | `1` يعيد أسماء flat القديمة (مثل `chart` بدلاً من `astroway_western_chart`). قديم. | 0.9.0 |

## لماذا MCP وليس تكامل مباشر

الذكاء الاصطناعي العام (بدون grounding) سيقول *«في يوليو، سيشكل زحل مثلثًا مع المشتري»* — بدون تاريخ دقيق، مع ±15 يومًا من التباين. **وكيل MCP** يقوم بـ `tool_use POST /v1/transits` ويعيد timestamp UTC **إلى الثانية**، باستخدام Swiss Ephemeris الحقيقي.

الميزة ليست في LLM، بل في **ضمان أن الرياضيات حقيقية** — ليست من وحي الخيال.

## توزيع الحزمة

- **mcp.so listing:** [mcp.so/server/astroway-mcp/astroway](https://mcp.so/server/astroway-mcp/astroway)
- **mcpservers.org:** في انتظار الموافقة (اعتبارًا من مايو 2026)
- **awesome-mcp-servers (punkpeye):** [PR #5972](https://github.com/punkpeye/awesome-mcp-servers/pull/5972)

## الروابط

- 📦 npm: [npmjs.com/package/@astroway/mcp](https://www.npmjs.com/package/@astroway/mcp)
- 📘 وثائق API: [/docs/api/](/docs/api/)
- 🔑 التسجيل: [/dashboard/sign-up](/dashboard/sign-up)
- 💰 التسعير: [/pricing/](/pricing/)
- 🌐 repo العام (MIT): [github.com/astroway/astroway-mcp](https://github.com/astroway/astroway-mcp)