feat(gateway): add unified MCP gateway with per-domain enable/disable

mcp/cesium-js/README.md

@@ -13,6 +13,7 @@ pnpm monorepo containing MCP servers and test applications for controlling [Cesi
 | [`@cesium-mcp/imagery-server`](./servers/imagery-server/README.md)              | Imagery layer management: add, remove, and list imagery providers                    | 3005 |
 | [`@cesium-mcp/tiles-server`](./servers/tiles-server/README.md)                  | 3D Tiles management: add, remove, and configure 3D Tilesets                          | 3006 |
 | [`@cesium-mcp/terrain-server`](./servers/terrain-server/README.md)              | Terrain provider management: set, get, and remove terrain sources                    | 3007 |
+| [`@cesium-mcp/gateway`](./servers/gateway/README.md)                            | Unified gateway aggregating multiple domain servers with runtime enable/disable      | 3010 |
 | [`@cesium-mcp/client-core`](./test-applications/packages/client-core/README.md) | Shared browser client library (managers, communications)                             | —    |
 | [`@cesium-mcp/cesium-js`](./test-applications/README.md)                        | Browser web application (CesiumJS viewer)                                            | 8080 |
 
@@ -88,6 +89,18 @@ Manage terrain providers on the CesiumJS globe.
 | `terrain_get`    | Get current terrain provider info and capabilities  |
 | `terrain_remove` | Remove terrain and reset to flat WGS84 ellipsoid    |
 
+### 🧭 [cesium-gateway](./servers/gateway/README.md)
+
+Unified gateway that aggregates multiple domain servers behind a single MCP endpoint and exposes meta-tools for runtime domain discovery. Helps keep the active tool surface small when many servers would otherwise be connected at once.
+
+| Tool                    | Description                                                   |
+| ----------------------- | ------------------------------------------------------------- |
+| `cesium_list_domains`   | List all domains with enabled/disabled status and tool counts |
+| `cesium_enable_domain`  | Enable all tools in a domain at runtime                       |
+| `cesium_disable_domain` | Disable all tools in a domain at runtime                      |
+
+The set of domains started at boot is controlled by the `CESIUM_DOMAINS` environment variable (comma-separated, case-insensitive; omitted or empty means enable all).
+
 ## 🏗️ Structure
 
 ```
@@ -99,7 +112,8 @@ cesium-js/
 │   ├── animation-server/    # @cesium-mcp/animation-server
 │   ├── imagery-server/      # @cesium-mcp/imagery-server
 │   ├── tiles-server/        # @cesium-mcp/tiles-server
-│   └── terrain-server/      # @cesium-mcp/terrain-server
+│   ├── terrain-server/      # @cesium-mcp/terrain-server
+│   └── gateway/             # @cesium-mcp/gateway
 ├── test-applications/
 │   ├── packages/
 │   │   └── client-core/     # @cesium-mcp/client-core
@@ -136,6 +150,7 @@ pnpm run build:animation    # @cesium-mcp/animation-server only
 pnpm run build:imagery      # @cesium-mcp/imagery-server only
 pnpm run build:tiles        # @cesium-mcp/tiles-server only
 pnpm run build:terrain      # @cesium-mcp/terrain-server only
+pnpm run build:gateway      # @cesium-mcp/gateway only
 pnpm run build:cesium-js    # @cesium-mcp/cesium-js (web app) only
 pnpm run clean              # Remove all build artifacts
 ```
@@ -151,6 +166,7 @@ pnpm run dev:animation     # Animation server on port 3004
 pnpm run dev:imagery       # Imagery server on port 3005
 pnpm run dev:tiles         # Tiles server on port 3006
 pnpm run dev:terrain       # Terrain server on port 3007
+pnpm run dev:gateway       # Gateway on port 3010
 ```
 
 ### Web Application
@@ -233,6 +249,16 @@ Add the servers to your MCP client (e.g., Claude Desktop, Cline):
         "TERRAIN_SERVER_PORT": "3007",
         "STRICT_PORT": "false"
       }
+    },
+    "cesium-gateway": {
+      "command": "node",
+      "args": ["{YOUR_WORKSPACE}/mcp/cesium-js/servers/gateway/build/index.js"],
+      "env": {
+        "COMMUNICATION_PROTOCOL": "websocket",
+        "GATEWAY_SERVER_PORT": "3010",
+        "GATEWAY_DOMAINS": "camera,entity,animation,imagery,tiles,terrain",
+        "STRICT_PORT": "false"
+      }
     }
   }
 }

mcp/cesium-js/package.json

@@ -5,21 +5,23 @@
   "type": "module",
   "private": true,
   "scripts": {
-    "build": "pnpm run build:shared && pnpm run build:camera && pnpm run build:entity && pnpm run build:animation && pnpm run build:imagery && pnpm run build:tiles && pnpm run build:terrain && pnpm run build:cesium-js",
+    "build": "pnpm run build:shared && pnpm run build:camera && pnpm run build:entity && pnpm run build:animation && pnpm run build:imagery && pnpm run build:tiles && pnpm run build:terrain && pnpm run build:gateway && pnpm run build:cesium-js",
     "build:shared": "pnpm --filter @cesium-mcp/shared build",
     "build:camera": "pnpm --filter @cesium-mcp/camera-server build",
     "build:entity": "pnpm --filter @cesium-mcp/entity-server build",
     "build:animation": "pnpm --filter @cesium-mcp/animation-server build",
     "build:imagery": "pnpm --filter @cesium-mcp/imagery-server build",
     "build:tiles": "pnpm --filter @cesium-mcp/tiles-server build",
     "build:terrain": "pnpm --filter @cesium-mcp/terrain-server build",
+    "build:gateway": "pnpm --filter @cesium-mcp/gateway build",
     "build:cesium-js": "pnpm --filter @cesium-mcp/cesium-js build",
     "dev:camera": "pnpm --filter @cesium-mcp/camera-server dev",
     "dev:entity": "pnpm --filter @cesium-mcp/entity-server dev",
     "dev:animation": "pnpm --filter @cesium-mcp/animation-server dev",
     "dev:imagery": "pnpm --filter @cesium-mcp/imagery-server dev",
     "dev:tiles": "pnpm --filter @cesium-mcp/tiles-server dev",
     "dev:terrain": "pnpm --filter @cesium-mcp/terrain-server dev",
+    "dev:gateway": "pnpm --filter @cesium-mcp/gateway dev",
     "start:web": "pnpm --filter @cesium-mcp/cesium-js start:web",
     "clean": "pnpm -r run clean",
     "lint": "eslint .",
@@ -34,7 +36,8 @@
     "test:animation": "pnpm --filter @cesium-mcp/animation-server test",
     "test:imagery": "pnpm --filter @cesium-mcp/imagery-server test",
     "test:tiles": "pnpm --filter @cesium-mcp/tiles-server test",
-    "test:terrain": "pnpm --filter @cesium-mcp/terrain-server test"
+    "test:terrain": "pnpm --filter @cesium-mcp/terrain-server test",
+    "test:gateway": "pnpm --filter @cesium-mcp/gateway test"
   },
   "keywords": [
     "mcp",

mcp/cesium-js/servers/animation-server/package.json

@@ -4,6 +4,10 @@
   "description": "MCP server for Cesium animation, path-based entity control, and clock management",
   "type": "module",
   "main": "build/index.js",
+  "exports": {
+    ".": "./build/index.js",
+    "./tools": "./build/tools/index.js"
+  },
   "bin": {
     "cesium-animation-mcp": "./build/index.js"
   },

mcp/cesium-js/servers/camera-server/package.json

@@ -24,7 +24,8 @@
   ],
   "license": "Apache-2.0",
   "exports": {
-    ".": "./build/index.js"
+    ".": "./build/index.js",
+    "./tools": "./build/tools/index.js"
   },
   "dependencies": {
     "@cesium-mcp/shared": "workspace:*",

mcp/cesium-js/servers/entity-server/package.json

@@ -9,7 +9,8 @@
   },
   "exports": {
     ".": "./build/index.js",
-    "./schemas": "./build/schemas.js"
+    "./schemas": "./build/schemas.js",
+    "./tools": "./build/tools/index.js"
   },
   "scripts": {
     "build": "tsc",

mcp/cesium-js/servers/gateway/.env.example

@@ -0,0 +1,8 @@
+PORT=3010
+MAX_RETRIES=10
+COMMUNICATION_PROTOCOL=websocket
+STRICT_PORT=false
+MCP_TRANSPORT=stdio
+# Comma-separated list of domains to enable at startup. Leave empty or omit to enable all.
+# Valid values: camera, entity, animation, imagery, tiles, terrain
+# CESIUM_DOMAINS=camera,entity,animation,imagery,tiles,terrain

mcp/cesium-js/servers/gateway/README.md

@@ -0,0 +1,100 @@
+# Cesium Gateway MCP Server
+
+A unified MCP server that aggregates all Cesium domain servers (camera, entity, animation, imagery, tiles, terrain) into a single endpoint with dynamic domain management.
+
+## Features
+
+- **Single endpoint** — one MCP server exposes all domain tools
+- **Domain filtering** — enable only the domains you need via `CESIUM_DOMAINS`
+- **Runtime control** — dynamically enable/disable domains with discovery tools
+- **Shared communication** — all domains share one WebSocket/SSE connection to the browser
+
+## Quick Start
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build
+pnpm run build
+
+# Run
+pnpm start
+```
+
+## Configuration
+
+| Variable                 | Default     | Description                               |
+| ------------------------ | ----------- | ----------------------------------------- |
+| `PORT`                   | `3010`      | Communication server port                 |
+| `CESIUM_DOMAINS`         | _(all)_     | Comma-separated list of domains to enable |
+| `COMMUNICATION_PROTOCOL` | `websocket` | `websocket` or `sse`                      |
+| `MCP_TRANSPORT`          | `stdio`     | `stdio` or `streamable-http`              |
+| `MAX_RETRIES`            | `10`        | Max retries for communication server port |
+| `STRICT_PORT`            | `false`     | Fail if port is already in use            |
+
+### Domain Selection
+
+```bash
+# Enable all domains (default)
+CESIUM_DOMAINS=
+
+# Enable only camera and entity
+CESIUM_DOMAINS=camera,entity
+
+# Available domains: camera, entity, animation, imagery, tiles, terrain
+```
+
+## MCP Client Configuration
+
+### Claude Desktop / Cursor
+
+```json
+{
+  "mcpServers": {
+    "cesium-gateway": {
+      "command": "node",
+      "args": ["path/to/servers/gateway/build/index.js"],
+      "env": {
+        "PORT": "3010",
+        "CESIUM_DOMAINS": "camera,entity,animation,imagery,tiles,terrain"
+      }
+    }
+  }
+}
+```
+
+## Discovery Tools
+
+The gateway exposes three meta-tools for runtime domain management:
+
+| Tool                    | Description                                                   |
+| ----------------------- | ------------------------------------------------------------- |
+| `cesium_list_domains`   | List all domains with enabled/disabled status and tool counts |
+| `cesium_enable_domain`  | Enable a previously disabled domain                           |
+| `cesium_disable_domain` | Disable a domain, hiding its tools                            |
+
+These tools use the MCP SDK's `RegisteredTool.enable()`/`disable()` API, so clients that support `tools/list_changed` notifications will see the tool list update in real time.
+
+## Architecture
+
+```
+MCP Client
+    │
+    ▼
+┌──────────────────────────────┐
+│     Gateway MCP Server       │
+│  ┌────────────────────────┐  │
+│  │   DomainRegistry       │  │
+│  │  ┌──────┐ ┌──────┐    │  │
+│  │  │camera│ │entity│ .. │  │
+│  │  └──────┘ └──────┘    │  │
+│  └────────────────────────┘  │
+│  ┌────────────────────────┐  │
+│  │   Discovery Tools      │  │
+│  └────────────────────────┘  │
+└──────────────┬───────────────┘
+               │ WebSocket/SSE
+               ▼
+         CesiumJS App
+```

mcp/cesium-js/servers/gateway/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@cesium-mcp/gateway",
+  "version": "1.0.0",
+  "description": "Unified MCP gateway server that combines all Cesium domain servers into a single process",
+  "type": "module",
+  "main": "./build/index.js",
+  "bin": {
+    "cesium-gateway-mcp": "./build/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf build",
+    "dev": "tsx src/index.ts",
+    "start": "node build/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "keywords": [
+    "mcp",
+    "cesium",
+    "gateway",
+    "3d",
+    "geospatial"
+  ],
+  "license": "Apache-2.0",
+  "exports": {
+    ".": "./build/index.js"
+  },
+  "dependencies": {
+    "@cesium-mcp/shared": "workspace:*",
+    "@cesium-mcp/camera-server": "workspace:*",
+    "@cesium-mcp/entity-server": "workspace:*",
+    "@cesium-mcp/animation-server": "workspace:*",
+    "@cesium-mcp/imagery-server": "workspace:*",
+    "@cesium-mcp/tiles-server": "workspace:*",
+    "@cesium-mcp/terrain-server": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "dotenv": "^16.4.7",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.2",
+    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/ui": "^4.0.18",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}