# MCP — połączenie Claude / Cursor Serwer AstroWay w Model Context Protocol (MCP) udostępnia **wszystkie {siteMeta.endpoints} endpointy** jako narzędzia dla AI-agenta. Obsługiwane są dwa tryby — oba są natywnie wspierane przez wszystkie klienty zgodne z MCP. | Tryb | URL / komenda | Kiedy wybrać | |---|---|---| | **Hosted HTTP** | `https://mcp.astroway.info/mcp` | Claude Web (claude.ai w przeglądarce), Claude Desktop / Cursor / Code dla nowicjuszy bez npm, lub gdy chcesz zero-install | | **Stdio (npm)** | `npx @astroway/mcp` | Zaawansowani użytkownicy Cursor, lokalny rozwój, dbający o prywatność (klucz nigdy nie opuszcza twojego komputera), gotowy do pracy offline | Hosted endpoint i pakiet npm używają **tej samej listy narzędzi** (generowanej z jednego `/v1/openapi.json`). Autoryzacja: ten sam klucz API `aw_test_*` / `aw_live_*` — w trybie hosted wysyłany przez nagłówek `Authorization: Bearer …`, w trybie stdio przez zmienną środowiskową `ASTROWAY_API_KEY`. Źródło: [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 Szybki start bez npm — wybierz swój klient. Przed instalacją pobierz klucz na [api.astroway.info/dashboard/sign-up](https://api.astroway.info/dashboard/sign-up) (10 000 darmowych kredytów/miesiąc). Kliknij przycisk — Cursor otworzy się, poprosi o potwierdzenie, automatycznie doda wpis: Zainstaluj w Cursor → :::caution[Obowiązkowy 2. krok — inaczej nie zadziała] Cursor nie potrafi podmieniać sekretów z deeplink — w `~/.cursor/mcp.json` zapisze się dosłowny tekst `Bearer YOUR_API_KEY`, na który serwer odpowie `403 invalid_format`. **Po kliknięciu przycisku:** 1. **Cursor Settings** (⚙️ prawy górny róg) → **Tools & MCP** → znajdź `astroway-hosted` na liście. 2. Kliknij trzy kropki (`⋯`) obok serwera → **Edit configuration**. 3. W polu `Authorization` zastąp `Bearer YOUR_API_KEY` na `Bearer aw_test_…` (lub `aw_live_…`) — twoim rzeczywistym kluczem z [Dashboard](https://api.astroway.info/dashboard/keys). 4. Zapisz → ponownie otwórz listę MCP → upewnij się, że status to **enabled** + zielony punkt + licznik `630 tools enabled`. Alternatywnie edytuj plik bezpośrednio: `~/.cursor/mcp.json` (`headers.Authorization`). ::: Bez edycji JSON. W dowolnym czacie Claude Desktop: 1. Kliknij **`+`** po lewej stronie pola wprowadzania → w menu wybierz **"Add connector"**. 2. W oknie dialogowym wybierz **"Add custom connector"**. 3. **Name:** `astroway-hosted` 4. **URL:** `https://mcp.astroway.info/mcp` 5. Rozwiń **"Advanced settings"** → w **"Custom headers"** dodaj: - **Key:** `Authorization` - **Value:** `Bearer aw_live_...` (twój klucz) 6. **Add** → znajdź `astroway-hosted` na liście Connectors, włącz przełącznik. Nie musisz restartować Claude Desktop. Kliknij `+` w nowym czacie — w Connectors pojawi się `astroway-hosted` z wszystkimi 630 narzędziami + 12 promptów + 14 zasobów. Dla Cline / Continue / Windsurf lub starszych wersji Claude Desktop / Cursor: ```json { "mcpServers": { "astroway-hosted": { "url": "https://mcp.astroway.info/mcp", "headers": { "Authorization": "Bearer aw_live_..." } } } } ``` Ścieżki do plików konfiguracyjnych: - **Claude Desktop (macOS):** `~/Library/Application Support/Claude/claude_desktop_config.json` - **Claude Desktop (Windows):** `%APPDATA%\Claude\claude_desktop_config.json` - **Cursor:** `~/.cursor/mcp.json` (globalnie) lub `.cursor/mcp.json` (w przestrzeni roboczej) - **Cline (VS Code):** `.cline/mcp.json` w przestrzeni roboczej - **Continue:** `~/.continue/config.json` (blok `mcpServers`) - **Windsurf:** `~/.codeium/windsurf/mcp_config.json` Po edycji całkowicie uruchom klienta ponownie (Cmd+Q → otwórz ponownie). ### Weryfikacja ```bash curl https://mcp.astroway.info/health # {"status":"ok","version":"…","uptime_sec":…,"mcp_protocol_version":"2024-11-05"} ``` W klientach — poproś: *"List 5 AstroWay tool names from astroway-hosted"*. Powinno zwrócić nazwy typu `astroway_western_chart`, `astroway_horoscope_daily`, `astroway_vedic_panchang_full`, … ### Limity szybkości Hosted endpoint jest chroniony 3-poziomowym ograniczeniem: Cloudflare DDoS + nginx `120 req/min/IP` + in-memory bucket `60/60s/(IP+key)`. Rzeczywiste klienty MCP (Claude Desktop, Cursor) nie zbliżają się do tych limitów — nie wykonują burst-requestów. Jeśli twoja automatyzacja / CI potrzebuje > 120 req/min — użyj trybu **stdio** (tam nie ma limitów, działa bezpośrednio przez `api.astroway.info/v1/*` z twoim limitem taryfowym). ### Co jeśli `mcp.astroway.info` jest tymczasowo niedostępny Jeśli hosted endpoint zwraca 5xx, klient MCP zobaczy błąd przy `tools/list`. To **nie wpływa** na klientów stdio — uruchamiają lokalny pakiet npm, który działa bezpośrednio z `api.astroway.info/v1/*` bez pośredniej warstwy hosted. **Fallback dla krytycznych integracji:** dodaj **drugi serwer MCP** w konfiguracji w trybie stdio — klient automatycznie użyje go, jeśli hosted nie odpowie na `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_..." } } } } ``` Rzeczywisty uptime hosted endpoint widać na [status.astroway.info](https://status.astroway.info). Incydenty > 5 minut publikujemy jako postmortem w ciągu 5 dni roboczych (zgodnie z [/sla/](/sla/)). ## Stdio (npm) — dla lokalnego rozwoju [`@astroway/mcp`](https://www.npmjs.com/package/@astroway/mcp) — pakiet npm uruchamiany lokalnie jako subprocess. Jeden pakiet npm, natywna integracja z Claude Desktop, Cursor i każdym klientem zgodnym z MCP. ## Jak to działa Lista narzędzi jest generowana **w momencie budowania** z live OpenAPI-spec ([api.astroway.info/v1/openapi.json](https://api.astroway.info/v1/openapi.json)). Każde wydanie pakietu automatycznie przechwytuje wszystkie nowe endpointy — nie musisz niczego utrzymywać ręcznie. Każdy endpoint staje się narzędziem postaci: - `tools/list` zwraca opis i schemat wejścia (z przykładem ciała żądania) - `tools/call` wykonuje HTTP POST na `https://api.astroway.info/v1/` z twoim `ASTROWAY_API_KEY` - Odpowiedź jest zwracana agentowi jako ustrukturyzowany JSON Każde wydanie jest również dostarczane z SLSA provenance ([attestowane przez Sigstore](https://search.sigstore.dev/)) — to gwarancja, że pakiet npm został zbudowany z konkretnego commita w publicznym repozytorium. ## Instalacja ### Claude Desktop (macOS) Dodaj do `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "astroway": { "command": "npx", "args": ["-y", "@astroway/mcp"], "env": { "ASTROWAY_API_KEY": "aw_live_..." } } } } ``` Uruchom ponownie Claude Desktop. W pasku pod czatem pojawi się ikona 🛠️ z liczbą załadowanych narzędzi. ### Cursor Dodaj do `~/.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 Ta sama komenda `npx @astroway/mcp` działa w każdym klientem zgodnym z MCP. Konfiguracja jest identyczna — zmienia się tylko ścieżka do pliku: ```json { "mcpServers": { "astroway": { "command": "npx", "args": ["-y", "@astroway/mcp"], "env": { "ASTROWAY_API_KEY": "aw_live_..." } } } } ``` | Klient | Ścieżka do konfiguracji | |---|---| | **Cline** (VS Code) | `.cline/mcp.json` w głównym katalogu przestrzeni roboczej | | **Continue** | `~/.continue/config.json` (w bloku `mcpServers`) | | **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | | **GitHub Copilot Chat (VS Code)** | flaga preview → `mcp.json` w przestrzeni roboczej | | **VS Code MCP extension** | `~/.vscode/mcp.json` | ### Inne klienty MCP Uruchom jako serwer stdio: ```bash ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp ``` ## Prywatność — od v1.0.0+ Ten serwer MCP **nie wysyła niczego z powrotem do AstroWay** poza samymi wywołaniami API, które mu zlecasz. Brak telemetrii, brak analytics, brak przełącznika opt-in/opt-out — cisza domyślnie. Wychodzące żądania zawierają dwa identyfikujące nagłówki, aby backend AstroWay mógł rozróżnić ruch MCP od bezpośredniego HTTP w swoich logach: - `User-Agent: astroway-mcp/ (Node/)` - `X-Astroway-Channel: mcp` Żaden z nich nie zawiera identyfikatora sesji, odcisku maszyny ani niczego osobistego. To standardowa semantyka `User-Agent` — każde narzędzie CLI wysyła podobne informacje. ## Rejestracja podzbioru — od v1.0.0+ Jeśli używasz tylko części katalogu — zarejestruj podzbiór, aby okno kontekstowe LLM pozostało kompaktowe: ```jsonc { "env": { "ASTROWAY_API_KEY": "aw_live_...", "ASTROWAY_TOOL_GROUPS": "western,vedic,relational", // tylko te prefiksy "ASTROWAY_READONLY": "1" // pomiń grupy ai/horoscope/reports (obsługiwane przez LLM, zużywają kredyty) } } ``` Popularne grupy: `western`, `vedic`, `tarot`, `numerology`, `hd` (Human Design), `relational` (synastria/kompozyt/Davison), `prognostics` (transity/progresje/rewolucje), `aspects`, `horary`, `geo`, `chinese`, `bazi`, `mayan`, `iching`, `runes`, `geomancy`. Uruchom `npx @astroway/mcp --list-tools`, aby zobaczyć pełny zestaw. `ASTROWAY_READONLY=1` pomija trzy grupy, które wewnętrznie wywołują LLM (`ai`, `horoscope`, `reports`) — przydatne, gdy chcesz czystą, deterministyczną matematykę kart bez wydawania kredytów na generowanie tekstu. ## Gwarancja stabilności — od v1.0.0+ - **Katalog jest zamrożony na czas sesji.** 624 narzędzi, 12 promptów, 14 zasobów jest wbudowanych w opublikowany pakiet npm w momencie budowania — nic się nie zmienia podczas połączenia. Jeśli twój klient cache'uje `tools/list` po pierwszym wywołaniu, pozostaje poprawny przez całą sesję. - **Identyfikatory narzędzi są stabilne w obrębie wersji major.** Nazwa pod `astroway__` nie zostanie zmieniona ani usunięta wewnątrz `v1.x` bez notki o deprecacji w `CHANGELOG.md` i jednoczesnej dostępności w minorze. - **Kształt wejścia narzędzia jest stabilny w obrębie wersji minor.** Zmiany wciągnięć (regex, zakres, enum) pojawiają się w patchach; dodanie obowiązkowego pola wymaga bumpu minor. - **Odświeżanie katalogu — przez reinstalację.** `npm i -g @astroway/mcp@latest` (lub `npx -y @astroway/mcp` w twojej konfiguracji) pobiera aktualny zestaw przy następnym uruchomieniu. ## Przykładowe prompty Po podłączeniu serwera poproś AI: ### Karta natalna > Oblicz moją kartę natalną — urodzony 15 marca 1990, 14:30, Kijów. Opisz Słońce, Księżyc, Ascendent i znajdź mocne aspekty. Claude wywoła narzędzie `chart` z twoimi parametrami, otrzyma ustrukturyzowany JSON i opisze kartę słownie. ### Tranzyty > Jakie znaczące tranzyty wolnych planet będą miały miejsce w mojej karcie natalnej w 2027 roku? Claude wykonuje dwa wywołania narzędzi: najpierw `transits` (aktualny snapshot), potem `transit-calendar` (zakres). Interpretuje trendy. ### Vedic Mahadasha > Uruchom Vimshottari Mahadasha dla osoby urodzonej 22.07.1985 06:45 w Bombaju. W jakim okresie ta osoba jest teraz? Poprzez narzędzie `vedic/dashas/vimshottari/maha` — dokładny znacznik czasu UTC bieżącego okresu. ### Synastria > Porównaj dwie karty: A — 10.06.1988 09:15 Londyn, B — 22.11.1991 22:40 Berlin. Jakie są najsilniejsze krzyżowe aspekty? Narzędzie `synastry` z dwoma blokami `chart` + interpretacja wyniku. ### Tarot > Wyciągnij 3 karty Rider-Waite-Smith: Przeszłość — Teraźniejszość — Przyszłość. Pytanie: «czy powinienem przyjąć nową pracę?». Seed = 42. Narzędzie `tarot/rider-waite/spread` z ustalonym seedem dla powtarzalności. ## Lista wszystkich narzędzi Po podłączeniu zapytaj Claude: > Wymień wszystkie narzędzia AstroWay. Lub z wiersza poleceń: ```bash ASTROWAY_API_KEY=aw_test_smoke npx @astroway/mcp 2>&1 | head -1 # (uruchamia serwer stdio; wywołania narzędzi list są wykonywane przez klienta MCP) ``` ## Konfiguracja | Zmienna | Domyślnie | Opis | Od wersji | |---|---|---|---| | `ASTROWAY_API_KEY` | *(wymagane)* | Live: `aw_live_...`. Sandbox: `aw_test_...`. | 0.1.0 | | `ASTROWAY_BASE_URL` | `https://api.astroway.info/v1` | Przesłonięcie dla self-hosted/staging środowisk. | 0.1.0 | | `ASTROWAY_TOOL_GROUPS` | *(wszystkie grupy)* | Oddzielone przecinkami prefiksy do ograniczenia katalogu (`western,vedic,relational`). | 1.0.0 | | `ASTROWAY_READONLY` | `0` | `1` pomija grupy obsługiwane przez LLM (`ai`, `horoscope`, `reports`). | 1.0.0 | | `LOG_LEVEL` | `error` | `silent`/`error`/`warn`/`info`/`debug` — poziom logowania do stderr. | 0.8.0 | | `LOG_FILE` | *(nie zapisywany)* | Ścieżka do pliku dla duplikowania logów. | 0.8.0 | | `MCP_FLAT_TOOLS` | `0` | `1` zwraca stare nazwy flat z przed v0.9 (`chart` zamiast `astroway_western_chart`). Legacy. | 0.9.0 | ## Dlaczego MCP, a nie bezpośrednia integracja Ogólny LLM (bez grounding) powie *«gdzieś w lipcu Saturn utworzy trójkąt do twojego Jowisza»* — bez dokładnej daty, z dryfem ±15 dni. **Agent MCP** wykonuje `tool_use POST /v1/transits` i zwraca znacznik czasu UTC **do sekundy**, na prawdziwym Swiss Ephemeris. Zaleta nie tkwi w LLM, ale w **gwarancji, że matematyka jest rzeczywista** — nie wymyślona. ## Dystrybucja pakietu - **mcp.so listing:** [mcp.so/server/astroway-mcp/astroway](https://mcp.so/server/astroway-mcp/astroway) - **mcpservers.org:** oczekuje na zatwierdzenie (stan na maj 2026) - **awesome-mcp-servers (punkpeye):** [PR #5972](https://github.com/punkpeye/awesome-mcp-servers/pull/5972) ## Linki - 📦 npm: [npmjs.com/package/@astroway/mcp](https://www.npmjs.com/package/@astroway/mcp) - 📘 Dokumentacja API: [/docs/api/](/docs/api/) - 🔑 Rejestracja: [/dashboard/sign-up](/dashboard/sign-up) - 💰 Cennik: [/pricing/](/pricing/) - 🌐 Publiczne repo (MIT): [github.com/astroway/astroway-mcp](https://github.com/astroway/astroway-mcp)