@openephemeris/mcp-server 3.0.0 → 3.1.0

package/README.md

@@ -55,10 +55,31 @@ Cursor deeplink payload:
 | Claude Desktop (Windows) | Manual | `%APPDATA%\Claude\claude_desktop_config.json` |
 | Windsurf | Manual | `~/.codeium/windsurf/mcp_config.json` (or legacy `~/.codeium/mcp_config.json`) |
 
+### Client install walkthroughs
+
+1. Cursor
+   - Click the "Install in Cursor" button above, then replace `YOUR_API_KEY_HERE` in Cursor MCP settings.
+   - If you prefer manual setup, paste the `mcpServers.openephemeris` block from "Manual install" into `~/.cursor/mcp.json`.
+2. Claude Desktop (macOS/Windows)
+   - Open the platform config file from the table above.
+   - Add the same `mcpServers.openephemeris` block from "Manual install".
+   - Restart Claude Desktop.
+3. Windsurf
+   - Open `~/.codeium/windsurf/mcp_config.json` (or the legacy `~/.codeium/mcp_config.json` path).
+   - Add the `mcpServers.openephemeris` block from "Manual install".
+   - Restart Windsurf.
+
 ### 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.
 
+### Auth and upgrade behavior in MCP clients
+
+- Missing/invalid credentials (`401`): tool call fails with a message that points users to sign up/sign in at `https://openephemeris.com/login?signup=true&redirect=%2Fdashboard%3Ftab%3Daccount`, then create/manage keys in `https://openephemeris.com/dashboard?tab=account`.
+- Tier-gated endpoint (`403`): tool call returns an upgrade-required message with `https://openephemeris.com/pay` and dashboard billing/key management link.
+- Monthly quota exhausted (`402`): tool call returns usage quota guidance with both dashboard (`/dashboard?tab=account`) and upgrade (`/pay`) links.
+- Burst/rate limit (`429`): tool call returns retry guidance and links to dashboard usage monitoring.
+
 ## What You Can Ask
 
 - "Calculate a natal chart for 1990-04-15 14:30 in Chicago."
@@ -140,8 +161,8 @@ OpenEphemeris API
 
 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`
+- Allowlisted operations: **67**
+- Methods: `GET=22`, `POST=45`, `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`
@@ -150,14 +171,15 @@ Generated by `npm run sync:readme` from `config/dev-allowlist.json` and the live
 
 | Family | Operations | Example |
 |---|---:|---|
-| `acg` | 5 | `POST /acg/ccg`, `GET /acg/health` |
+| `acg` | 4 | `POST /acg/ccg`, `GET /acg/health` |
 | `catalogs` | 3 | `GET /catalogs/bodies`, `GET /catalogs/fixed-stars` |
-| `comparative` | 6 | `POST /comparative/composite`, `POST /comparative/composite/midpoint` |
+| `comparative` | 5 | `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` |
+| `ephemeris` | 29 | `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` |
+| `visualization` | 2 | `POST /visualization/bi-wheel`, `POST /visualization/chart-wheel` |
 <!-- GENERATED:RUNTIME_SNAPSHOT:END -->