# MCP — σύνδεση Claude / Cursor
Ο διακομιστής **AstroWay MCP** εκθέτει **όλους τους {siteMeta.endpoints} τελικούς πόντους** ως εργαλεία για έναν πράκτορα AI. Υπάρχουν δύο λειτουργίες — και οι δύο υποστηρίζονται εγγενώς από όλους τους πελάτες συμβατούς με το MCP.
| Λειτουργία | URL / εντολή | Πότε να επιλέξεις |
|---|---|---|
| **Hosted HTTP** | `https://mcp.astroway.info/mcp` | Claude Web (claude.ai στον browser), Claude Desktop / Cursor / Code newcomers χωρίς npm, ή όταν θέλεις zero-install |
| **Stdio (npm)** | `npx @astroway/mcp` | Power users του Cursor, τοπική ανάπτυξη, privacy-conscious (το κλειδί δεν εγκαταλείπει ποτέ τον υπολογιστή σου), offline-ready |
Το hosted endpoint και το npm package χρησιμοποιούν **τον ίδιο κατάλογο εργαλείων** (γεννιέται από ένα `/v1/openapi.json`). Auth: ίδιος κλειδί `aw_test_*` / `aw_live_*` API — στο hosted στέλνεται μέσω `Authorization: Bearer …` header, στο stdio μέσω μεταβλητής περιβάλλοντος `ASTROWAY_API_KEY`.
Πηγή: [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
Γρήγορη εκκίνηση χωρίς npm — επίλεξε τον πελάτη σου. Πριν εγκαταστήσεις, πήγαινε στο [api.astroway.info/dashboard/sign-up](https://api.astroway.info/dashboard/sign-up) για να πάρεις ένα κλειδί (10.000 πιστώσεις/μήνα δωρεάν).
Κάνε κλικ στο κουμπί — το Cursor θα ανοίξει, θα σου ζητήσει επιβεβαίωση, και θα προσθέσει αυτόματα την εγγραφή:
Εγκατάσταση στο Cursor →
:::caution[Υποχρεωτικό 2ο βήμα — διαφορετικά δεν θα λειτουργήσει]
Το Cursor δεν μπορεί να αντικαταστήσει το μυστικό από το deeplink — στο `~/.cursor/mcp.json` θα γραφτεί το γράμμα `Bearer YOUR_API_KEY`, στο οποίο ο διακομιστής απαντά με `403 invalid_format`.
**Μετά το κλικ στο κουμπί:**
1. **Cursor Settings** (⚙️ πάνω δεξιά γωνία) → **Tools & MCP** → βρες το `astroway-hosted` στη λίστα.
2. Κάνε κλικ στις τρεις τελείες (`⋯`) δίπλα από τον διακομιστή → **Edit configuration**.
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`).
:::
Χωρίς επεξεργασία JSON. Σε οποιαδήποτε συνομιλία του Claude Desktop:
1. Κάνε κλικ στο **`+`** αριστερά από το πεδίο εισόδου → στο μενού επίλεξε **"Add connector"**.
2. Στο παράθυρο διαλόγου επίλεξε **"Add custom connector"**.
3. **Όνομα:** `astroway-hosted`
4. **URL:** `https://mcp.astroway.info/mcp`
5. Άνοιξε τις **"Advanced settings"** → στο **"Custom headers"** πρόσθεσε:
- **Κλειδί:** `Authorization`
- **Τιμή:** `Bearer aw_live_...` (το δικό σου κλειδί)
6. **Add** → βρες το `astroway-hosted` στη λίστα Connectors, ενεργοποίησε τον διακόπτη.
Δεν χρειάζεται να επανεκκινήσεις το Claude Desktop. Κάνε κλικ στο `+` σε μια νέα συνομιλία — στη λίστα Connectors θα εμφανιστεί το `astroway-hosted` με όλα τα 630 εργαλεία + 12 προτροπές + 14 πόρους.
Για 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` (globally) ή `.cursor/mcp.json` (στο workspace)
- **Cline (VS Code):** `.cline/mcp.json` στο workspace
- **Continue:** `~/.continue/config.json` (block `mcpServers`)
- **Windsurf:** `~/.codeium/windsurf/mcp_config.json`
Μετά την επεξεργασία επανεκκίνησε πλήρως τον πελάτη (Cmd+Q → άνοιξε ξανά).
### Έλεγχος
```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`, …
### Όρια ρυθμού
Το hosted endpoint προστατεύεται από τριών επιπέδων περιορισμό: Cloudflare DDoS layer + nginx `120 req/min/IP` + in-memory bucket `60/60s/(IP+key)`. Οι πραγματικοί πελάτες MCP (Claude Desktop, Cursor) δεν πλησιάζουν αυτά τα όρια — δεν κάνουν burst-запросы. Αν η αυτοματοποίησή σου / CI χρειάζεται > 120 req/min — χρησιμοποίησε τη λειτουργία **stdio** (εκεί δεν υπάρχουν όρια, πηγαίνει απευθείας μέσω `api.astroway.info/v1/*` με τον δικό σου περιορισμό του προγράμματος τιμών).
### Τι γίνεται αν το `mcp.astroway.info` είναι προσωρινά μη διαθέσιμο
Αν το hosted endpoint επιστρέψει 5xx, ο πελάτης MCP θα δει ένα σφάλμα κατά το `tools/list`. Αυτό **δεν επηρεάζει** τους πελάτες stdio — αυτοί εκτελούν το τοπικό npm package, το οποίο πηγαίνει απευθείας στο `api.astroway.info/v1/*` χωρίς ενδιάμεσο hosted layer.
**Fallback για κρίσιμες ολοκληρώσεις:** πρόσθεσε έναν **δεύτερο διακομιστή MCP** στη ρύθμιση στη λειτουργία stdio — ο πελάτης θα χρησιμοποιήσει αυτόματα τον δεύτερο διακομιστή αν το hosted δεν απαντήσει στο `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 του hosted endpoint φαίνεται στο [status.astroway.info](https://status.astroway.info). Τα περιστατικά > 5 λεπτών δημοσιεύονται ως postmortem εντός 5 εργάσιμων ημερών (σύμφωνα με το [/sla/](/sla/)).
## Stdio (npm) — για τοπική ανάπτυξη
Το [`@astroway/mcp`](https://www.npmjs.com/package/@astroway/mcp) είναι ένα npm package που εκτελείται τοπικά ως subprocess. Ένα npm package, εγγενής ολοκλήρωση με το Claude Desktop, το Cursor και οποιονδήποτε πελάτη συμβατό με το MCP.
## Πώς λειτουργεί
Ο κατάλογος εργαλείων δημιουργείται **κατά τη στιγμή της build** από το live OpenAPI-spec ([api.astroway.info/v1/openapi.json](https://api.astroway.info/v1/openapi.json)). Κάθε έκδοση του package αυτόματα συμπεριλαμβάνει όλα τα νέα τελικά σημεία — δεν χρειάζεται χειροκίνητη συντήρηση.
Κάθε τελικό σημείο γίνεται ένα εργαλείο της μορφής:
- `tools/list` επιστρέφει την περιγραφή και το σχήμα εισόδου (με παράδειγμα σώματος αιτήματος)
- `tools/call` κάνει HTTP POST στο `https://api.astroway.info/v1/` με το δικό σου `ASTROWAY_API_KEY`
- Η απάντηση επιστρέφεται στον πράκτορα ως structured JSON
Κάθε έκδοση συνοδεύεται επίσης από SLSA provenance ([Sigstore-attested](https://search.sigstore.dev/)) — αυτή είναι η εγγύηση ότι το npm package κατασκευάστηκε από το συγκεκριμένο commit στο δημόσιο αποθετήριο.
## Εγκατάσταση
### 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` στη ρίζα του workspace |
| **Continue** | `~/.continue/config.json` (υπό `mcpServers`) |
| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
| **GitHub Copilot Chat (VS Code)** | preview flag → `mcp.json` στο workspace |
| **VS Code MCP extension** | `~/.vscode/mcp.json` |
### Άλλοι πελάτες MCP
Εκτέλεσε ως stdio server:
```bash
ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp
```
## Privacy — από την v1.0.0+
Αυτός ο διακομιστής MCP **δεν στέλνει τίποτα πίσω στο AstroWay** εκτός από τις κλήσεις API που του δίνεις να εκτελέσει. Καμία τηλεμετρία, κανένα analytics, κανένας διακόπτης opt-in/opt-out — σιωπή από προεπιλογή.
Τα εξερχόμενα αιτήματα φέρουν δύο επικεφαλίδες ταυτοποίησης ώστε το backend του AstroWay να μπορεί να ξεχωρίζει την κίνηση MCP από απευθείας HTTP στα δικά του logs:
- `User-Agent: astroway-mcp/ (Node/)`
- `X-Astroway-Channel: mcp`
Κανένας από αυτούς δεν περιέχει session ID, machine fingerprint ή κάτι προσωπικό. Πρόκειται για τυπική ημαντική του `User-Agent` — κάθε εργαλείο CLI στέλνει παρόμοιες πληροφορίες.
## Subset registration — από την v1.0.0+
Αν χρησιμοποιείς μόνο μέρος του καταλόγου — εγγραφή μόνο την υποσύνοψη ώστε το παράθυρο περιβάλλοντος του LLM να παραμένει συμπαγές:
```jsonc
{
"env": {
"ASTROWAY_API_KEY": "aw_live_...",
"ASTROWAY_TOOL_GROUPS": "western,vedic,relational", // μόνο αυτές οι ομάδες
"ASTROWAY_READONLY": "1" // παράλειψη 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`) — χρήσιμο όταν θέλεις καθαρή ντετερμινιστική μαθηματική των χαρτών χωρίς να καταναλώνεις πιστώσεις για δημιουργία κειμένου.
## Commitment σταθερότητας — από την v1.0.0+
- **Ο κατάλογος είναι σταθερός κατά τη διάρκεια μιας συνεδρίας.** 624 εργαλεία, 12 προτροπές, 14 πόροι είναι ενσωματωμένοι στο δημοσιευμένο npm package κατά τη στιγμή της build — τίποτα δεν αλλάζει κατά τη διάρκεια της σύνδεσης. Αν ο πελάτης σου κάνει cache στο `tools/list` μετά την πρώτη κλήση, παραμένει σωστό για ολόκληρη τη συνεδρία.
- **Οι ταυτότητες εργαλείων είναι σταθερές εντός μιας major έκδοσης.** Το όνομα υπό `astroway__` δε θα μετονομαστεί ή διαγραφεί εντός του `v1.x` χωρίς σημείωση εγκατάλειψης στο `CHANGELOG.md` και παράλληλη διαθεσιμότητα για ένα minor.
- **Το σχήμα εισόδου εργαλείου είναι σταθερό εντός μιας minor έκδοσης.** Οι περιορισμοί (regex, range, enum) έρχονται με patches· η προσθήκη ενός υποχρεωτικού πεδίου απαιτεί bump minor.
- **Ανανέωση καταλόγου — επανεγκατάσταση.** `npm i -g @astroway/mcp@latest` (ή η μορφή `npx -y @astroway/mcp` στη δική σου ρύθμιση) φέρνει τον τρέχοντα κατάλογο στην επόμενη εκκίνηση.
## Παραδείγματα προτροπών
Αφού συνδέσεις τον διακομιστή ζήτησε από τον AI:
### Natal chart
> Υπολόγισε το natal chart μου — γεννημένος στις 15 Μαρτίου 1990, 14:30, Κίεβο. Περιέγραψε τον Ήλιο, τη Σελήνη, τον Ascendant και βρες τους στενούς αспекτούς.
Ο Claude θα καλέσει το εργαλείο `chart` με τις παραμέτρους σου, θα λάβει μια δομημένη JSON, και θα περιγράψει το chart με λέξεις.
### Transits
> Ποιες σημαντικές transits των αργών πλανητών θα συμβούν στο natal chart μου κατά τη διάρκεια του 2027;
Ο Claude κάνει δύο κλήσεις εργαλείων: πρώτα `transits` (τρέχουσα στιγμή), μετά `transit-calendar` (διάστημα). Ερμηνεύει τις τάσεις.
### Vedic Mahadasha
> Εκτέλεσε το Vimshottari Mahadasha για ένα άτομο γεννημένο στις 22.07.1985 06:45 στη Μουμπάι. Σε ποια περίοδο βρίσκεται αυτό το άτομο τώρα;
Μέσω του εργαλείου `vedic/dashas/vimshottari/maha` — ακριβής timestamp UTC της τρέχουσας περιόδου.
### Synastry
> Σύγκρινε δύο charts: Α — 10.06.1988 09:15 Λονδίνο, Β — 22.11.1991 22:40 Βερολίνο. Ποιες είναι οι ισχυρότερες cross-aspects;
Το εργαλείο `synastry` με δύο blocks `chart` + ερμηνεία της βαθμολογίας συμβατότητας.
### Tarot
> Τράβηξε 3 κάρτες Rider-Waite-Smith: Παρελθόν — Παρόν — Μέλλον. Ερώτηση: «πρέπει να δεχτώ τη νέα δουλειά;». Seed = 42.
Το `tarot/rider-waite/spread` με σταθερό seed για αναπαραγωγιμότητα.
## Κατάλογος όλων των εργαλείων
Αφού συνδέσεις τον διακομιστή ζήτησε από τον Claude:
> List all astroway tools.
Ή από τη γραμμή εντολών:
```bash
ASTROWAY_API_KEY=aw_test_smoke npx @astroway/mcp 2>&1 | head -1
# (εκκινεί τον stdio server· οι κλήσεις εργαλείων πρωτοκόλλου γίνονται από τον πελάτη 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 prefixes για περιορισμό καταλόγου (`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` | *(δεν γράφεται)* | Διαδρομή αρχείου για αντιγραφή logs. | 0.8.0 |
| `MCP_FLAT_TOOLS` | `0` | `1` επιστρέφει ονόματα flat παλαιότερης έκδοσης (`chart` αντί `astroway_western_chart`). Legacy. | 0.9.0 |
## Γιατί MCP και όχι απευθείας ολοκλήρωση
Ένας γενικός LLM (χωρίς grounding) μπορεί να πει *«κάπου τον Ιούλιο ο Κρόνος θα σχηματίσει τρίγωνο στον Δία σου»* — χωρίς ακριβή ημερομηνία, με απόκλιση ±15 ημερών. **Ένας πράκτορας MCP** κάνει `tool_use POST /v1/transits` και επιστρέφει timestamp UTC **μέχρι το δευτερόλεπτο**, χρησιμοποιώντας πραγματικό Swiss Ephemeris.
Το πλεονέκτημα δεν είναι στον LLM, αλλά στην **εγγύηση ότι τα μαθηματικά είναι πραγματικά** — όχι φανταστικά.
## Διανομή του package
- **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: [/docs/api/](/docs/api/)
- 🔑 Εγγραφή: [/dashboard/sign-up](/dashboard/sign-up)
- 💰 Τιμολόγηση: [/pricing/](/pricing/)
- 🌐 Δημόσιο αποθετήριο (MIT): [github.com/astroway/astroway-mcp](https://github.com/astroway/astroway-mcp)