@cosmosos/mcp-ephemeris 0.1.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +112 -66
  2. package/dist/index.js +1276 -129
  3. package/package.json +10 -4
package/README.md CHANGED
@@ -1,17 +1,19 @@
1
1
  # @cosmosos/mcp-ephemeris
2
2
 
3
- **Le vrai ciel, pour votre IA.** Un serveur [MCP](https://modelcontextprotocol.io)
4
- qui donne à n'importe quel assistant (Claude, Cursor, agents) des **positions
5
- planétaires calculées** — jamais devinées — grâce au moteur d'éphémérides
6
- [Swiss Ephemeris](https://www.astro.com/swisseph/), et **validées contre
7
- JPL Horizons (NASA)** à moins d'une seconde d'arc.
3
+ **The real sky, for your AI.** An [MCP](https://modelcontextprotocol.io) server
4
+ that gives any assistant (Claude, Cursor, agents) **computed planetary
5
+ positions** — never guessed — powered by the
6
+ [Swiss Ephemeris](https://www.astro.com/swisseph/) engine, and **validated
7
+ against JPL Horizons (NASA)** to under one arcsecond.
8
8
 
9
- > **Principe cardinal : le LLM ne calcule jamais.** Ce serveur est une façade sur
10
- > un moteur d'éphémérides. Le modèle interprète ; le ciel, lui, est un fait.
9
+ > **Cardinal rule: the LLM never computes.** This server is a facade over an
10
+ > ephemeris engine. The model interprets; the sky is a fact.
11
11
 
12
- ## Démarrage rapide (Claude Desktop)
12
+ *(Version française : <https://llmastro.com/notre-moteur>)*
13
13
 
14
- Ouvrez **Réglages → Développeur → Modifier la configuration**, puis ajoutez&nbsp;:
14
+ ## Quick start (Claude Desktop)
15
+
16
+ Open **Settings → Developer → Edit Config**, then add:
15
17
 
16
18
  ```json
17
19
  {
@@ -24,84 +26,128 @@ Ouvrez **Réglages → Développeur → Modifier la configuration**, puis ajoute
24
26
  }
25
27
  ```
26
28
 
27
- Quittez complètement Claude Desktop (barre des tâches) et relancez-le. Demandez
28
- ensuite&nbsp;: *« Quelle est la phase de la Lune aujourd'hui ? »* — Claude appelle
29
- le serveur et répond à partir de positions réellement calculées.
29
+ Fully quit Claude Desktop (system tray) and relaunch it. Then ask:
30
+ *"What's the moon phase today?"* — Claude calls the server and answers from
31
+ genuinely computed positions.
32
+
33
+ **Cursor / Windsurf / others**: add the same `llmastro` entry
34
+ (`command: npx`, `args: ["-y", "@cosmosos/mcp-ephemeris"]`) to your client's MCP
35
+ configuration.
30
36
 
31
- **Cursor / Windsurf / autres** : ajoutez la même entrée `llmastro`
32
- (`command: npx`, `args: ["-y", "@cosmosos/mcp-ephemeris"]`) dans la configuration
33
- MCP de votre client.
37
+ ## Tools exposed
34
38
 
35
- ## Outils exposés
39
+ **19 tools**, all backed by the same server-side computed engine.
40
+
41
+ ### Positions & sky
42
+ | Tool | Input | Output |
43
+ |---|---|---|
44
+ | `get_planet_positions` | `datetime` (ISO UTC) | ecliptic positions of all bodies (sign, degree, retro) |
45
+ | `get_moon_phase` | `datetime` (ISO UTC) | moon phase, illumination %, description |
46
+ | `get_current_sky` | `latitude`, `longitude` | the sky right now (current transits) for a place |
47
+ | `get_aspects` | `datetime` (ISO UTC) | grid of major + minor aspects between bodies |
48
+
49
+ ### Natal chart & relationships
50
+ | Tool | Input | Output |
51
+ |---|---|---|
52
+ | `get_natal_chart` | birth + `zodiac` (tropical/sidereal), `houseSystem` (7 systems) | full chart: houses, aspects, ASC/MC, moon phase, Hermetic Lots |
53
+ | `get_transits` | birth + optional `datetime` | transit→natal aspects, sorted by orb |
54
+ | `get_synastry` | two births | inter-chart aspects + harmony/tension summary |
55
+ | `get_composite_chart` | two births | midpoint composite chart |
56
+ | `get_secondary_progressions` | birth + `targetDate` | progressed positions ("a day for a year") |
57
+ | `get_solar_return` | birth + `year` (+ optional place) | instant + chart of the solar return |
58
+ | `get_lunar_return` | birth + optional `after` | instant + chart of the next lunar return |
59
+
60
+ ### Celestial events
61
+ | Tool | Input | Output |
62
+ |---|---|---|
63
+ | `get_ingresses` | `body`, `start`, `end` | sign-change dates (retrograde-robust) |
64
+ | `get_retrograde_windows` | `body`, `start`, `end` | retrograde/direct stations over the range |
65
+ | `get_eclipse_details` | `datetime`, `kind` | magnitude, obscuration, Saros of a known eclipse *(swisseph)* |
66
+ | `get_next_eclipse` | `from`, `kind`, optional `backward` | next/previous eclipse: maximum, type, contacts *(swisseph)* |
36
67
 
37
- | Outil | Entrée | Sortie |
68
+ ### Astrocartography, numerology, authority
69
+ | Tool | Input | Output |
38
70
  |---|---|---|
39
- | `get_planet_positions` | `datetime` (ISO UTC) | positions écliptiques de tous les corps (signe, degré, rétro) |
40
- | `get_moon_phase` | `datetime` (ISO UTC) | phase lunaire, illumination %, description |
41
- | `get_natal_chart` | `date`, `time`, `timezone` (IANA), `latitude`, `longitude` | thème complet : planètes en maisons, aspects, ASC/MC, phase lunaire |
42
- | `get_current_sky` | `latitude`, `longitude` | le ciel maintenant (transits du moment) pour un lieu |
43
- | `get_astrocartography` | `datetime` (ISO UTC) | lignes planétaires MC/IC + parans (croisements) |
44
- | `get_transits` | naissance + `datetime` optionnel | aspects transit→natal, triés par orbe (cœur des « prévisions ») |
45
- | `validate_against_horizons` | `datetime` (ISO UTC), `bodies` optionnel | écart de nos positions vs JPL Horizons (NASA) en secondes d'arc — réseau requis |
71
+ | `get_astrocartography` | `datetime` (ISO UTC) | planetary MC/IC lines + parans (crossings) |
72
+ | `get_life_path` | `date` (YYYY-MM-DD) | life-path number (numerology) |
73
+ | `get_engine_diagnostic` | — | active engine, native addon load status, real precision |
74
+ | `validate_against_horizons` | `datetime`, optional `bodies` | delta of our positions vs JPL Horizons (NASA) in arcseconds — network required |
46
75
 
47
- ## Précision
76
+ *(swisseph)* = requires the native Swiss Ephemeris addon; returns `null` on the AstraCore fallback.
48
77
 
49
- Sous [Swiss Ephemeris](https://www.astro.com/swisseph/), les positions
50
- correspondent à la référence mondiale **JPL Horizons (NASA)** à moins d'une
51
- seconde d'arc (mesuré au 2026-07-19) :
78
+ ## Precision
52
79
 
53
- | Corps | Écart vs NASA |
80
+ Under [Swiss Ephemeris](https://www.astro.com/swisseph/), positions match the
81
+ world reference **JPL Horizons (NASA)** to under one arcsecond (measured
82
+ 2026-07-19):
83
+
84
+ | Body | Difference vs NASA |
54
85
  |---|---|
55
- | Soleil | 0,2″ |
56
- | Lune | 1,5″ |
57
- | Jupiter | 0,1″ |
58
- | Pluton | 0,4″ |
86
+ | Sun | 0.2″ |
87
+ | Moon | 1.5″ |
88
+ | Jupiter | 0.1″ |
89
+ | Pluto | 0.4″ |
59
90
 
60
- Vérifiez-le vous-même avec l'outil `validate_against_horizons`.
91
+ Check it yourself with the `validate_against_horizons` tool.
61
92
 
62
- ## Deux moteurs
93
+ ## Two engines
63
94
 
64
- Le calcul est routé selon la variable `ASTRO_ENGINE` :
95
+ Computation is routed by the `ASTRO_ENGINE` variable:
65
96
 
66
- - **`swisseph`** (par défaut) — Swiss Ephemeris, addon natif, précision
67
- sub-arcseconde. Se compile automatiquement là où une chaîne de build C++ est
68
- présente (Linux, macOS, la plupart des serveurs).
69
- - **`astracore`** — moteur maison pur TypeScript (VSOP/Meeus), **sans binaire
70
- natif**. Utilisé en repli automatique quand `swisseph` n'a pas pu être compilé
71
- (fréquent sous Windows). Soleil et Lune restent précis&nbsp;; les planètes
72
- externes dérivent de quelques minutes d'arc.
97
+ - **`swisseph`** (default) — Swiss Ephemeris, native addon, sub-arcsecond
98
+ precision. Compiles automatically wherever a C++ build chain is present
99
+ (Linux, macOS, most servers).
100
+ - **`astracore`** — in-house pure-TypeScript engine (VSOP/Meeus), **no native
101
+ binary**. Used as an automatic fallback when `swisseph` couldn't be compiled
102
+ (common on Windows). Sun and Moon stay accurate; outer planets drift by a few
103
+ arcminutes.
73
104
 
74
- Pour forcer un moteur : `ASTRO_ENGINE=swisseph` ou `ASTRO_ENGINE=astracore`.
105
+ To force an engine: `ASTRO_ENGINE=swisseph` or `ASTRO_ENGINE=astracore`.
75
106
 
76
- ## Confidentialité
107
+ ## Privacy
77
108
 
78
- Le serveur tourne **sur votre machine** : vos données de naissance ne sont
79
- envoyées nulle part. Seul `validate_against_horizons` effectue une requête
80
- sortante (vers l'API publique de la NASA).
109
+ The server runs **on your machine**: your birth data is sent nowhere. Only
110
+ `validate_against_horizons` makes an outbound request (to NASA's public API).
81
111
 
82
- ## Prérequis
112
+ ## Requirements
83
113
 
84
114
  - Node.js ≥ 20.
85
- - Pour la précision maximale (`swisseph`) : une chaîne de build C++
86
- (`python3`, `make`, un compilateur) sur la machine. Sinon, repli automatique
87
- sur `astracore`, sans configuration.
115
+ - For maximum precision (`swisseph`): a C++ build chain (`python3`, `make`, a
116
+ compiler) on the machine. Otherwise, automatic fallback to `astracore`, with
117
+ no configuration.
118
+
119
+ ## About
120
+
121
+ Powered by the astrology engine of [Llmastro](https://llmastro.com). Learn more
122
+ about the precision and architecture: <https://llmastro.com/notre-moteur>.
88
123
 
89
- ## À propos
124
+ ## License
90
125
 
91
- Propulsé par le moteur d'astrologie de [Llmastro](https://llmastro.com). En
92
- savoir plus sur la précision et l'architecture :
93
- <https://llmastro.com/notre-moteur>.
126
+ **Free for non-commercial use** (personal, research, education, non-profit
127
+ organizations) — under the
128
+ [PolyForm Noncommercial 1.0.0](./LICENSE) license.
94
129
 
95
- ## Licence
130
+ **Commercial / professional use: a paid license is required.** To obtain one,
131
+ contact KAIROSAST LTD via <https://llmastro.com/contact>.
96
132
 
97
- **Gratuit pour un usage non commercial** (personnel, recherche, éducation,
98
- organisations à but non lucratif) — sous licence
99
- [PolyForm Noncommercial 1.0.0](./LICENSE).
133
+ Note: the optional `swisseph` dependency (Swiss Ephemeris, Astrodienst) has its
134
+ own license (AGPL or a commercial Swiss Ephemeris license) and is not covered by
135
+ this one. Professional use must comply with it separately.
100
136
 
101
- **Usage commercial / professionnel : licence payante requise.** Pour l'obtenir,
102
- contactez KAIROSAST LTD via <https://llmastro.com/contact>.
137
+ ## Development
138
+
139
+ This repository is **self-contained**: the ephemeris engine is vendored in
140
+ `vendor/ephemeris/` (source), and the build inlines it into `dist/` via
141
+ [`tsup`](https://tsup.egoist.dev/).
142
+
143
+ ```bash
144
+ pnpm install # or npm install
145
+ pnpm build # bundles dist/index.js (engine inlined)
146
+ pnpm start # runs the MCP server (stdio) locally
147
+ ```
103
148
 
104
- À noter : la dépendance optionnelle `swisseph` (Swiss Ephemeris, Astrodienst) a
105
- sa propre licence (AGPL ou licence commerciale Swiss Ephemeris) et n'est pas
106
- couverte par la présente. Les usages professionnels doivent s'y conformer
107
- séparément.
149
+ - Default engine: `swisseph` (sub-arcsecond precision) if the native addon
150
+ compiles, otherwise automatic fallback to `astracore` (pure TypeScript, no
151
+ binary). Force via `ASTRO_ENGINE=swisseph|astracore`.
152
+ - The vendored engine is a snapshot of `@astro-platform/ephemeris` (Llmastro),
153
+ re-synced manually.