MCP — підключення Claude / Cursor

@astroway/mcp — це Model Context Protocol сервер, який експонує усі 705 ендпоінтів AstroWay як інструменти для AI-агента. Один npm-пакет, нативна інтеграція з Claude Desktop, Cursor та будь-яким MCP-сумісним клієнтом.

Source: github.com/astroway/astroway-mcp · npm: npmjs.com/package/@astroway/mcp

Як це працює

Tool list генерується на момент білда з live OpenAPI-spec (api.astroway.info/v1/openapi.json). Кожен реліз пакета автоматично підхоплює усі нові ендпоінти — нічого вручну підтримувати не треба.

Кожен ендпоінт стає інструментом виду:

tools/list повертає опис та схему вводу (з прикладом тіла запиту)
tools/call робить HTTP POST на https://api.astroway.info/v1/<path> із вашим ASTROWAY_API_KEY
Відповідь повертається агенту як structured JSON

Кожен реліз ще й ship’иться з SLSA provenance (Sigstore-attested) — це гарантія що npm-пакет збудований саме з commit’у в публічному репо.

Встановлення

Claude Desktop (macOS)

Додай у ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Перезапусти Claude Desktop. У бару під чатом з’явиться 🛠️ індикатор з кількістю завантажених tool-ів.

Cursor

Додай у ~/.cursor/mcp.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-сумісному клієнті. Конфіг ідентичний — змінюється лише шлях до файлу:

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

Клієнт	Шлях до конфіга
Cline (VS Code)	`.cline/mcp.json` у корені workspace
Continue	`~/.continue/config.json` (під `mcpServers`)
Windsurf	`~/.codeium/windsurf/mcp_config.json`
GitHub Copilot Chat (VS Code)	preview-флаг → `mcp.json` у workspace
VS Code MCP extension	`~/.vscode/mcp.json`

Інші MCP клієнти

Запусти як stdio-сервер:

ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp

Privacy — з v1.0.0+

Цей MCP-сервер не відправляє нічого назад до AstroWay окрім самих API-викликів які ти йому даєш виконати. Жодної телеметрії, жодного analytics, жодного opt-in/opt-out перемикача — тиша за замовчуванням.

Вихідні запити несуть два ідентифікаційні заголовки щоб AstroWay backend міг розрізняти MCP-трафік від прямого HTTP у власних логах:

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

Жоден з них не містить session ID, machine fingerprint чи будь-чого персонального. Це стандартна User-Agent семантика — кожен CLI-інструмент шле подібну інформацію.

Subset registration — з v1.0.0+

Якщо використовуєш лише частину каталогу — реєструй підмножину щоб контекстне вікно LLM залишалося компактним:

{
  "env": {
    "ASTROWAY_API_KEY": "aw_live_...",
    "ASTROWAY_TOOL_GROUPS": "western,vedic,relational",   // лише ці префікси
    "ASTROWAY_READONLY": "1"                               // skip ai/horoscope/reports (LLM-backed, тратять кредити)
  }
}

Поширені групи: western, vedic, tarot, numerology, hd (Human Design), relational (synastry/composite/davison), prognostics (transits/progressions/returns), aspects, horary, geo, chinese, bazi, mayan, iching, runes, geomancy. Запусти npx @astroway/mcp --list-tools щоб побачити повний набір.

ASTROWAY_READONLY=1 пропускає три групи що внутрішньо викликають LLM (ai, horoscope, reports) — корисно коли хочеш чисту детерміновану математику карт без витрат кредитів на генерацію тексту.

Stability commitment — з v1.0.0+

Каталог заморожений на час сесії. 624 tools, 12 prompts, 14 resources вшиті в опублікований npm-пакет на момент білду — нічого не змінюється під час підключення. Якщо твій клієнт кешує tools/list після першого виклику — він залишається коректним для всієї сесії.
Tool identifiers стабільні в межах major версії. Імʼя під astroway_<group>_<tool> не буде перейменоване чи видалене всередині v1.x без deprecation note в CHANGELOG.md та одно-minor парралельної доступності.
Tool input shape стабільний в межах minor версії. Затягування (regex, range, enum) приходить у патчах; додавання обовʼязкового поля вимагає minor bump.
Refresh каталогу — переустановкою. npm i -g @astroway/mcp@latest (або npx -y @astroway/mcp форма у твоєму конфізі) підтягує поточний набір при наступному старті.

Приклади промптів

Після підключення сервера попроси AI:

Натальна карта

Розрахуй мою натальну карту — народжений 15 березня 1990, 14:30, Київ. Опиши Сонце, Місяць, Асцендент і знайди тісні аспекти.

Claude викличе chart tool з твоїми параметрами, отримає структурований JSON, і опише карту словами.

Транзити

Які значущі транзити повільних планет припадуть на мою натал-карту впродовж 2027 року?

Claude робить два tool-call’и: спочатку transits (поточний знімок), потім transit-calendar (діапазон). Інтерпретує тренди.

Vedic Mahadasha

Запусти Vimshottari Mahadasha для людини, народженої 22.07.1985 06:45 у Мумбаї. У якому періоді ця людина зараз?

Через vedic/dashas/vimshottari/maha tool — точний UTC-timestamp поточного періоду.

Synastry

Порівняй дві карти: А — 10.06.1988 09:15 Лондон, Б — 22.11.1991 22:40 Берлін. Які найсильніші крос-аспекти?

synastry tool з двома chart блоками + інтерпретація балу сумісності.

Tarot

Витягни 3 карти Rider-Waite-Smith: Минуле — Теперішнє — Майбутнє. Питання: «чи варто прийняти нову роботу?». Seed = 42.

tarot/rider-waite/spread з фіксованим seed для відтворюваності.

Список усіх tool-ів

Після підключення спитай у Claude:

Перерахуй усі astroway-інструменти.

Або з командного рядка:

ASTROWAY_API_KEY=aw_test_smoke npx @astroway/mcp 2>&1 | head -1
# (запускає stdio-сервер; протокольні tool-list виклики йдуть від MCP клієнта)

Конфігурація

Змінна	За замовчуванням	Опис	З версії
`ASTROWAY_API_KEY`	(обовʼязково)	Live: `aw_live_...`. Sandbox: `aw_test_...`.	0.1.0
`ASTROWAY_BASE_URL`	`https://api.astroway.info/v1`	Override для self-hosted/staging-середовищ.	0.1.0
`ASTROWAY_TOOL_GROUPS`	(всі групи)	Comma-separated префікси для обмеження каталогу (`western,vedic,relational`).	1.0.0
`ASTROWAY_READONLY`	`0`	`1` пропускає LLM-backed групи (`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` повертає pre-v0.9 flat-імена (`chart` замість `astroway_western_chart`). Legacy.	0.9.0

Чому MCP, а не пряма інтеграція

Generic LLM (без grounding) скаже «десь у липні Сатурн утворить тригон до твого Юпітера» — без точної дати, з ±15 днів дрифтом. MCP-агент робить tool_use POST /v1/transits і повертає UTC-timestamp до секунди, на справжньому Swiss Ephemeris.

Перевага не в LLM, а в гарантії що математика реальна — не вигадана.