@morphemeris/mcp 0.1.0 → 0.1.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 (2) hide show
  1. package/README.md +98 -2
  2. package/package.json +5 -5
package/README.md CHANGED
@@ -2,10 +2,40 @@
2
2
 
3
3
  MCP (Model Context Protocol) server for the [Morphemeris](https://morphemeris.com) astronomical ephemeris API. Gives AI coding agents direct access to planetary positions, house cusps, fixed stars, and other astronomical calculations.
4
4
 
5
+ ## Prerequisites
6
+
7
+ You'll need a Morphemeris API key. Sign up at [morphemeris.com](https://morphemeris.com) and create a key at [morphemeris.com/dashboard/keys](https://morphemeris.com/dashboard/keys). The free tier includes 500 requests/month.
8
+
5
9
  ## Installation
6
10
 
7
11
  ### Claude Code
8
12
 
13
+ [Claude Code MCP docs](https://code.claude.com/docs/en/mcp)
14
+
15
+ From your terminal (not inside Claude Code):
16
+
17
+ ```bash
18
+ claude mcp add morphemeris \
19
+ -e MORPHEMERIS_API_KEY=morphemeris_live_... \
20
+ -- npx -y @morphemeris/mcp
21
+ ```
22
+
23
+ You can control where the server is available with the `-s` (scope) flag:
24
+
25
+ - **`local`** (default) — only you, only in the current project directory
26
+ - **`project`** — saved to `.mcp.json` in the project root, shared with your team via version control (requires approval on first use)
27
+ - **`user`** — available across all your projects on this machine
28
+
29
+ For example, to make Morphemeris available everywhere: `claude mcp add morphemeris -s user ...`
30
+
31
+ After adding, start a new Claude Code conversation and run `/mcp` to verify the server appears. If it shows as disabled, select it and enable it. You may need to enable it a second time on first setup — this is a known quirk with newly added MCP servers.
32
+
33
+ ### Cursor
34
+
35
+ [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol)
36
+
37
+ Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
38
+
9
39
  ```json
10
40
  {
11
41
  "mcpServers": {
@@ -20,9 +50,69 @@ MCP (Model Context Protocol) server for the [Morphemeris](https://morphemeris.co
20
50
  }
21
51
  ```
22
52
 
23
- ### Cursor
53
+ ### VS Code (GitHub Copilot)
24
54
 
25
- Add to your `.cursor/mcp.json`:
55
+ [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)
56
+
57
+ Add to `.vscode/mcp.json` in your project root, or use the command palette: `MCP: Open User Configuration` for global setup.
58
+
59
+ ```json
60
+ {
61
+ "servers": {
62
+ "morphemeris": {
63
+ "type": "stdio",
64
+ "command": "npx",
65
+ "args": ["-y", "@morphemeris/mcp"],
66
+ "env": {
67
+ "MORPHEMERIS_API_KEY": "morphemeris_live_..."
68
+ }
69
+ }
70
+ }
71
+ }
72
+ ```
73
+
74
+ MCP tools are only available in Copilot's **Agent mode** — select "Agent" from the mode dropdown in Copilot Chat.
75
+
76
+ ### Windsurf
77
+
78
+ [Windsurf MCP docs](https://docs.windsurf.com/windsurf/cascade/mcp)
79
+
80
+ Add to `~/.codeium/windsurf/mcp_config.json`:
81
+
82
+ ```json
83
+ {
84
+ "mcpServers": {
85
+ "morphemeris": {
86
+ "command": "npx",
87
+ "args": ["-y", "@morphemeris/mcp"],
88
+ "env": {
89
+ "MORPHEMERIS_API_KEY": "morphemeris_live_..."
90
+ }
91
+ }
92
+ }
93
+ }
94
+ ```
95
+
96
+ ### OpenAI Codex CLI
97
+
98
+ [Codex MCP docs](https://github.com/openai/codex/blob/main/docs/mcp.md)
99
+
100
+ Add to `~/.codex/config.toml` (global) or `.codex/config.toml` (project):
101
+
102
+ ```toml
103
+ [mcp_servers.morphemeris]
104
+ command = "npx"
105
+ args = ["-y", "@morphemeris/mcp"]
106
+
107
+ [mcp_servers.morphemeris.env]
108
+ MORPHEMERIS_API_KEY = "morphemeris_live_..."
109
+ ```
110
+
111
+ ### Gemini CLI
112
+
113
+ [Gemini CLI MCP docs](https://googlegemini.com/app/docs/gemini-cli/customize/mcp-servers)
114
+
115
+ Add to `~/.gemini/settings.json` (global) or `.gemini/settings.json` (project):
26
116
 
27
117
  ```json
28
118
  {
@@ -67,6 +157,12 @@ Ask your AI agent:
67
157
  - "Show me the fixed star Aldebaran's position today"
68
158
  - "What house system options are available?"
69
159
 
160
+ ## A note about time zones
161
+
162
+ The Morphemeris API expects all datetimes in **UTC**. When you ask your agent about a specific local time (e.g., "7:30 PM Eastern"), the agent will convert it to UTC before calling the API. This conversion is usually correct, but be aware of edge cases involving historical daylight saving time changes.
163
+
164
+ For example, in the United States, the Emergency Daylight Saving Time Energy Conservation Act of 1973 moved the start of DST to January 6, 1974 due to the oil crisis — so February 1974 was EDT (UTC-4), not the EST (UTC-5) that most models assume. If precision matters, provide the UTC time directly or verify the agent's conversion, especially for dates before 2000 or in regions with unusual DST history.
165
+
70
166
  ## Pricing
71
167
 
72
168
  Morphemeris offers a free tier of 500 requests/month. Additional requests are $0.01 each via prepaid credits. Get your API key at [morphemeris.com](https://morphemeris.com).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@morphemeris/mcp",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "MCP server for the Morphemeris astronomical ephemeris API",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -13,13 +13,13 @@
13
13
  ],
14
14
  "dependencies": {
15
15
  "@modelcontextprotocol/sdk": "^1.12.1",
16
- "zod": "^3.25.23"
16
+ "zod": "^4.3.6"
17
17
  },
18
18
  "devDependencies": {
19
- "@types/node": "^22.15.17",
19
+ "@types/node": "^25.5.0",
20
20
  "tsup": "^8.5.0",
21
- "typescript": "^5.8.3",
22
- "vitest": "^3.2.1"
21
+ "typescript": "^6.0.2",
22
+ "vitest": "^4.1.2"
23
23
  },
24
24
  "engines": {
25
25
  "node": ">=18"