galaxy-maps-mcp

MCP stdio server for validating, saving, publishing, and inspecting Galaxy Maps courses from local JSON files.

Setup

Install dependencies with Bun when you are ready to run the server:

bun install

Runtime environment is read lazily, so the server can start without credentials. Firebase credentials are only required for tools that call Firebase.

export GALAXY_MAPS_FIREBASE_API_KEY="..."
export GALAXY_MAPS_EMAIL="..."
export GALAXY_MAPS_PASSWORD="..."

Optional overrides:

export GALAXY_MAPS_PROJECT_ID="galaxy-maps-ac367"
export GALAXY_MAPS_REGION="us-central1"

The Firebase API key value already lives in the platform repo .env as VITE_FIREBASE_API_KEY; reuse that value here as GALAXY_MAPS_FIREBASE_API_KEY.

Claude MCP Registration

Add this to ~/.claude.json:

{
  "mcpServers": {
    "galaxy-maps-mcp": {
      "command": "bun",
      "args": ["/home/ian/code/galaxy-maps-mcp/src/server.ts"],
      "env": {
        "GALAXY_MAPS_FIREBASE_API_KEY": "your-api-key",
        "GALAXY_MAPS_EMAIL": "your-email",
        "GALAXY_MAPS_PASSWORD": "your-password"
      }
    }
  }
}

Tools

validate_galaxy_map

Input:

{ "jsonPath": "/absolute/path/to/galaxy-map.json" }

Reads a local JSON file with Bun.file(path).text(). Accepts either a bare Galaxy Map object or a wrapped object:

{ "galaxyMap": { "...": "..." }, "mapLayout": "zigzag" }

Validation checks title, description, non-empty stars, non-empty planets, and required planet mission content. The report includes star count, planet count, total payload bytes, per-planet mission field byte sizes, and warnings for large payloads. It never prints mission HTML or the full map.

save_galaxy_map

Input:

{ "jsonPath": "/absolute/path/to/galaxy-map.json", "mapLayout": "zigzag" }

mapLayout is optional and may be "zigzag" or "spiral". The selected layout is explicit input first, then wrapped file mapLayout, then "zigzag".

Flow:

1. Validate the local file.
2. Sign in with Firebase Auth REST.
3. POST to https://{GALAXY_MAPS_REGION}-{GALAXY_MAPS_PROJECT_ID}.cloudfunctions.net/saveGalaxyMap.
4. Return course ID, total planets, layout, and https://app.galaxymaps.io/galaxy/{courseId}.

publish_course

Input:

{
  "courseId": "course-id",
  "visibility": "unlisted",
  "presentationOnly": false
}

visibility defaults to "unlisted" and may be "private", "unlisted", or "public". presentationOnly defaults to false.

Behavior:

• Public visibility patches the course to status: "submitted" and visibility: "public", then stops because admin review is required.
• Private or unlisted visibility publishes the course.
• If the course has no cohort and presentationOnly is false, the tool creates a default Squad cohort and attaches it to the course.
• If presentationOnly is true, the course is patched with presentationOnly: true and public: false.

get_course_status

Input:

{ "courseId": "course-id" }

Reads courses/{courseId} from Firestore REST and returns title, status, visibility, public flag, cohort, topic total, task total, and course URL.

Development

Run a TypeScript check:

bunx tsc --noEmit

Run the local handshake smoke test after dependencies are installed:

bun test/handshake.ts