# MCP — conectarea Claude / Cursor Serverul Model Context Protocol (MCP) AstroWay expune **toate cele {siteMeta.endpoints} de endpoint-uri** ca instrumente pentru un agent AI. Sunt disponibile două moduri — ambele sunt native compatibile cu toți clienții MCP. | Mod | URL / comandă | Când să alegi | |---|---|---| | **Hosted HTTP** | `https://mcp.astroway.info/mcp` | Claude Web (claude.ai în browser), Claude Desktop / Cursor / Code pentru începători fără npm, sau când vrei zero-install | | **Stdio (npm)** | `npx @astroway/mcp` | Utilizatori avansați de Cursor, dezvoltare locală, cei care acordă atenție confidențialității (cheia nu părăsește niciodată mașina ta), pregătiți pentru offline | Endpoint-ul hosted și pachetul npm folosesc **același catalog de instrumente** (generat dintr-un singur `/v1/openapi.json`). Autentificarea: aceeași cheie API `aw_test_*` / `aw_live_*` — la hosted este trimisă prin `Authorization: Bearer …` header, iar la stdio prin variabila de mediu `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) ## Hosted (`mcp.astroway.info`) — zero install Pornire rapidă fără npm — alege clientul tău. Înainte de instalare, obține o cheie de pe [api.astroway.info/dashboard/sign-up](https://api.astroway.info/dashboard/sign-up) (10 000 de credite/lună gratuit). Apasă butonul — Cursor se va deschide, va cere confirmare, va adăuga înregistrarea automat: Instalează în Cursor → :::caution[Pasul 2 este obligatoriu — altfel nu va funcționa] Cursor nu poate substitui secretul din deeplink — în `~/.cursor/mcp.json` va fi scris literalul `Bearer YOUR_API_KEY`, la care serverul va răspunde cu `403 invalid_format`. **După ce apeși butonul:** 1. **Cursor Settings** (⚙️ colțul dreapta sus) → **Tools & MCP** → găsește `astroway-hosted` în listă. 2. Apasă cele trei puncte (`⋯`) lângă server → **Edit configuration**. 3. În câmpul `Authorization` înlocuiește `Bearer YOUR_API_KEY` cu `Bearer aw_test_…` (sau `aw_live_…`) — cheia ta reală de pe [Dashboard](https://api.astroway.info/dashboard/keys). 4. Salvează → deschide din nou lista MCP → asigură-te că starea este **enabled** + punctul verde + contorul `630 tools enabled`. Alternativ, editează fișierul direct: `~/.cursor/mcp.json` (`headers.Authorization`). ::: Fără editare JSON. În orice chat din Claude Desktop: 1. Apasă **`+`** în stânga câmpului de intrare → din meniu alege **"Add connector"**. 2. În dialog alege **"Add custom connector"**. 3. **Name:** `astroway-hosted` 4. **URL:** `https://mcp.astroway.info/mcp` 5. Deschide **"Advanced settings"** → în **"Custom headers"** adaugă: - **Key:** `Authorization` - **Value:** `Bearer aw_live_...` (cheia ta) 6. **Add** → găsește `astroway-hosted` în lista Connectors, activează comutatorul. Nu este necesară repornirea lui Claude Desktop. Apasă `+` într-un nou chat — în Connectors va apărea `astroway-hosted` cu toate cele 630 de instrumente + 12 de prompt-uri + 14 de resurse. Pentru Cline / Continue / Windsurf sau versiuni vechi de Claude Desktop / Cursor: ```json { "mcpServers": { "astroway-hosted": { "url": "https://mcp.astroway.info/mcp", "headers": { "Authorization": "Bearer aw_live_..." } } } } ``` Căi către fișierele de configurare: - **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) sau `.cursor/mcp.json` (în workspace) - **Cline (VS Code):** `.cline/mcp.json` în workspace - **Continue:** `~/.continue/config.json` (bloc `mcpServers`) - **Windsurf:** `~/.codeium/windsurf/mcp_config.json` După editare, repornește complet clientul (Cmd+Q → deschide din nou). ### Verificare ```bash curl https://mcp.astroway.info/health # {"status":"ok","version":"…","uptime_sec":…,"mcp_protocol_version":"2024-11-05"} ``` În client — solicită: *"List 5 AstroWay tool names from astroway-hosted"*. Ar trebui să returneze nume precum `astroway_western_chart`, `astroway_horoscope_daily`, `astroway_vedic_panchang_full`, … ### Rate limits Endpoint-ul hosted este protejat de un sistem de limitare pe trei niveluri: Cloudflare DDoS layer + nginx `120 req/min/IP` + bucket în memorie `60/60s/(IP+cheie)`. Clienții MCP reali (Claude Desktop, Cursor) nu se apropie de aceste limite — ei nu fac cereri în burst. Dacă automatizarea sau CI-ul tău necesită > 120 req/min — folosește modul **stdio** (acolo nu există astfel de limite, comunică direct prin `api.astroway.info/v1/*` cu limita ta tarifară de rate-limit). ### Ce se întâmplă dacă `mcp.astroway.info` este temporar indisponibil Dacă endpoint-ul hosted returnează 5xx, clientul MCP va vedea o eroare la `tools/list`. Acest lucru **nu afectează** clienții stdio — ei lansează pachetul npm local, care comunică direct cu `api.astroway.info/v1/*` fără strat intermediar hosted. **Fallback pentru integrări critice:** adaugă un **al doilea server MCP** în config cu modul stdio — clientul va folosi automat acesta dacă hosted nu răspunde la `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_..." } } } } ``` Uptime-ul real al endpoint-ului hosted este vizibil pe [status.astroway.info](https://status.astroway.info). Incidentele > 5 minute sunt publicate ca postmortem în maximum 5 zile lucrătoare (conform [/sla/](/sla/)). ## Stdio (npm) — pentru dezvoltare locală [`@astroway/mcp`](https://www.npmjs.com/package/@astroway/mcp) — pachet npm care rulează local ca un subprocess. Un singur pachet npm, integrare nativă cu Claude Desktop, Cursor și orice client compatibil MCP. ## Cum funcționează Lista de instrumente este generată **la momentul build-ului** din specificația OpenAPI live ([api.astroway.info/v1/openapi.json](https://api.astroway.info/v1/openapi.json)). Fiecare lansare a pachetului preia automat toate noile endpoint-uri — nu este necesară întreținerea manuală. Fiecare endpoint devine un instrument de tipul: - `tools/list` returnează descrierea și schema de intrare (cu exemplu de corp al cererii) - `tools/call` face un HTTP POST către `https://api.astroway.info/v1/` cu cheia ta `ASTROWAY_API_KEY` - Răspunsul este returnat agentului ca JSON structurat Fiecare lansare este și semnată cu SLSA provenance ([Sigstore-attested](https://search.sigstore.dev/)) — aceasta garantează că pachetul npm a fost construit chiar din commit-ul din repo-ul public. ## Instalare ### Claude Desktop (macOS) Adaugă în `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "astroway": { "command": "npx", "args": ["-y", "@astroway/mcp"], "env": { "ASTROWAY_API_KEY": "aw_live_..." } } } } ``` Repornește Claude Desktop. În bara de sub chat va apărea indicatorul 🛠️ cu numărul de instrumente încărcate. ### Cursor Adaugă în `~/.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 Aceeași comandă `npx @astroway/mcp` funcționează în fiecare client compatibil MCP. Configurația este identică — se modifică doar calea către fișier: ```json { "mcpServers": { "astroway": { "command": "npx", "args": ["-y", "@astroway/mcp"], "env": { "ASTROWAY_API_KEY": "aw_live_..." } } } } ``` | Client | Cale către config | |---|---| | **Cline** (VS Code) | `.cline/mcp.json` în rădăcina workspace-ului | | **Continue** | `~/.continue/config.json` (sub `mcpServers`) | | **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | | **GitHub Copilot Chat (VS Code)** | flag de preview → `mcp.json` în workspace | | **Extensie VS Code MCP** | `~/.vscode/mcp.json` | ### Alți clienți MCP Rulează ca server stdio: ```bash ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp ``` ## Confidențialitate — de la v1.0.0+ Acest server MCP **nu trimite nimic înapoi către AstroWay** în afară de apelurile API pe care i le ceri să le execute. Nicio telemetrie, niciun analytics, niciun comutator de opt-in/opt-out — implicit este dezactivat. Cererea de ieșire include două antete de identificare pentru ca backend-ul AstroWay să poată diferenția traficul MCP de cel HTTP direct în propriile logs: - `User-Agent: astroway-mcp/ (Node/)` - `X-Astroway-Channel: mcp` Niciunul dintre acestea nu conține ID de sesiune, fingerprint de mașină sau altceva personal. Aceasta este o semantică standard pentru `User-Agent` — fiecare instrument CLI trimite asemenea informații. ## Înregistrare subset — de la v1.0.0+ Dacă folosești doar o parte din catalog — înregistrează un subset pentru a menține fereastra de context a LLM compactă: ```jsonc { "env": { "ASTROWAY_API_KEY": "aw_live_...", "ASTROWAY_TOOL_GROUPS": "western,vedic,relational", // doar aceste prefixe "ASTROWAY_READONLY": "1" // sare peste grupurile ai/horoscope/reports (LLM-backed, consumă credite) } } ``` Grupuri comune: `western`, `vedic`, `tarot`, `numerology`, `hd` (Human Design), `relational` (synastry/composite/davison), `prognostics` (transits/progressions/returns), `aspects`, `horary`, `geo`, `chinese`, `bazi`, `mayan`, `iching`, `runes`, `geomancy`. Rulează `npx @astroway/mcp --list-tools` pentru a vedea setul complet. `ASTROWAY_READONLY=1` sare peste cele trei grupuri care apelează intern LLM (`ai`, `horoscope`, `reports`) — util când dorești o matematică curată și deterministă a hărților fără a consuma credite pe generarea de text. ## Angajament de stabilitate — de la v1.0.0+ - **Catalogul este fixat pe durata sesiunii.** 624 de instrumente, 12 de prompt-uri, 14 de resurse sunt incluse în pachetul npm publicat la momentul build-ului — nimic nu se schimbă în timpul conectării. Dacă clientul tău face cache la `tools/list` după primul apel, acesta rămâne corect pentru întreaga sesiune. - **Identificatorii instrumentelor sunt stabili în cadrul aceleiași versiuni major.** Numele sub `astroway__` nu vor fi redenumite sau eliminate în interiorul `v1.x` fără un notificare de deprecare în `CHANGELOG.md` și disponibilitate paralelă minimă pe un minor. - **Forma de intrare a instrumentului este stabilă în cadrul aceleiași versiuni minor.** Restricțiile (regex, range, enum) sunt aduse prin patch-uri; adăugarea unui câmp obligatoriu necesită un bump minor. - **Reîmprospătarea catalogului se face prin reinstalare.** `npm i -g @astroway/mcp@latest` (sau `npx -y @astroway/mcp` în config-ul tău) preia setul curent la următoarea pornire. ## Exemple de prompt-uri După conectarea serverului, solicită AI-ului: ### Hartă natală > Calculează-mi harta natală — născut pe 15 martie 1990, ora 14:30, Kiev. Descrie Soarele, Luna, Ascendentul și identifică aspectele strânse. Claude va apela instrumentul `chart` cu parametrii tăi, va primi un JSON structurat și va descrie harta în cuvinte. ### Tranzite > Care sunt tranzitele semnificative ale planetelor lente care vor avea loc în harta mea natală pe parcursul anului 2027? Claude face două apeluri la instrumente: mai întâi `transits` (starea curentă), apoi `transit-calendar` (intervalul). Interpretează tendințele. ### Vedic Mahadasha > Rulează Vimshottari Mahadasha pentru o persoană născută pe 22.07.1985 la 06:45 în Mumbai. În ce perioadă se află această persoană acum? Prin instrumentul `vedic/dashas/vimshottari/maha` — timestamp exact UTC pentru perioada curentă. ### Synastry > Compară două hărți: A — 10.06.1988 09:15 Londra, B — 22.11.1991 22:40 Berlin. Care sunt cele mai puternice aspecte încrucișate? Instrumentul `synastry` cu două blocuri `chart` + interpretarea scorului de compatibilitate. ### Tarot > Extrage 3 cărți Rider-Waite-Smith: Trecut — Prezent — Viitor. Întrebare: „merită să accept noul job?”. Seed = 42. `tarot/rider-waite/spread` cu seed fixat pentru reproductibilitate. ## Listă a tuturor instrumentelor După conectare, întreabă în Claude: > Listează toate instrumentele AstroWay. Sau din linia de comandă: ```bash ASTROWAY_API_KEY=aw_test_smoke npx @astroway/mcp 2>&1 | head -1 # (pornește serverul stdio; apelurile protocolare de listare a instrumentelor sunt făcute de clientul MCP) ``` ## Configurare | Variabilă | Implicit | Descriere | De la versiunea | |---|---|---|---| | `ASTROWAY_API_KEY` | *(obligatoriu)* | Live: `aw_live_...`. Sandbox: `aw_test_...`. | 0.1.0 | | `ASTROWAY_BASE_URL` | `https://api.astroway.info/v1` | Suprascriere pentru medii self-hosted/staging. | 0.1.0 | | `ASTROWAY_TOOL_GROUPS` | *(toate grupurile)* | Prefixe separate prin virgulă pentru limitarea catalogului (`western,vedic,relational`). | 1.0.0 | | `ASTROWAY_READONLY` | `0` | `1` sare peste grupurile LLM-backed (`ai`, `horoscope`, `reports`). | 1.0.0 | | `LOG_LEVEL` | `error` | `silent`/`error`/`warn`/`info`/`debug` — nivelul de logare pe stderr. | 0.8.0 | | `LOG_FILE` | *(nu este scris)* | Cale către fișier pentru duplicarea logurilor. | 0.8.0 | | `MCP_FLAT_TOOLS` | `0` | `1` returnează nume plate pre-v0.9 (`chart` în loc de `astroway_western_chart`). Legacy. | 0.9.0 | ## De ce MCP și nu integrare directă LLM-ul generic (fără grounding) va spune *„undeva în iulie Saturn va forma un trin cu Jupiterul tău”* — fără dată exactă, cu o marjă de ±15 zile. **Agentul MCP** face `tool_use POST /v1/transits` și returnează timestamp-ul UTC **până la secundă**, pe baza Swiss Ephemeris real. Avantajul nu este în LLM, ci în **garanția că matematica este reală** — nu inventată. ## Distribuirea pachetului - **mcp.so listing:** [mcp.so/server/astroway-mcp/astroway](https://mcp.so/server/astroway-mcp/astroway) - **mcpservers.org:** în așteptarea aprobării (la momentul mai 2026) - **awesome-mcp-servers (punkpeye):** [PR #5972](https://github.com/punkpeye/awesome-mcp-servers/pull/5972) ## Linkuri - 📦 npm: [npmjs.com/package/@astroway/mcp](https://www.npmjs.com/package/@astroway/mcp) - 📘 Documente API: [/docs/api/](/docs/api/) - 🔑 Înregistrare: [/dashboard/sign-up](/dashboard/sign-up) - 💰 Prețuri: [/pricing/](/pricing/) - 🌐 Repo public (MIT): [github.com/astroway/astroway-mcp](https://github.com/astroway/astroway-mcp)