README.md

# Planets360: AI Vedic Astrology — MCP server (Node.js / TypeScript)

Planets360: AI Vedic Astrology helps users explore Kundli, Moon signs, Panchang, Nakshatra, Panchapakshi, planetary transits, Dasa/Bhukti, Chandrashtama, and compatibility. This integration follows the uploaded `openapi.yaml` for API paths, required input fields, and documented enum values. It calls the production API using POST JSON bodies, which the specification documents for each operation.

## Included tools

- `planets360_panchang_kundli`
- `planets360_planet_transit_range`
- `planets360_dasa_bhukti`
- `planets360_chandrashtama_days`
- `planets360_panchapakshi_table`
- `planets360_find_bird_by_birth_info`
- `planets360_find_bird_by_nakshatra`
- `planets360_find_bird_by_name`
- `planets360_love_compatibility_birth_dates`
- `planets360_love_compatibility_moon_signs`
- `planets360_love_compatibility_names`
- `planets360_moon_sign_prediction`
- `planets360_read_public_article` (allowlisted public website content, not an API endpoint)

## Requirements

- Node.js 20 or newer recommended (uses built-in `fetch` and `AbortSignal.timeout`).
- A valid Planets360 API token configured on the machine running the server.
- Network access from the MCP server to `https://ephemeris.gopim.dev` and `https://planets360.in`.

## Run locally

1. Install Node.js.
2. In this directory, run `npm install`.
3. Copy `.env.example` to `.env`, then set `PLANETS360_API_TOKEN` to your secret. `.env` is ignored by Git. The current source reads environment variables; it does not automatically load `.env`, so export the variables in your shell or configure them in your MCP host.
4. Build: `npm run build`.
5. Start: `PLANETS360_API_TOKEN='your-secret' npm start` (PowerShell: `$env:PLANETS360_API_TOKEN='your-secret'; npm start`).
6. Configure your MCP client to launch `node dist/index.js` with `PLANETS360_API_TOKEN` in its process environment.

The token is sent only in the `Authorization: Bearer ...` header and is never an MCP tool argument. If your API server requires `X-API-Key` instead, confirm this with the API owner before changing the header; the OpenAPI security section lists both schemes and describes them as the same secret.

## Security and current limitations

- Never commit `.env`, tokens, or production credentials.
- Public article retrieval only accepts HTTPS URLs under `planets360.in` and does not follow redirects.
- API response payloads are returned as received. Several response schemas in the uploaded specification are intentionally broad, so this server does not assume undocumented fields.
- This package has not been deployed and has not been tested against the production API. Run build and API smoke tests in an environment with npm dependencies, network access, and an authorized token before production use.
- The portable `mcp.json` describes a local stdio process. A hosted ChatGPT connection requires deploying the MCP server to an HTTPS-accessible MCP endpoint and configuring remote transport/authentication; the local package alone does not create that hosted endpoint.

## Hosted mode (Streamable HTTP) for OpenAI directory submission

The OpenAI plugin submission portal recommends MCP servers with a URL.
The server supports the MCP Streamable HTTP transport:

```
MCP_TRANSPORT=http MCP_HTTP_HOST=0.0.0.0 MCP_HTTP_PORT=8787 \
PLANETS360_API_TOKEN='...' node dist/index.js
```

- MCP endpoint: `POST https://<your-host>/mcp` (stateless; each request gets a fresh server instance).
- Health check: `GET https://<your-host>/healthz`.
- Deploy behind TLS (nginx, Caddy, Cloudflare Tunnel, etc.). For example, on the same host as your existing API, proxy `https://<domain>/mcp` to `http://127.0.0.1:8787/mcp`.

### Submission package composition (important)

Per the plugin guidelines and submission docs, remote MCP servers are submitted
through **With MCP** using the hosted HTTPS URL — they are **not** declared as a
command/stdio server in the ZIP. A root `mcp.json` with `"type": "stdio"` in the
uploaded package triggers the "Command MCP Server detected" finding, because
command-line MCP submissions are limited to approved desktop-only partners.

Therefore the submission ZIP contains only metadata, skills, and assets:

```
plugin.json  package.json  PRIVACY.md
skills/planets360-astrology/SKILL.md
skills/planets360-get-started/SKILL.md
assets/logo.png  assets/logo.svg
```

The repository keeps `mcp.json` and `dist/` for local/desktop testing only;
exclude them from the submission ZIP. The MCP server is registered in the
portal via **With MCP** with your public URL — the ZIP carries no MCP config.

Submission steps for the hosted path:

1. Deploy the Streamable HTTP server (command above) behind a public HTTPS host.
2. Domain verification: host the exact verification token at `/.well-known/openai-apps-challenge` on the MCP host (or an allowed parent host), then run **Verify Domain** in the portal.
3. Create the submission with **With MCP**, entering the public `https://<host>/mcp` URL, and upload the ZIP above for metadata and skills.
4. Tool annotations: every tool declares explicit `readOnlyHint`, `openWorldHint`, and `destructiveHint` values with justifications (this server only performs read operations against the Planets360 API and website).
5. Provide `review.demo_recording_url`, five positive and three negative test cases, and release notes (already scaffolded in `plugin.json`).

If you keep the stdio configuration instead, local MCP submissions require an approved partner allowlist — contact your OpenAI representative and submit as desktop-only per the submission docs.

## Privacy

- See [PRIVACY.md](./PRIVACY.md) for the plugin's data-handling disclosure, and the public [Privacy Policy](https://planets360.in/privacy-policy).
- Data minimization: tool schemas request only fields required for each calculation; birth details are forwarded solely to the Planets360 calculation API for the requested report.
- No chat-log access, no persistence, no account requirement.