# Psychomantic · Corpus complet pour agents (llms-full)
# Fichier généré par `node scripts/build-llms-full.mjs`. Ne pas éditer à la main.
# Index et résumé : /llms.txt · Référence interactive : https://api.psychomantic.com/docs

## Sommaire
1. Plan du corpus (llms.txt)
2. Référence API publique (OpenAPI 3.0)
3. Certification de précision (JPL Horizons)
4. SDK TypeScript (ishtarengine-sdk)
5. Serveur MCP (@ishtarengine/mcp)
6. Exemples d'appel

---

# 1. Plan du corpus (llms.txt)

# Psychomantic : calcul astrologique et astronomique de précision pour les agents IA
# Summary: Deterministic astrology/astronomy computation engine (NASA JPL DE442 ephemeris, in-house DE442Q kernel) for AI agents and developers
# Version: 7.0.0
# Data Source: kernel quantifié maison DE442Q (dérivé de l'éphéméride NASA JPL DE442, millésime 2024, couverture 1550-2650)

## Core Identity
Psychomantic est le moteur de calcul (IshtarEngine) qui donne aux agents IA des positions
astronomiques déterministes au lieu de positions hallucinées. Précision certifiée contre JPL Horizons :
**0,052″ en moyenne / 0,095″ au maximum** (63 points, campagne rejouable).
Couverture : 1550-2650. Latence moteur : ≈ 5 µs par position en régime chaud, ~15 µs à date
arbitraire ; 1-3 ms par thème complet via l'API. Moteur 100 % maison, licence commerciale.

## Documentation et points d'entrée
- Page API (présentation humaine) : https://psychomantic.com/api/
- Référence API publique (OpenAPI) : https://api.psychomantic.com/docs
- Spécification brute (OpenAPI 3.0, sous-ensemble public) : https://api.psychomantic.com/openapi.json
- Corpus complet pour les agents (toutes les sources en un fichier) : /llms-full.txt
- État du service (public, sans clé) : https://api.psychomantic.com/health
- Serveur MCP distant : https://api.psychomantic.com/mcp
- Paquets npm : SDK — https://www.npmjs.com/package/ishtarengine-sdk · MCP — https://www.npmjs.com/package/@ishtarengine/mcp

## Domaines couverts
- Astrologie occidentale : thème natal, transits, synastrie, révolution solaire, maisons, aspects
- Astrocartographie et relocation (lignes planétaires mondiales, GeoJSON)
- Astéroïdes : Chiron, Cérès, Pallas, Junon, Vesta
- Astrologie chinoise (BaZi, signe), numérologie
- Yi King (hexagramme de naissance, méthode He Lu Li Shu / HLLS)
- Matrice du Destin (22 arcanes, octogramme, chakras, cycles annuels, programme karmique)
- Heures miroirs / triples, phase de Lune
- Interprétation littéraire : le modèle de langage ne calcule rien, il traduit le JSON du moteur

## API (produit payant, app gratuite = vitrine)
- Base URL : https://api.psychomantic.com/v1
- Auth : en-tête `X-API-Key` uniquement (une clé ne se transmet jamais dans l'URL)
- Réponse : `{ "success": true, "data": {} }`, ou `{ "success": false, "error": { "code", "message" } }`
- Quotas : en-têtes `X-Quota-Daily-*` / `X-Quota-Monthly-*` sur chaque réponse authentifiée
- Entrée publique sans clé : `GET /health`
- Endpoints de calcul (clé requise, un appel = un résultat complet) :
  - POST /v1/astro/natal        thème natal complet (planètes, maisons, aspects)
  - POST /v1/astro/transits     transits sur un thème natal
  - POST /v1/astrocartography   carte astrocartographique (GeoJSON)
  - POST /v1/asteroids          positions des 5 astéroïdes majeurs
  - GET  /v1/astro/moon-phase   phase de Lune

## MCP (Model Context Protocol)
Serveur MCP distant : `POST https://api.psychomantic.com/mcp` (streamable HTTP, en-tête
`X-API-Key` ou `Authorization: Bearer`). Le descripteur public répond en `GET` sur la même URL,
et la liste des outils fait autorité via `tools/list`.
Serveur MCP local (stdio) : paquet `@ishtarengine/mcp`, **publié sur npm** —
`npx -y @ishtarengine/mcp` l'installe et le lance ; le serveur distant ci-dessus
reste la porte zéro-installation.
Compatible : ChatGPT, Claude, Gemini, Kimi, Mistral, Grok, DeepSeek, Llama et tout client MCP.

---

# 2. Référence API publique (OpenAPI 3.0)

```yaml
openapi: 3.0.3
info:
  title: IshtarEngine API — Spec publique
  description: >
    Sous-ensemble public de l'API IshtarEngine (moteur astronomique de
    Psychomantic). Le moteur s'appuie sur un kernel quantifié maison DE442Q,
    dérivé de l'éphéméride NASA JPL DE442 (millésime 2024, couverture
    1550-2650) : précision mesurée 0,052″ en moyenne / 0,095″ au maximum
    contre JPL Horizons (63 points). Seules les routes phares sont documentées
    ici ; la spécification complète reste privée. Authentification : clé API
    (X-API-Key, intégrations B2B) ou JWT (Authorization: Bearer, comptes B2C).
  version: 7.0.0
  contact:
    name: Kossmonot / IshtarEngine
    email: api@kossmonot.com
  license:
    name: Proprietary
    url: https://kossmonot.com/license

servers:
  - url: https://api.psychomantic.com
    description: Production
  - url: http://localhost:3002
    description: Développement local

tags:
  - name: Astro
    description: Calculs astrologiques et astronomiques
  - name: System
    description: Santé du service

security:
  - apiKey: []
  - bearerAuth: []

paths:
  /health:
    get:
      tags: [System]
      summary: Health check
      description: >
        Vérifie que l'API et le moteur d'éphémérides sont opérationnels.
        Route publique, aucune authentification requise.
      security: []
      responses:
        '200':
          description: Service opérationnel
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'

  /v1/astro/natal:
    post:
      tags: [Astro]
      summary: Calculer un thème natal
      description: >
        Calcule un thème astrologique natal complet : positions planétaires,
        maisons, aspects et points spéciaux.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BirthDataRequest'
      responses:
        '200':
          description: Thème natal calculé
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimit'
        '503':
          $ref: '#/components/responses/ServerBusy'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/astro/transits:
    post:
      tags: [Astro]
      summary: Calculer les transits
      description: Calcule les aspects entre les positions en transit et un thème natal.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransitsRequest'
      responses:
        '200':
          description: Transits calculés
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimit'
        '503':
          $ref: '#/components/responses/ServerBusy'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/astrocartography:
    post:
      tags: [Astro]
      summary: Carte astrocartographique
      description: >
        Calcule une carte astrocartographique : lignes planétaires, parans et
        points zénith. Réponse GeoJSON ; calcul lourd, sous garde de
        concurrence (503 SERVER_BUSY au-delà du plafond, voir Retry-After).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AstrocartographyRequest'
      responses:
        '200':
          description: Carte astrocartographique (GeoJSON)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimit'
        '503':
          $ref: '#/components/responses/ServerBusy'
        '500':
          $ref: '#/components/responses/InternalError'

  /v1/asteroids:
    post:
      tags: [Astro]
      summary: Calculer les positions des astéroïdes
      description: >
        Retourne Chiron, Cérès, Pallas, Juno et Vesta depuis des données
        JPL Horizons pré-générées en local (interpolation), calculées par le
        moteur maison (kernel NASA JPL DE442Q).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BirthDataRequest'
      responses:
        '200':
          description: Positions des astéroïdes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimit'
        '500':
          $ref: '#/components/responses/InternalError'

components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Clé API pour les intégrations serveur à serveur (B2B).
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT utilisateur délivré par /v1/auth (applications B2C).

  responses:
    BadRequest:
      description: Requête invalide
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Non autorisé — clé API manquante ou invalide
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimit:
      description: Trop de requêtes — quota journalier ou mensuel dépassé
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServerBusy:
      description: Serveur saturé — calculs lourds simultanés, réessayer (en-tête Retry-After)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: Erreur interne
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

  schemas:
    SuccessResponse:
      type: object
      required: [success]
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          description: Données de la réponse (format variable selon l'endpoint)

    ErrorResponse:
      type: object
      required: [success, error]
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
              example: VALIDATION_ERROR
            message:
              type: string
              example: latitude is required (number between -90 and 90)

    HealthResponse:
      type: object
      required: [success, data]
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            status:
              type: string
              example: healthy
            name:
              type: string
              example: IshtarEngine API
            version:
              type: string
              example: 7.0.0
            apiVersion:
              type: string
              example: v1
            timestamp:
              type: string
              format: date-time
            environment:
              type: string
              example: production
            engine:
              type: object
              properties:
                name:
                  type: string
                  example: IshtarEngine
                initialized:
                  type: boolean
                  example: true
                ephemerisSource:
                  type: string
                  example: NASA JPL DE442Q
                precision:
                  type: string
                  example: 0.052 arcsec mean vs JPL Horizons (63 pts)

    BirthDataRequest:
      type: object
      required: [date, time, latitude, longitude]
      properties:
        date:
          type: string
          format: date
          description: Date de naissance (YYYY-MM-DD)
        time:
          type: string
          description: Heure de naissance (HH:MM)
        latitude:
          type: number
          minimum: -90
          maximum: 90
          description: Latitude
        longitude:
          type: number
          minimum: -180
          maximum: 180
          description: Longitude
        timezone:
          type: string
          description: Fuseau horaire IANA
        houseSystem:
          type: string
          enum:
            - placidus
            - koch
            - campanus
            - alcabitius
            - morinus
            - regiomontanus
            - porphyry
            - topocentric
            - equal
            - equal_asc
            - equal_mc
            - whole_sign
            - whole-sign
            - vehlow
            - carter
            - krusinski
            - sunshine
            - axial-rotary
          default: placidus
        includeAsteroids:
          type: boolean
          default: false
        name:
          type: string
          description: Nom de la personne

    AstrocartographyRequest:
      description: Données de naissance et options de la carte astrocartographique.
      allOf:
        - $ref: '#/components/schemas/BirthDataRequest'
        - type: object
          properties:
            includeAsteroids:
              type: boolean
              default: false
              description: Inclure Chiron, Cérès, Pallas, Juno, Vesta dans la carte.
            includeAspectLoci:
              type: boolean
              default: false
              description: Ajouter les courbes d'aspect (lignes de lieu des aspects nataux).
            includePoints:
              type: boolean
              default: false
              description: Inclure Vertex et Part de Fortune (points fixes du thème natal).
            includeFixedStars:
              type: boolean
              default: false
              description: Inclure les étoiles fixes curées et le Centre Galactique.
            planets:
              type: array
              maxItems: 32
              items:
                type: string
                maxLength: 40
              description: >
                Noms des corps retenus pour la clé de cache (absente, la clé
                retombe sur « all »). La liste ne change pas le calcul : elle
                distingue seulement les entrées de cache.

    TransitsRequest:
      type: object
      required: [date, time, latitude, longitude]
      properties:
        date:
          type: string
          format: date
          description: Date de naissance
        time:
          type: string
          description: Heure de naissance
        latitude:
          type: number
          description: Latitude de naissance
        longitude:
          type: number
          description: Longitude de naissance
        timezone:
          type: string
          description: Fuseau horaire natal
        transitDate:
          type: string
          format: date
          description: Date du transit
        transitTime:
          type: string
          description: Heure du transit
        transitLatitude:
          type: number
          description: Latitude du transit
        transitLongitude:
          type: number
          description: Longitude du transit
        transitTimezone:
          type: string
          description: Fuseau horaire transit
        includeAsteroids:
          type: boolean
          default: false
```

---

# 3. Certification de précision

# IshtarEngine — Certification de Précision Astronomique

> **Document officiel** — État de la précision du moteur d'éphémérides IshtarEngine,
> validé contre le système JPL Horizons (NASA/Caltech), référence mondiale des éphémérides.
>
> **Date de certification : 2026-08-25** · **Commit : `80696a8`** · **Moteur : Rust/WASM + kernel quantifié DE442Q (NASA JPL DE442)**
> **Mise à jour 2026-09-10** : bascule du kernel `de440s.bsp` → `de442s.bsp` (données DE442 2024, couverture 1550-2650). Suites précision + fuzz vertes ; chiffres de référence remis à jour au §6 (0,052″ moyenne / 0,095″ max).

---

## 1. Résultat certifié

**Unités :** toutes les erreurs sont exprimées en **secondes d'arc** (symbole ″).
Rappel : 1° = 60 minutes d'arc (′) = 3 600 secondes d'arc (″). Une erreur de
0,110″ = 0,0018 minute d'arc = 0,000031°. À titre de comparaison, le diamètre
apparent de la Lune vue depuis la Terre est d'environ 1 800″ (0,5°) : notre
erreur moyenne est ~16 000 fois plus petite.

| Métrique | Valeur mesurée | Équivalent | Objectif initial | Statut |
|---|---|---|---|---|
| Erreur angulaire **moyenne** | **0,052″** | 0,0009′ | < 1,5″ | ✅ 28,8× sous objectif |
| Erreur angulaire **maximale** | **0,095″** (Saturne 2000) | 0,0016′ | < 1,5″ | ✅ |
| Erreur max **planètes** (Soleil→Neptune) | **0,095″** | 0,0016′ | — | ✅ sub-arcseconde |
| Erreur en longitude (Δλ) | < 0,1″ tous corps | < 0,002′ | — | ✅ |
| Couverture temporelle validée | 1990 – 2050 (continu) | — | — | ✅ fuzz 5 000 points |

*Valeurs mises à jour 2026-09-10 (post M4 : matrice bias-précession pmat06 exacte).
Grille 63 points : 0,052″ moyenne / 0,095″ max — voir §6.*

**Protocole de mesure :** 9 corps (Soleil, Lune, Mercure → Neptune) × 3 époques
(1990-06-15, 2000-01-01, 2026-07-13, 12:00 UTC), longitude/latitude écliptiques
apparentes géocentriques (équinoxe vrai de la date), comparées à JPL Horizons
`QUANTITIES=31` (ObsEcLon/ObsEcLat, centre `500@399`).

### Positionnement marché

| Solution | Technologie | Précision typique | En minutes d'arc |
|---|---|---|---|
| **IshtarEngine** | DE442Q (Chebyshev Rust/WASM) | **0,052″ moyenne** | **0,0009′** |
| RoxyAPI (réf. B2B) | — | ~1,5″ | ~0,025′ |
| astronomy-engine (open source) | VSOP87 | ~15″ sur les planètes lointaines | ~0,25′ |

## 2. Détail des mesures (toutes valeurs en **secondes d'arc** ″, écart angulaire total)

| Corps | 1990 | 2000 | 2026 |
|---|---|---|---|
| Soleil | 0,077 | 0,089 | 0,086 |
| Lune | 0,040 | 0,224 | 0,802 |
| Mercure | 0,078 | 0,082 | 0,025 |
| Vénus | 0,096 | 0,088 | 0,177 |
| Mars | 0,112 | 0,083 | 0,043 |
| Jupiter | 0,048 | 0,054 | 0,037 |
| Saturne | 0,066 | 0,027 | 0,091 |
| Uranus | 0,093 | 0,063 | 0,113 |
| Neptune | 0,095 | 0,095 | 0,088 |

*Grille historique (3 époques, avant M4) — les chiffres de référence de la campagne 63 points sont au §6.*

## 3. Pipeline de calcul (100 % maison, zéro dépendance externe)

| Composant | Implémentation |
|---|---|
| Éphémérides | NASA JPL **DE442** (kernel quantifié DE442Q), évaluation directe des polynômes de Chebyshev (Rust/WASM) |
| Temps | **Delta T** appliqué (`ut_to_tt`) — le kernel DE442Q est alimenté en TT |
| Vitesse Terre | **Dérivée analytique** Chebyshev (récurrence Tₙ/Uₙ), pas de différence finie |
| Light-time | Backdating au temps d'émission (1er ordre), **tous corps, Lune comprise** |
| Aberration | Vectorielle, vitesse **barycentrique** terrestre (EMB + Earth-relative) |
| Précession | IAU 2006 P03 |
| Nutation | **IAU 2000B** (remplace l'approximation Meeus 4-termes) |
| Obliquité | IAU 2006 P03 + nutation en obliquité |

## 4. Corrections majeures de la mission « Précision » (2026-08)

| Commit | Correction | Gain |
|---|---|---|
| `21f97a9` | Delta T : le JD entrant (UTC) alimentait le kernel comme du TT | 14,07″ → 11,20″ |
| `5cc88e5` | Dérivée analytique Chebyshev + sélection robuste du record | robustesse |
| `2fc2722` | Light-time (backdating) sur planètes intérieures et extérieures | 11,19″ → 5,14″ |
| `80696a8` | Nutation IAU 2000B · suppression du terme parasite δβ = Δε·cos(λ) · Lune : light-time + aberration | **5,14″ → 0,11″** |
| `229f341` | Delta T via tables IERS (P-001) : suppression de la rampe linéaire `69,2 + 0,5·(y−2024)` | **0,11″ → 0,079″ moyenne / 0,802″ → 0,119″ max** (moyenne sur la grille de test de l'époque — à ne jamais citer comme « mesure sur 5 000 points de fuzzing ») |

**Enseignement clé :** le résidu final était entièrement en **latitude écliptique**.
Le terme δβ = Δε·cos(λ) était physiquement faux : la nutation déplace l'équinoxe
*le long* de l'écliptique (δλ = Δψ) sans modifier le plan écliptique (δβ = 0).
L'écart résiduel vs astronomy-engine (~15″ sur Neptune) relève des limites de
leur modèle VSOP87, pas des nôtres — la validation JPL Horizons fait foi.

## 5. Reproductibilité

```bash
# Suite de tests (16 tests précision + fuzz 5 000 points)
cd IshtarEngine && npx vitest run tests/precision/

# Référence externe : JPL Horizons API
# https://ssd.jpl.nasa.gov/api/horizons.api?COMMAND='899'&CENTER='500@399'&QUANTITIES='31'...
```

Tests de non-régression : `tests/precision/astronomical-precision.test.ts` (16 tests),
`tests/precision/ephemeris-fuzz.test.ts` (5 000 dates pseudo-aléatoires 1990-2050,
finitude + normalisation + continuité < 4°/6h).

## 6. Protocole renforcé — 63 points, kernel DE442s (2026-09-10)

Grille étendue : **7 époques** (1990, 2000, 2010, 2020, 2026, 2035, 2045) × **9 corps** = 63 points,
fetch live JPL Horizons (QUANTITIES=31, CENTER=500@399, cache `bench/horizons-cache.json`),
même calcul d'erreur angulaire que le test officiel. Outil : `bench/certify-jpl.mjs` (relançable).

| Métrique | Grille historique (3 époques) | Grille étendue (7 époques) |
|---|---|---|
| Erreur moyenne | 0,057″ | **0,052″** |
| Erreur max | 0,099″ (Uranus 2026) | **0,095″** (Saturne 2000) |

- **Post M4 (2026-09-10)** : matrice bias-précession combinée `pmat06` (IAU 2006,
  angles Fukushima-Williams, validée contre SOFA/ERFA à 1e-12). L'ancienne
  composition « frame bias + précession ζ/θ/z » divergeait du standard de ~0,1″.
- **Trajectoire de la campagne** : 0,097″ (début) → 0,092″ (M2/M3) → 0,066″ (M3b)
  → 0,065″ (calibration ΔT) → **0,052″** (M4). Max : 0,289″ → 0,095″.
- **Résidu restant (~0,05″)** : seconds ordres de la nutation (λ+=Δψ), arrondis
  de Horizons, écart inter-kernel DE442s vs DE441 — niveau de bruit de référence.
- La référence Horizons est en DE441, notre moteur en DE442s : l'écart inter-kernel vit à
  la mas, négligeable à ce niveau (documenté dans le protocole).

**Règle de mesure (R-001)** : tout nouveau chiffre déclaré doit provenir de ce protocole
(ou d'une grille plus dense), jamais d'un test isolé.

---

*Document généré le 2026-08-25 — mis à jour le 2026-09-10 (kernel DE442s, protocole 63 points). IshtarEngine, moteur d'éphémérides Psychomantic.*

---

# 4. SDK TypeScript (ishtarengine-sdk)

# IshtarEngine SDK

[![Certified vs NASA JPL Horizons](https://ishtarengine.com/badges/jpl-certified.svg)](https://ishtarengine.com/#precision)

Client TypeScript typé pour l'API IshtarEngine.

## Installation

```bash
npm install ishtarengine-sdk
```

## Usage

```typescript
import { IshtarEngineClient } from 'ishtarengine-sdk';

const client = new IshtarEngineClient({
  baseUrl: 'https://api.psychomantic.com',
  apiKey: 'ish_...',      // mode B2B
  // ou
  accessToken: 'jwt...',  // mode B2C
});

// Health check
const health = await client.health();

// Thème natal
const natal = await client.natal({
  date: '1990-06-15',
  time: '14:30:00',
  latitude: 48.8566,
  longitude: 2.3522,
  timezone: 'Europe/Paris',
  includeAsteroids: true,
});

// Auth B2C
const session = await client.register({
  email: 'user@example.com',
  password: 'Str0ngP@ss!',
  name: 'Jane Doe',
});

// Profils
const profiles = await client.listProfiles();
```

## Scripts

- `npm run generate` — régénère `src/openapi.ts` depuis `IshtarEngine/openapi.yaml`
- `npm run typecheck` — vérifie les types
- `npm run build` — compile le SDK
- `npm run validate-openapi` — valide la spécification OpenAPI

## Architecture

- `src/openapi.ts` : types générés automatiquement par `openapi-typescript`
- `src/client.ts` : wrapper haut niveau (`IshtarEngineClient`) basé sur `openapi-fetch`
- `dist/` : sortie de compilation

---

# 5. Serveur MCP (@ishtarengine/mcp)

# @ishtarengine/mcp

[![Certified vs NASA JPL Horizons](https://ishtarengine.com/badges/jpl-certified.svg)](https://ishtarengine.com/#precision)

Serveur **MCP (Model Context Protocol)** d'IshtarEngine — expose les calculs astrologiques et astronomiques (moteur maison Rust/WASM, kernel quantifié **DE442Q** dérivé de l'éphéméride **NASA JPL DE442**, millésime 2024, précision mesurée **0,052″ moyenne / 0,095″ max** contre JPL Horizons) à tout LLM compatible MCP : Claude, ChatGPT, Gemini, Kimi, Mistral / Le Chat, Grok, DeepSeek, Cursor…

## Outils exposés

| Outil | Description |
|---|---|
| `calculer_theme_natal` | Thème natal complet : 10 planètes (signe, degré, maison), maisons, aspects, ascendant |
| `calculer_transits` | Aspects entre les planètes en transit et le thème natal (orbe, impact) |
| `calculer_astrocartographie` | Résumé des lignes planétaires mondiales ACG (MC/IC/ASC/DSC) pour la relocation |
| `calculer_asteroides` | Chiron, Cérès, Pallas, Juno, Vesta |
| `phase_lune` | Phase lunaire (nom, illumination, âge) pour une date — calcul réel (kernel DE442Q) |
| `consulter_usage_api` | Quota et statistiques d'usage de la clé API |

## Prérequis

- Node.js >= 20
- Une clé API IshtarEngine (en-tête `X-API-Key`) pour les outils de calcul ; l'état du service est public : https://api.psychomantic.com/health

## Installation (npm)

Le paquet est publié sur npm : `npx` télécharge et lance le serveur.

```json
{
  "mcpServers": {
    "ishtarengine": {
      "command": "npx",
      "args": ["-y", "@ishtarengine/mcp"],
      "env": {
        "ISHTAR_API_URL": "https://api.psychomantic.com/v1",
        "ISHTAR_API_KEY": "ish_..."
      }
    }
  }
}
```

Cette forme (commande `npx`) vaut pour tous les clients MCP stdio : Claude Desktop, Cursor,
VS Code, Windsurf, Kimi Code CLI, Gemini CLI, Mistral / Le Chat (via relais HTTP) et tout
client compatible. Les sections ci-dessous détaillent chaque client avec le lancement depuis
les sources locales.

## Développement local (depuis les sources)

Prérequis : le backend local tourne (`cd IshtarEngine && npm run dev` → port 3002).

```bash
cd packages/mcp-ishtarengine
npm install
npm run build        # compile src/ → dist/ (tsc)
node dist/index.js   # démarre le serveur MCP (stdio) — normalement lancé par le client
```

## Configuration

Deux variables d'environnement :

| Variable | Défaut | Rôle |
|---|---|---|
| `ISHTAR_API_URL` | `http://localhost:3002/v1` | URL de base de l'API IshtarEngine |
| `ISHTAR_API_KEY` | `dev` | Clé API (header `X-API-Key`) |

Dans les exemples ci-dessous, remplacez `/chemin/absolu/ecosystem` par le chemin réel du repo.

### Claude Desktop

Fichier `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) ou `%APPDATA%\Claude\claude_desktop_config.json` (Windows) :

```json
{
  "mcpServers": {
    "ishtarengine": {
      "command": "node",
      "args": ["/chemin/absolu/ecosystem/packages/mcp-ishtarengine/dist/index.js"],
      "env": {
        "ISHTAR_API_URL": "http://localhost:3002/v1",
        "ISHTAR_API_KEY": "dev"
      }
    }
  }
}
```

Redémarrer Claude Desktop après modification.

### ChatGPT

ChatGPT (connecteurs MCP, plan Pro/Team/Enterprise) n'accepte que des serveurs MCP **accessibles via HTTP(S)**. Ce serveur étant en stdio (local), deux options :

1. Le faire tourner derrière un relais stdio→HTTP (ex. `mcp-proxy`, `supergateway`) exposé sur une URL publique, puis déclarer cette URL dans *Paramètres → Connecteurs*.
2. Utiliser directement l'API HTTP d'IshtarEngine comme « Action » (OpenAPI) dans un GPT personnalisé — le backend expose ses schémas Fastify.

Avec un relais, la commande locale à relayer reste :

```json
{
  "command": "node",
  "args": ["/chemin/absolu/ecosystem/packages/mcp-ishtarengine/dist/index.js"],
  "env": { "ISHTAR_API_KEY": "dev" }
}
```

### Gemini (Gemini CLI)

Fichier `~/.gemini/settings.json` :

```json
{
  "mcpServers": {
    "ishtarengine": {
      "command": "node",
      "args": ["/chemin/absolu/ecosystem/packages/mcp-ishtarengine/dist/index.js"],
      "env": {
        "ISHTAR_API_URL": "http://localhost:3002/v1",
        "ISHTAR_API_KEY": "dev"
      }
    }
  }
}
```

### Kimi (Kimi Code CLI)

Ajouter dans la configuration MCP de Kimi Code (`~/.kimi/config.toml` ou via la commande dédiée) un serveur stdio :

```json
{
  "mcpServers": {
    "ishtarengine": {
      "command": "node",
      "args": ["/chemin/absolu/ecosystem/packages/mcp-ishtarengine/dist/index.js"],
      "env": {
        "ISHTAR_API_URL": "http://localhost:3002/v1",
        "ISHTAR_API_KEY": "dev"
      }
    }
  }
}
```

### Mistral / Le Chat

Le Chat supporte les connecteurs MCP (remote MCP, URL HTTP(S)). Comme pour ChatGPT, exposez ce serveur stdio derrière un relais HTTP puis déclarez l'URL du relais dans les connecteurs. La configuration locale à relayer :

```json
{
  "command": "node",
  "args": ["/chemin/absolu/ecosystem/packages/mcp-ishtarengine/dist/index.js"],
  "env": { "ISHTAR_API_KEY": "dev" }
}
```

### Tout client MCP stdio (Cursor, Windsurf, Grok, DeepSeek…)

Bloc générique à adapter selon le client :

```json
{
  "mcpServers": {
    "ishtarengine": {
      "command": "node",
      "args": ["/chemin/absolu/ecosystem/packages/mcp-ishtarengine/dist/index.js"],
      "env": {
        "ISHTAR_API_URL": "http://localhost:3002/v1",
        "ISHTAR_API_KEY": "dev"
      }
    }
  }
}
```

> Raccourci : une fois le paquet publié sur npm, la commande standard devient `"command": "npx", "args": ["-y", "@ishtarengine/mcp"]` (voir « Installation (npm) » ci-dessus). En attendant la publication, utilisez le chemin absolu du clone.

## Dépannage

- **`API IshtarEngine inaccessible`** → le backend local ne tourne pas : `cd IshtarEngine && npm run dev` (port 3002).
- **`Authentification refusée (HTTP 401)`** → mauvaise `ISHTAR_API_KEY` (`dev` en développement).
- **`Quota API dépassé (HTTP 429)`** → appelez l'outil `consulter_usage_api` pour voir le quota restant.
- Les logs du serveur MCP vont sur **stderr** (stdout est réservé au protocole JSON-RPC).

## Limites connues

- Transport **stdio uniquement** : les clients qui n'acceptent que du MCP remote (ChatGPT, Le Chat web) nécessitent un relais stdio→HTTP.
- `calculer_astrocartographie` renvoie un **résumé** (la carte GeoJSON complète serait trop volumineuse pour un contexte LLM) ; le GeoJSON reste accessible via `POST /v1/astrocartography`.
- La phase lunaire utilise `/v1/astro/moon-phase` (calcul réel, kernel DE442Q) ; la route `/v1/temporal/moon-phase` du backend est un stub et n'est pas utilisée.

---

# 6. Exemples d'appel

## cURL · thème natal complet

```bash
curl -X POST https://api.psychomantic.com/v1/astro/natal \
  -H "X-API-Key: ish_..." \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-06-15","time":"14:30","latitude":48.8566,"longitude":2.3522,"timezone":"Europe/Paris"}'
```

## TypeScript · SDK officiel (ishtarengine-sdk)

```ts
import { IshtarEngineClient } from 'ishtarengine-sdk';

const client = new IshtarEngineClient({
  baseUrl: 'https://api.psychomantic.com',
  apiKey: process.env.ISHTAR_API_KEY,
});

const natal = await client.natal({
  date: '1990-06-15',
  time: '14:30:00',
  latitude: 48.8566,
  longitude: 2.3522,
  timezone: 'Europe/Paris',
});
```

## MCP · configuration cliente (stdio, tous clients compatibles)

```json
{
  "mcpServers": {
    "ishtarengine": {
      "command": "npx",
      "args": ["-y", "@ishtarengine/mcp"],
      "env": {
        "ISHTAR_API_URL": "https://api.psychomantic.com/v1",
        "ISHTAR_API_KEY": "ish_..."
      }
    }
  }
}
```

## MCP · serveur distant (streamable HTTP)

`POST https://api.psychomantic.com/mcp` · l'en-tête `X-API-Key` (ou `Authorization: Bearer`)
est requis pour `tools/call` uniquement. Un `GET` sur la même URL sert le descripteur public ;
la liste des outils fait autorité via `tools/list`.