Skip to content

AGENTS.md

Latest commit

 

History

History
83 lines (66 loc) · 4.15 KB

AGENTS.md

File metadata and controls

83 lines (66 loc) · 4.15 KB
Raw

AGENTS.md — cesium-mcp

AI agent integration for CesiumJS. A monorepo providing an MCP server that lets AI agents control a 3D globe (CesiumJS) in the browser via WebSocket, plus IDE tooling for Cesium API doc lookup and code generation.

Monorepo Structure

packages/
  cesium-mcp-bridge/    # SDK — command execution layer (browser-side, controls Cesium viewer)
  cesium-mcp-runtime/   # MCP stdio/HTTP server — bridges AI agents to browser via WebSocket
  cesium-mcp-dev/       # IDE assistant — Cesium API doc queries and code generation
examples/               # browser-agent, dify-integration, emergency-response, minimal, video
docs/                   # VitePress site (guide, api, design, examples, zh-CN)
.Codex-plugin/         # Codex plugin manifest
hooks/                  # Plugin hooks (SessionStart, etc.)
skills/                 # Plugin skills (/cesium-quickstart)

Commands

Command Purpose
npm run build Build all packages (tsup)
npm test / npx vitest run Run tests
npm run lint ESLint all packages
npm run typecheck tsc --noEmit across workspaces
npm run clean Remove all dist/
npm run build -w packages/cesium-mcp-bridge Build one package
npm run changeset Add a changeset for versioning

Install: npm ci at root (workspaces + patch-package postinstall).

Code Conventions

  • No semicolons. Single quotes. Trailing commas on multi-line.
  • 2-space indent. ESM throughout.
  • import type { ... } separate from value imports.
  • Files: kebab-case. Symbols: camelCase functions/vars, PascalCase types/classes.
  • Type suffixes: XxxParams, XxxResult.
  • One file per domain under src/commands/ (camera.ts, layer.ts, scene.ts, etc.).
  • Commands are plain functions (viewer: Cesium.Viewer, params: XxxParams) => result, not classes.
  • Tests: Vitest, colocated as *.test.ts. Import source via ./foo.js (NodeNext ESM).
  • Types in types.ts with // ========== Section ========== banners. No zod in bridge.

Adding a New Tool

  1. Bridge command — Add a function in packages/cesium-mcp-bridge/src/commands/. Export from index.ts.
  2. Runtime tool — In packages/cesium-mcp-runtime/src/index.ts, call _registerTool() with:
    • Name, description, Zod schema shape (params), MCP annotations, async handler.
    • Handler calls sendToBrowser(sessionId, { action, params }) and awaits the response.
  3. Toolset — Add the tool to an existing toolset array or create a new one. Default-enabled toolsets: view, entity, layer, interaction.

Meta-tools list_toolsets / enable_toolset let agents discover and activate toolsets at runtime.

Environment Variables

Variable Purpose Default
CESIUM_WS_PORT WebSocket server port 9100
CESIUM_TOOLSETS Enabled toolsets (comma-sep or "all") view,entity,layer,interaction
CESIUM_LOCALE Locale (en / zh-CN) en
CESIUM_ION_TOKEN Cesium Ion access token —
DEFAULT_SESSION_ID Multi-browser session routing —
MCP_TRANSPORT Transport mode (stdio / http) stdio
MCP_HTTP_PORT HTTP transport port WS_PORT + 100
HTTPS_PROXY / HTTP_PROXY / ALL_PROXY Proxy for geocode —
OSM_USER_AGENT User-Agent for OSM Nominatim —

Do NOT

  • Commit .env files, .vscode/mcp.json, or any Ion tokens / API keys.
  • Use npm or yarn — this repo uses npm workspaces with npm ci.
  • Modify hardcoded Ion tokens in examples/ without replacing them with env-var references.
  • Commit the .codegraph/ directory (local-only, gitignored).
  • Report security vulnerabilities in public issues (use GitHub Security Advisories).
  • Bump CesiumJS beyond ~1.139.x without checking peer dependency constraints (^1.114.0).

Working Principles

  • Think first. State assumptions. Surface tradeoffs. Ask when uncertain.
  • Simplicity. Minimum code that solves the problem. No speculative abstractions.
  • Surgical changes. Touch only what you must. Match existing style. Remove only orphans your changes created.
  • Goal-driven. Define success criteria, verify each step. Write a failing test, then make it pass.