# MCP — Claude / Cursor Bağlantısı AstroWay'in MCP sunucusu, **tüm {siteMeta.endpoints} uç noktalarını** AI ajanları için araçlar olarak sunar. İki mod desteklenmektedir — her ikisi de tüm MCP uyumlu istemciler tarafından yerel olarak desteklenir. | Mod | URL / Komut | Ne zaman tercih edilir? | |---|---|---| | **Hosted HTTP** | `https://mcp.astroway.info/mcp` | Tarayıcıdaki Claude Web (claude.ai), Claude Desktop / Cursor / Code yeni başlayanlar npm olmadan ya da sıfır kurulum istiyorsan | | **Stdio (npm)** | `npx @astroway/mcp` | Cursor güç kullanıcıları, yerel geliştirme, gizlilik odaklı (anahtar hiçbir zaman makineni terk etmez), çevrimdışı hazır | Hosted uç noktası ve npm paketi **aynı araç kataloğunu** kullanır (tek `/v1/openapi.json` dosyasından üretilir). Kimlik Doğrulama: aynı `aw_test_*` / `aw_live_*` API anahtarı — hosted'da `Authorization: Bearer …` başlığında gönderilir, stdio'da ise `ASTROWAY_API_KEY` ortam değişkeni aracılığıyla. Kaynak: [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) ## Hosted (`mcp.astroway.info`) — sıfır kurulum npm olmadan hızlı başlangıç — istemciyi seç. Kurulumdan önce [api.astroway.info/dashboard/sign-up](https://api.astroway.info/dashboard/sign-up) adresinden bir anahtar al (ayda 10.000 kredi ücretsiz). Düğmeye tıkla — Cursor açılacak, onay isteyecek ve kaydı otomatik olarak ekleyecek: Cursor'da Yükle → :::caution[Zorunlu 2. adım — aksi halde çalışmaz] Cursor, deeplink ile gizli anahtarı yerleştiremez — `~/.cursor/mcp.json` dosyasına `Bearer YOUR_API_KEY` dizesi yazılır ve sunucu `403 invalid_format` yanıtı verir. **Düğmeye tıkladıktan sonra:** 1. **Cursor Ayarları** (⚙️ sağ üst köşe) → **Araçlar & MCP** → listeden `astroway-hosted` bul. 2. Sunucuya ait üç noktaya (⋯) tıkla → **Yapılandırmayı Düzenle**. 3. `Authorization` alanındaki `Bearer YOUR_API_KEY` metnini gerçek API anahtarınla değiştir (`aw_test_…` ya da `aw_live_…`) — [Dashboard](https://api.astroway.info/dashboard/keys) adresinden aldığın gerçek anahtar. 4. Kaydet → MCP listesini tekrar aç ve durumunun **etkin** + yeşil nokta + `630 tools enabled` sayacı olduğundan emin ol. Alternatif olarak doğrudan dosyayı düzenleyebilirsin: `~/.cursor/mcp.json` (`headers.Authorization`). ::: JSON düzenlemesi gerekmez. Herhangi bir Claude Desktop sohbetinde: 1. Giriş alanının solundaki **`+`** düğmesine tıkla → açılan menüden **"Add connector"** seçeneğini seç. 2. Diyalogda **"Add custom connector"** seçeneğini seç. 3. **Name:** `astroway-hosted` 4. **URL:** `https://mcp.astroway.info/mcp` 5. **"Advanced settings"** bölümünü genişlet → **"Custom headers"** kısmına ekle: - **Key:** `Authorization` - **Value:** `Bearer aw_live_...` (senin anahtarın) 6. **Add** → Connectors listesinde `astroway-hosted` bul, anahtarı etkinleştir. Claude Desktop'u yeniden başlatmana **gerek yok**. Yeni bir sohbette `+` düğmesine tıkla — Connectors listesinde `astroway-hosted` tüm 630 aracı, 12 promptu ve 14 kaynağıyla birlikte görünecek. Cline / Continue / Windsurf ya da eski Claude Desktop / Cursor sürümleri için: ```json { "mcpServers": { "astroway-hosted": { "url": "https://mcp.astroway.info/mcp", "headers": { "Authorization": "Bearer aw_live_..." } } } } ``` Yapılandırma dosyalarının yolları: - **Claude Desktop (macOS):** `~/Library/Application Support/Claude/claude_desktop_config.json` - **Claude Desktop (Windows):** `%APPDATA%\Claude\claude_desktop_config.json` - **Cursor:** `~/.cursor/mcp.json` (global) ya da `.cursor/mcp.json` (çalışma alanı içinde) - **Cline (VS Code):** `.cline/mcp.json` (çalışma alanı içinde) - **Continue:** `~/.continue/config.json` (`mcpServers` bloğu) - **Windsurf:** `~/.codeium/windsurf/mcp_config.json` Değişiklikten sonra istemciyi tamamen yeniden başlat (Cmd+Q → tekrar aç). ### Doğrulama ```bash curl https://mcp.astroway.info/health # {"status":"ok","version":"…","uptime_sec":…,"mcp_protocol_version":"2024-11-05"} ``` İstemcide — AI'ye şunu söyle: *"List 5 AstroWay tool names from astroway-hosted"*. Geri dönüş olarak `astroway_western_chart`, `astroway_horoscope_daily`, `astroway_vedic_panchang_full` gibi araç isimleri almalısın. ### Rate limitleri Hosted uç noktası 3 seviyeli koruma ile korunmaktadır: Cloudflare DDoS katmanı + nginx `120 req/dakika/IP` + bellek içi kova `60/60sn/(IP+anahtar)`. Gerçek MCP istemcileri (Claude Desktop, Cursor) bu limitlere yaklaşmaz — ani istekler yapmazlar. Eğer otomasyonun / CI'in > 120 req/dakika ihtiyacı varsa **stdio** modunu kullan (burada limit yok, doğrudan `api.astroway.info/v1/*` adresine senin tarif planındaki rate limiti ile gidiyor). ### `mcp.astroway.info` geçici olarak kullanılamazsa ne olur? Hosted uç noktası 5xx yanıtı dönerse, MCP istemcisi `tools/list` çağrısında hata alır. Bu **stdio istemcilerini etkilemez** — onlar yerel npm paketini çalıştırır ve doğrudan `api.astroway.info/v1/*` adresine gider, hosted katmanı olmadan. **Kritik entegrasyonlar için yedek:** konfigürasyonuna **ikinci bir MCP sunucusu** ekle — hosted yanıt vermediğinde istemci otomatik olarak yedek modu kullanır: ```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_..." } } } } ``` Hosted uç noktasının gerçek kullanılabilirliği [status.astroway.info](https://status.astroway.info) adresinden izlenebilir. 5 dakikadan uzun kesintilerde 5 iş günü içinde postmortem yayınlanır (bkz. [/sla/](/sla/)). ## Stdio (npm) — yerel geliştirme için [`@astroway/mcp`](https://www.npmjs.com/package/@astroway/mcp) — yerel olarak alt süreç olarak çalışan npm paketi. Tek bir npm paketi, Claude Desktop, Cursor ve herhangi bir MCP uyumlu istemciyle yerel entegrasyon. ## Nasıl çalışır? Araç listesi **build anında** canlı OpenAPI spec'ten (`api.astroway.info/v1/openapi.json`) üretilir. Paket her yayınlandığında yeni uç noktalar otomatik olarak dahil edilir — manuel güncellemeye gerek yok. Her uç nokta aşağıdaki şekilde bir araç haline gelir: - `tools/list` girdi açıklaması ve şemasını (istek gövdesi örneğiyle birlikte) döndürür - `tools/call` senin `ASTROWAY_API_KEY` ile `https://api.astroway.info/v1/` adresine HTTP POST yapar - Yanıt, yapılandırılmış JSON olarak araca geri gönderilir Her yayın aynı zamanda SLSA provenance ([Sigstore onaylı](https://search.sigstore.dev/)) ile birlikte gelir — bu, npm paketinin gerçekten kamu repo'sundaki bir committ'ten üretildiğinin garantisidir. ## Kurulum ### Claude Desktop (macOS) `~/Library/Application Support/Claude/claude_desktop_config.json` dosyasına ekle: ```json { "mcpServers": { "astroway": { "command": "npx", "args": ["-y", "@astroway/mcp"], "env": { "ASTROWAY_API_KEY": "aw_live_..." } } } } ``` Claude Desktop'u yeniden başlat. Sohbetin altında 🛠️ simgesi ve yüklenen araç sayısı görünecek. ### Cursor `~/.cursor/mcp.json` dosyasına ekle: ```json { "mcpServers": { "astroway": { "command": "npx", "args": ["-y", "@astroway/mcp"], "env": { "ASTROWAY_API_KEY": "aw_live_..." } } } } ``` ### Cline / Continue / Windsurf / Copilot / VS Code MCP Her MCP uyumlu istemcide aynı `npx @astroway/mcp` komutu çalışır. Yapılandırma aynıdır — sadece dosya yolu değişir: ```json { "mcpServers": { "astroway": { "command": "npx", "args": ["-y", "@astroway/mcp"], "env": { "ASTROWAY_API_KEY": "aw_live_..." } } } } ``` | İstemci | Yapılandırma dosyasının yolu | |---|---| | **Cline** (VS Code) | Çalışma alanının kökünde `.cline/mcp.json` | | **Continue** | `~/.continue/config.json` (`mcpServers` altında) | | **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | | **GitHub Copilot Chat (VS Code)** | önizleme bayrağı → çalışma alanındaki `mcp.json` | | **VS Code MCP eklentisi** | `~/.vscode/mcp.json` | ### Diğer MCP istemcileri stdio sunucusu olarak çalıştır: ```bash ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp ``` ## Gizlilik — v1.0.0+'dan itibaren Bu MCP sunucusu **sadece senin verdiğin API çağrıları dışında** hiçbir şeyi AstroWay'e göndermez. Varsayılan olarak telemetri, analytics ya da opt-in/opt-out anahtarları yok — sessizlik. Çıkış istekleri, AstroWay arka ucunun MCP trafiğini doğrudan HTTP trafiğinden ayırt edebilmesi için iki tanımlayıcı başlık taşır: - `User-Agent: astroway-mcp/ (Node/)` - `X-Astroway-Channel: mcp` Bu başlıklardan hiçbiri oturum kimliği, makine parmak izi ya da kişisel veri içermiyor. Standart `User-Agent` semantiğine uygun — her CLI aracı benzer bilgiler gönderir. ## Alt küme kaydı — v1.0.0+'dan itibaren Eğer kataloğun sadece bir kısmını kullanıyorsan, LLM bağlam penceresini kompakt tutmak için alt kümeyi kaydet: ```jsonc { "env": { "ASTROWAY_API_KEY": "aw_live_...", "ASTROWAY_TOOL_GROUPS": "western,vedic,relational", // sadece bu önekler "ASTROWAY_READONLY": "1" // ai/horoscope/reports'u atla (LLM destekli, kredi harcar) } } ``` Yaygın gruplar: `western`, `vedic`, `tarot`, `numerology`, `hd` (Human Design), `relational` (synastry/composite/davison), `prognostics` (transits/progressions/returns), `aspects`, `horary`, `geo`, `chinese`, `bazi`, `mayan`, `iching`, `runes`, `geomancy`. Tam listeyi görmek için `npx @astroway/mcp --list-tools` komutunu çalıştır. `ASTROWAY_READONLY=1` LLM tarafından desteklenen üç grubu (`ai`, `horoscope`, `reports`) atlar — metin üretimi için kredi harcamadan saf matematiksel harita hesaplamaları yapmak istiyorsan kullanışlıdır. ## Kararlılık taahhüdü — v1.0.0+'dan itibaren - **Katalog, oturum boyunca dondurulur.** 624 araç, 12 prompt, 14 kaynak yayınlanan npm paketine build anında gömülür — bağlantı sırasında hiçbir şey değişmez. İstemcin `tools/list` çıktısını oturum boyunca önbelleğe alırsa, bu çıktı tüm oturum boyunca geçerliliğini korur. - **Araç tanımlayıcıları major versiyon içinde kararlıdır.** `astroway__` adı `v1.x` içinde deprecation notu olmadan yeniden adlandırılmaz ya da silinmez. - **Araç girdi şekli minor versiyon içinde kararlıdır.** Sıkılaştırmalar (regex, range, enum) patch'lerde gelir; zorunlu alan eklemek minor yükseltme gerektirir. - **Katalog yenilemesi yeniden kurulumla olur.** `npm i -g @astroway/mcp@latest` (ya da konfigürasyonundaki `npx -y @astroway/mcp` komutu) bir sonraki başlangıçta güncel kataloğu yükler. ## Prompt örnekleri Sunucuyu bağladıktan sonra AI'ye şunu söyle: ### Doğum haritası > 15 Mart 1990, 14:30, Kiev'de doğdum. Güneş, Ay, Ascendant'ı hesapla ve yakın açılara bak. Claude, parametrelerinle `chart` aracını çağıracak, yapılandırılmış JSON yanıtı alacak ve haritayı sözcüklerle tanımlayacak. ### Transitler > 2027 yılında yavaş gezegenlerin transitleri hangi önemli açılar oluşturacak? Claude iki araç çağrısı yapar: önce `transits` (mevcut anlık görüntü), sonra `transit-calendar` (zaman aralığı). Trendleri yorumlar. ### Vedic Mahadasha > 22.07.1985 06:45 Mumbai'de doğan biri için Vimshottari Mahadasha'yı başlat. Bu kişi şu anda hangi dönemde? `vedic/dashas/vimshottari/maha` aracıyla — mevcut dönem için hassas UTC-timestamp. ### Synastry > İki harita karşılaştır: A — 10.06.1988 09:15 Londra, B — 22.11.1991 22:40 Berlin. En güçlü kros açılar hangileri? İki `chart` bloğu + uyumluluk puanı yorumu ile `synastry` aracı. ### Tarot > Rider-Waite-Smith'den 3 kart çek: Geçmiş — Şimdi — Gelecek. Soru: "Yeni işi kabul etmeli miyim?". Seed = 42. Sabit seed ile tekrarlanabilir sonuç için `tarot/rider-waite/spread`. ## Tüm araçların listesi Bağlantıdan sonra Claude'a sor: > Tüm astroway araçlarını listele. Ya da komut satırından: ```bash ASTROWAY_API_KEY=aw_test_smoke npx @astroway/mcp 2>&1 | head -1 # (stdio sunucusunu başlatır; protokol araç listesi çağrıları MCP istemcisi tarafından yapılır) ``` ## Yapılandırma | Değişken | Varsayılan | Açıklama | Sürüm | |---|---|---|---| | `ASTROWAY_API_KEY` | *(zorunlu)* | Canlı: `aw_live_...`. Sandbox: `aw_test_...`. | 0.1.0 | | `ASTROWAY_BASE_URL` | `https://api.astroway.info/v1` | Self-hosted/staging ortamları için geçersiz kıl. | 0.1.0 | | `ASTROWAY_TOOL_GROUPS` | *(tüm gruplar)* | Kataloğu sınırlamak için virgülle ayrılmış önekler (`western,vedic,relational`). | 1.0.0 | | `ASTROWAY_READONLY` | `0` | `1` LLM destekli grupları (`ai`, `horoscope`, `reports`) atlar. | 1.0.0 | | `LOG_LEVEL` | `error` | `silent`/`error`/`warn`/`info`/`debug` — stderr'e loglama seviyesi. | 0.8.0 | | `LOG_FILE` | *(yazılmaz)* | Logları ikileştirmek için dosya yolu. | 0.8.0 | | `MCP_FLAT_TOOLS` | `0` | `1` eski v0.9 düz isimleri döndürür (`chart` yerine `astroway_western_chart`). Eski sürüm. | 0.9.0 | ## Neden MCP, doğrudan entegrasyon değil? Genel LLM (grounding olmadan) *"Temmuz ayında Satürn Jüpiter'inle üçgen oluşturacak"* gibi belirsiz tarihler ve ±15 günlük kayma ile yanıt verir. **MCP aracı** `tool_use POST /v1/transits` çağrısı yapar ve UTC-timestamp'ı **saniyeye kadar** Swiss Ephemeris'e dayalı gerçek veriyle döndürür. Avantaj LLM'de değil, **matematiğin gerçek olduğunun garantisinde** — hayal ürünü değil. ## Paket dağıtımı - **mcp.so listing:** [mcp.so/server/astroway-mcp/astroway](https://mcp.so/server/astroway-mcp/astroway) - **mcpservers.org:** Mayıs 2026 itibarıyla onay bekliyor - **awesome-mcp-servers (punkpeye):** [PR #5972](https://github.com/punkpeye/awesome-mcp-servers/pull/5972) ## Bağlantılar - 📦 npm: [npmjs.com/package/@astroway/mcp](https://www.npmjs.com/package/@astroway/mcp) - 📘 API dokümantasyonu: [/docs/api/](/docs/api/) - 🔑 Kayıt ol: [/dashboard/sign-up](/dashboard/sign-up) - 💰 Fiyatlandırma: [/pricing/](/pricing/) - 🌐 Genel repo (MIT): [github.com/astroway/astroway-mcp](https://github.com/astroway/astroway-mcp)