@openephemeris/mcp-server 3.0.0

package/README.md

@@ -0,0 +1,163 @@
+# OpenEphemeris MCP Server
+
+Model Context Protocol server for OpenEphemeris. This package exposes typed astrology tools and an allowlist-gated generic proxy (`dev.call`) for MCP-compatible clients.
+
+## Quick Start
+
+### One-click install (Cursor)
+
+<!-- GENERATED:CURSOR_INSTALL:BEGIN -->
+[![Install in Cursor](https://img.shields.io/badge/Install%20in-Cursor-1f6feb)](cursor://anysphere.cursor-deeplink/mcp/install?name=openephemeris&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBvcGVuZXBoZW1lcmlzL21jcC1zZXJ2ZXIiXSwiZW52Ijp7IkFTVFJPTUNQX1BST0ZJTEUiOiJkZXYiLCJBU1RST01DUF9CQUNLRU5EX1VSTCI6Imh0dHBzOi8vYXBpLm9wZW5lcGhlbWVyaXMuY29tIiwiQVNUUk9NQ1BfQVBJX0tFWSI6IllPVVJfQVBJX0tFWV9IRVJFIn19)
+
+> Replace `YOUR_API_KEY_HERE` in Cursor MCP settings with your API key from https://openephemeris.com/dashboard.
+
+Cursor deeplink payload:
+```json
+{
+  "command": "npx",
+  "args": [
+    "-y",
+    "@openephemeris/mcp-server"
+  ],
+  "env": {
+    "ASTROMCP_PROFILE": "dev",
+    "ASTROMCP_BACKEND_URL": "https://api.openephemeris.com",
+    "ASTROMCP_API_KEY": "YOUR_API_KEY_HERE"
+  }
+}
+```
+<!-- GENERATED:CURSOR_INSTALL:END -->
+
+### Manual install (stdio MCP clients)
+
+```json
+{
+  "mcpServers": {
+    "openephemeris": {
+      "command": "npx",
+      "args": ["-y", "@openephemeris/mcp-server"],
+      "env": {
+        "ASTROMCP_PROFILE": "dev",
+        "ASTROMCP_BACKEND_URL": "https://api.openephemeris.com",
+        "ASTROMCP_API_KEY": "YOUR_API_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+### Platform guide
+
+| Client | Install mode | Config location |
+|---|---|---|
+| Cursor | One-click deeplink or manual | `~/.cursor/mcp.json` |
+| Claude Desktop (macOS) | Manual | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Claude Desktop (Windows) | Manual | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Windsurf | Manual | `~/.codeium/windsurf/mcp_config.json` (or legacy `~/.codeium/mcp_config.json`) |
+
+### Remote-only clients (ChatGPT Developer Mode, Antigravity, etc.)
+
+This package runs as a local stdio MCP server. Remote-only clients require a hosted MCP endpoint (Streamable HTTP/SSE), so you must run this server behind an MCP bridge/proxy and expose it over HTTPS before adding it in those clients.
+
+## What You Can Ask
+
+- "Calculate a natal chart for 1990-04-15 14:30 in Chicago."
+- "Find transit events for the next 6 months."
+- "Get moon phase and void-of-course status right now."
+- "Find an electional window for signing a contract next month."
+- "Generate Human Design chart data from birth details."
+- "Call `/predictive/transits/search` with `format=llm`."
+
+## Tooling Model
+
+- Typed tools are preferred for common workflows (natal, transits, moon phase, eclipse, synastry, relocation, electional, Human Design).
+- Generic tools: `dev.list_allowed` returns all currently allowlisted operations, and `dev.call` invokes any allowlisted operation by `method + path`.
+- Security model: default-deny with explicit allowlist in `config/dev-allowlist.json`.
+- Deny prefixes block sensitive route families (`/auth`, `/billing`, `/admin`, etc.).
+
+### `dev.call` input
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `method` | `GET\|POST\|PUT\|PATCH\|DELETE` | Yes | HTTP method |
+| `path` | `string` | Yes | Absolute API path, e.g. `/ephemeris/natal-chart` |
+| `query` | `object` | No | Query parameters |
+| `body` | `object` | No | JSON body for non-GET requests |
+| `preset` | `full\|simple` | No | Convenience mapping to `query.preset` |
+| `format` | `json\|llm\|llm_v2` | No | Convenience mapping to `query.format` (`llm_v2` normalizes to `llm`) |
+| `output_mode` | `full\|simple\|llm\|llm_v2` | No | Legacy compatibility field |
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `ASTROMCP_API_KEY` | Yes (unless service key/JWT used) | API key for OpenEphemeris |
+| `ASTROMCP_BACKEND_URL` | No | Defaults to `https://api.openephemeris.com` |
+| `ASTROMCP_PROFILE` | No | `dev` by default |
+| `ASTROMCP_SERVICE_KEY` | No | Internal service auth |
+| `ASTROMCP_JWT` | No | Bearer token auth |
+| `ASTROMCP_DEV_ALLOWLIST_PATH` | No | Override allowlist file path |
+| `MCP_USER_ID` | No | Per-instance user identifier |
+
+Legacy aliases (`MERIDIAN_*`) remain supported.
+
+## Development
+
+```bash
+npm install
+npm run dev
+npm run typecheck
+npm test
+npm run regen:dev-allowlist
+npm run check:dev-allowlist
+npm run sync:readme
+npm run check:readme
+npm run verify:release
+```
+
+`npm run verify:release` is the release gate. It checks:
+- allowlist freshness against OpenAPI
+- schema pack freshness
+- README synchronization
+- type safety + tests
+- publish tarball contents (`npm pack --dry-run --json`)
+
+## Architecture
+
+```text
+MCP Client (Cursor / Claude / Windsurf / other stdio clients)
+    | stdio JSON-RPC
+    v
+openephemeris-mcp (Node.js)
+    | typed tools + dev.call/dev.list_allowed
+    | auth chain: Service Key > API Key > JWT
+    v
+OpenEphemeris API
+```
+
+<!-- GENERATED:RUNTIME_SNAPSHOT:BEGIN -->
+## Runtime Snapshot (Generated)
+
+Generated by `npm run sync:readme` from `config/dev-allowlist.json` and the live tool registry.
+
+- Allowlisted operations: **68**
+- Methods: `GET=22`, `POST=46`, `PUT=0`, `PATCH=0`, `DELETE=0`
+- Registered tools (`ASTROMCP_PROFILE=dev`): **10**
+- Typed tools: `ephemeris.electional`, `ephemeris.moon_phase`, `ephemeris.natal_chart`, `ephemeris.next_eclipse`, `ephemeris.relocation`, `ephemeris.synastry`, `ephemeris.transits`, `human_design.chart`
+- Generic tools: `dev.call`, `dev.list_allowed`
+
+### Allowlist Families
+
+| Family | Operations | Example |
+|---|---:|---|
+| `acg` | 5 | `POST /acg/ccg`, `GET /acg/health` |
+| `catalogs` | 3 | `GET /catalogs/bodies`, `GET /catalogs/fixed-stars` |
+| `comparative` | 6 | `POST /comparative/composite`, `POST /comparative/composite/midpoint` |
+| `electional` | 5 | `GET /electional/aspect-search`, `GET /electional/find-window` |
+| `ephemeris` | 30 | `POST /ephemeris/angles-points`, `POST /ephemeris/aspect-check` |
+| `health` | 1 | `GET /health` |
+| `human-design` | 6 | `POST /human-design/bodygraph`, `POST /human-design/chart` |
+| `location` | 2 | `GET /location/autocomplete`, `GET /location/reverse` |
+| `predictive` | 8 | `POST /predictive/events`, `POST /predictive/returns` |
+| `timezone` | 2 | `POST /timezone/lookup`, `POST /timezone/offset` |
+<!-- GENERATED:RUNTIME_SNAPSHOT:END -->