MCP Moon Phase Server

A simple MCP (Model Context Protocol) server that calculates moon phases based on date and time.

About

This code (and most of this README) was created with the Crush AI coding app, Claude Sonnet 4, and some improvements I took from Kimi K2's version of this project and merged manually into this code. (In a nutshell, I didn't like how Sonnet passed the http.Response down to functions that have no business knowing about HTTP stuff, to let them send a resposne. Kimi dedcided to keep HTTP stuff inside the handler and have the "worker" functions only deal with JSONRPC request and response structures. I applied this concept to Sonnet's code in #02a73315d.)

Features

• Calculates moon age (days since last new moon)
• Calculates illumination percentage (0-100%)
• Accepts specific datetime or uses current time
• Communicates via stdio using JSON-RPC format
• Provides MCP tool definitions for discovery

Usage

Run the server (dev mode):

go run .

Then add the server to your favorite AI coding tool. In case of Crush, see the crush.json file.

MCP Tool Discovery

List available tools:

{"method": "tools/list", "id": 1}

Response:

{
  "result": {
    "tools": [
      {
        "name": "moon_phase",
        "description": "Calculate the phase of the moon for a given date and time, or current time if not specified. Returns moon age in days and illumination percentage.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "datetime": {
              "type": "string",
              "description": "ISO 8601 datetime string (RFC3339 format). If not provided, uses current time.",
              "format": "date-time"
            }
          },
          "additionalProperties": false
        }
      }
    ]
  },
  "id": 1
}

(Note: The spec requires that each request carries a unique ID.)

Call Tools

Call the moon_phase tool:

{"method": "tools/call", "params": {"name": "moon_phase", "arguments": {"datetime": "2024-01-01T12:00:00Z"}}, "id": 2}

Direct Method Calls (Legacy)

Get current moon phase:

{"method": "moon_phase", "id": 1}

Get moon phase for specific date:

{"method": "moon_phase", "params": {"datetime": "2024-01-01T12:00:00Z"}, "id": 2}

Example Response

{"result": {"moon_age": 15.5, "illumination": 75}, "id": 1}

Testing

Run tests:

go test -v ./...

Implementation Details

• Uses Julian day calculation for accurate moon phase computation
• Lunar cycle: 29.53059 days
• DateTime format: RFC3339 (ISO 8601)
• Error codes follow JSON-RPC 2.0 specification
• Supports both MCP tool protocol and direct method calls