GeoD MCP 0.1.0

Local stdio MCP for acquiring real geographic data with GeoD CLI 0.1.1 and rendering it with GeoStyle/OpenStyle. Node.js 22+ is required. Data acquisition runs independently of the desktop UI. Rendering also needs a running GeoStyle server and Chrome/Edge.

Install in one command

On Windows x64 with Node.js 22+, run one of these commands in the workspace GeoD may access:

npx --yes [email protected] install codex
npx --yes [email protected] install workbuddy

Use --workspace C:\path\to\your\workspace to choose another folder. The command installs the package under %LOCALAPPDATA%\GeoD\Agent, starts it, verifies geod_capabilities and geod_plan, and writes the selected client's configuration. Codex also receives a geod-agent skill. Restart a client session if it does not discover a newly registered MCP server.

WorkBuddy's configuration is verified on disk and the MCP tools are called independently; a WorkBuddy client session has not yet been tested. This package is a local Windows stdio server. A cloud-only client needs a separately hosted, authenticated remote MCP endpoint.

Build from this source checkout

Build a portable npm tarball and install it into Codex without using the npm registry:

$built = powershell -NoProfile -File .\scripts\package-geod-mcp-npm.ps1 | ConvertFrom-Json
powershell -NoProfile -File .\scripts\install-geod-codex.ps1 -PackageSpec $built.tarball -Workspace (Get-Location).Path

The installer uses a fixed per-user directory under %LOCALAPPDATA%\GeoD\Agent, installs the already published [email protected] as a package dependency, registers a geod stdio server with codex mcp add, and installs the geod-agent skill. Before registration it starts the installed MCP process and calls geod_capabilities and geod_plan through JSON-RPC. It refuses to overwrite a different geod registration or skill. Set -Workspace to the folder that GeoD should be allowed to read and write.

GeoStyle rendering requires its separate server and browser; the installer's plan check does not claim a working render.

The same installed stdio entrypoint can be registered in WorkBuddy's user or project mcp.json:

powershell -NoProfile -File "$env:LOCALAPPDATA\GeoD\Agent\node_modules\geod-mcp\scripts\install-workbuddy.ps1" -Workspace (Get-Location).Path

The script verifies real MCP tool calls, preserves other JSON servers, refuses to replace a different geod entry, and backs up an existing configuration before writing. WorkBuddy is not installed on this verification machine, so client discovery and tool invocation there remain unverified. Cloud-hosted agents such as a remote Doubao Work session need a separately deployed, authenticated remote MCP endpoint; this local Windows stdio package is not such an endpoint.

Run from this checkout

cd C:\path\to\geo-downloader\packages\geod-mcp
npm ci --ignore-scripts
$env:GEOD_WORKSPACE = 'C:\path\to\your\workspace'
node src/index.mjs

The process waits for an MCP client on stdin. It emits only MCP protocol messages on stdout; it is not an interactive CLI prompt. The source checkout includes mcp.config.json as an editable template for clients that accept the mcpServers format. Replace its example absolute paths before using it. The Codex installer above writes a global Codex registration; running the server directly does not change client configuration.

{
  "mcpServers": {
    "geod": {
      "command": "node",
      "args": ["C:/absolute/path/to/geo-downloader/packages/geod-mcp/src/index.mjs"],
      "env": {
        "GEOD_WORKSPACE": "C:/path/to/your/workspace",
        "GEOD_BIN": "C:/absolute/path/to/geod.exe",
        "GEOSTYLE_URL": "http://127.0.0.1:3100"
      }
    }
  }
}

For the Windows ZIP, extract it and change args to the extracted src/index.mjs; omit GEOD_BIN to use the bundled executable. Production Node dependencies are included in the ZIP. Node, Chrome/Edge and the GeoStyle server are separate prerequisites. Set GEOD_WORKSPACE to the directory the AI should be able to read. Start one MCP server per output directory; use separate GEOD_OUTPUT_DIR values for independent clients.

AI workflow

1. Call geod_capabilities or read geod://examples/sichuan / geod://examples/henan.
2. Call geod_plan with { "request": { ... } }. It validates limits and returns the tile footprint without downloading.
3. Call geod_fetch with that request. It returns a jobId after local validation. Poll geod_job_status until completed, failed or cancelled (suggested interval 1 second).
4. Read result.bundleDir, result.manifest and artifacts. Check quality and warnings. geod_get_artifact takes { "jobId": "...", "artifactId": "imagery-preview" } and returns a native PNG block. vectors returns GeoJSON text; manifest returns JSON.
5. Call geod_render with { "bundleDir": "...", "openStyle": { ... }, "renderer": "openlayers", "width": 1600, "height": 1200 }. The OpenStyle object is optional; omitting it uses the data inspection style. Both openlayers and maplibre are supported. GeoStyle validates actual fields/layers.
6. Poll the render job. Read preview for a small native image, map for the full PNG, openstyle for the editable style, and render-evidence for actual rendering observations. These artifact IDs belong to the render job, separate from the download job.

Example instruction for an AI connected to this MCP:

用 geod 的四川示例先规划，再下载行政区和影像，按 boundary 裁剪。完成后用 GeoStyle 渲染 1600×1200 地图，展示图片并返回 GeoJSON、GeoTIFF、OpenStyle 和成果目录。根据质量字段如实说明数据范围。

The sample uses NASA Blue Marble overview imagery and DataV boundaries. It is not current high-resolution imagery and contains no verified attraction/POI dataset. The tool accepts parameters; it does not itself interpret place names or invoke an LLM. The calling AI selects boundaries, providers, layers and styles.

Tools

| Tool | Purpose | | --- | --- | | geod_capabilities | Paths, prerequisites, limits, examples | | geod_plan | Request validation and footprint/tile estimates | | geod_fetch | Start a download/import job | | geod_job_status | Progress, outcome, quality and artifact metadata | | geod_cancel_job | Request cancellation; poll until terminal | | geod_inspect | Validate a local bundle and file hashes | | geod_render | Import to GeoStyle and capture real browser rendering | | geod_get_artifact | Read registered image/data artifacts |

Completed artifacts also expose geod://artifacts/{jobId}/{artifactId} resources. Each includes a local path, media type, byte count and SHA-256. PNG/JPEG/WebP/GIF can be returned as native MCP images. GeoTIFF is intended for file-based analysis; it is not mislabeled as a display image. Inline file reads are capped at 8 MiB, with an additional 9,000,000-byte serialized MCP response limit to account for Base64 and JSON expansion. Oversized responses return an explicit error and the artifact path; the original file remains available for local processing. Use the small preview artifact when a full map is too large to display inline.

Configuration and behavior

| Environment variable | Default / meaning | | --- | --- | | GEOD_WORKSPACE | Current working directory; existing local inputs/bundles must be inside this directory or the output directory | | GEOD_OUTPUT_DIR | <workspace>/output/geod-mcp; one unique subdirectory per job | | GEOD_BIN | Bundled ZIP bin/geod.exe, npm dependency geod-cli/native/geod.exe, or source checkout target/release/geod.exe | | GEOSTYLE_URL | http://127.0.0.1:3100; the server used for imports and renders | | GEOSTYLE_GEOD_IMPORT_TOKEN | Optional import token; required when the GeoStyle server enforces one | | GEOD_MAX_CONCURRENT_JOBS | 2, configurable from 1 to 4; additional jobs return BUSY | | GEOD_RENDER_SCRIPT | Bundled or checkout scripts/geod-render.mjs | | CHROME_PATH | Optional browser path, forwarded to the renderer |

Local input paths are resolved against GEOD_WORKSPACE, including symlink resolution. The server launches fixed subprocesses with argument arrays and no shell. Request limits and source validation remain in geod-core. imagery.clipToLayer masks PNG/GeoTIFF by polygon union, preserving holes; vector geometries are unchanged. JPEG cannot carry the clipped transparent result.

geod_fetch and geod_render are application-level background jobs, independent of any client's optional MCP Tasks support. They continue after the start-tool response as long as this server process remains alive. Cancellation transitions through cancelling, then cancelled. Renderer cancellation uses IPC so its temporary browser can close on Windows. Closing the stdio input cancels active work. Completed records and artifacts remain readable after restart; unfinished records become failed with INTERRUPTED. Downloads do not resume automatically, and cancelled jobs do not publish registered artifacts. Files are retained locally, including possible partial job files, until the user removes the relevant job directory while no job is running.

Verification

npm test
npm run test:live

Run these verification commands from the source checkout (tests and live-smoke are not distributed in the production ZIP). The test suite uses the official SDK client and real stdio processes, a local tile/GeoJSON server, transparent polygon-hole assertions, artifact/resource readback, cancellation, path boundaries and restart behavior. The live smoke script in the source checkout downloads the real Sichuan example, renders through GeoStyle, reads the native MCP image block back, and writes it to output/geod-mcp-verification-*/sichuan-via-mcp.png. It requires the release CLI, network sources, the GeoStyle server and Chrome/Edge.

Protocol integration uses the official TypeScript SDK server/client packages, pinned to 2.0.0. The server supports the SDK's stdio negotiation and legacy opening mode. A remote HTTP MCP service and OAuth are not included.