Skip to main content
Glama

geoharness

Verifiable execution for geospatial agents. geoharness is an MCP server that lets any LLM agent plan a geospatial workflow as an operator DAG, then statically verifies that plan against geo-typed operator contracts before anything runs. Failures come back as structured diagnoses (attribute, required, actual, repairable, repair, hint) that the agent can act on, and only a plan the server verified (it issues a verified_hash) can be executed. Every call is recorded in a local, hash-chained provenance ledger.

It is a reference implementation of the GeoAgent specification, supporting a forthcoming standardization effort (a follow-up to ISO/AWI TR 19182). It carries no ISO endorsement.

Status: alpha (0.1.0). APIs, the operator set and file formats may change. Expect rough edges; please read Limitations.

Scope: geoharness verifies and constrains a planner-supplied DAG. It does not search for or synthesize workflows; planning stays with your agent.

Install and run

uvx --from "geoharness[mcp,geo]" geoharness-mcp

Requires uv. The mcp extra provides the server, the geo extra (shapely, rasterio, fiona, numpy) provides real raster/vector IO and execution. Verification-only use works without geo. Python 3.11-3.13 is covered by CI. The geo extra currently needs Python <= 3.13 (fiona publishes no Python 3.14 wheels; a source build needs GDAL); on 3.14 use geoharness[mcp] for verification only.

Claude Code (plugin)

claude --plugin-dir plugins/claude-code/geoharness

The plugin bundles the MCP server launcher, the geoharness-workflow skill and local hooks that record host context next to the ledger. Check it with claude plugin validate plugins/claude-code/geoharness. See plugins/claude-code/geoharness/README.md.

pi

pi mcp add geoharness -- uvx --from "geoharness[mcp,geo]" geoharness-mcp
mkdir -p ~/.pi/agent/skills && cp -r plugins/pi/skills/geoharness-workflow ~/.pi/agent/skills/

See plugins/pi/README.md.

Any other MCP client

Add a stdio server entry:

{
  "mcpServers": {
    "geoharness": {
      "command": "uvx",
      "args": ["--from", "geoharness[mcp,geo]", "geoharness-mcp"]
    }
  }
}

Give the agent the protocol from plugins/pi/skills/geoharness-workflow/SKILL.md (plain Markdown). Without host hooks the exported trace covers the ledger only (coverage: ledger-only).

Related MCP server: MIDAS

The 7 tools

Tool

Purpose

ingest_asset

Read a raster/vector/table from the workspace; returns an asset_id and typed attributes (CRS, resolution, bands, ...). Sources are bound by asset_id; agents cannot assert metadata.

list_operators

List operator contracts (slots, constraints, parameters, output rules, trust tier).

verify_dag

Verify a whole DAG (geoagent-dag/3.0) plus optional task requirements; returns diagnoses, runtime obligations and a verified_hash iff it passed.

apply_repairs

Apply the repairable fixes from diagnoses and re-verify. Unrepairable problems are reported, never faked.

execute_dag

Run a verified DAG (needs the issued verified_hash); returns output files, checksums and runtime (L4) diagnoses.

register_operator

Register a provisional, LLM-authored operator (contract + Python source) behind gates G1-G5.

export_trace

Export the provenance ledger as a zip bundle (full or research profile).

There is deliberately no single-operator execution tool: the gate needs the whole DAG.

Protocol: ingest_asset for each input, list_operators, write the WHOLE DAG, verify_dag, repair if needed, execute_dag. If an operator is missing, tell the user first, then register_operator. Design details: docs/SPEC.md. Authoring contracts and operators: docs/AUTHORING.md. JSON Schema of contracts: geoharness/contracts/schemas/contract-1.0.json.

Privacy

  • Everything is recorded locally under <workspace>/.geoharness/ (override with GEOHARNESS_HOME; the old name GEOAGENT_HOME is still accepted). Nothing is uploaded, ever.

  • The ledger stores paths, sizes and SHA-256 checksums, never your data; secrets and environment values are redacted; chain-of-thought is never read or stored.

  • The server needs no LLM API key and makes no network calls of its own.

Research bundle submission

If you want to help evaluate geoharness, export_trace(profile="research") writes a redacted bundle (absolute paths and usernames stripped) after your agent asks you for annotations and your explicit consent. Bundles land in .geoharness/exports/. Sharing is manual: you decide whether and where to send a bundle; the server never uploads anything. Review the zip before sharing it.

Limitations

  • The sandbox is defence in depth, not a security boundary. Provisional operators run Python written by an LLM in a restricted child process (AST scan, import whitelist, audit hook, timeouts, size and memory caps). There are no OS-level namespaces or seccomp; native code in whitelisted libraries is invisible to the audit hook. Only register operators you are comfortable running; they are flagged "LLM-authored, unreviewed".

  • Trace replay does not support provisional operators (python -m geoharness.mcp.trace replay).

  • Large rasters cross the sandbox boundary as JSON, so provisional operators on big rasters are slow and memory-hungry.

  • Alpha: the built-in library is 25 operators; many common GIS operations are not yet covered (see docs/OPERATOR_AUDIT.md, written in Chinese).

  • The verifier is static (L1-L3) plus runtime post-checks (L4); it checks declared contracts, not the scientific appropriateness of an analysis.

Development

uv sync --extra mcp --extra geo --extra dev
uv run pytest -q

See CONTRIBUTING.md. License: Apache-2.0.


中文说明

geoharness:面向地理空间智能体的“先验证、后执行”框架。

geoharness 是一个 MCP 服务器。任何 LLM 智能体可以把地理空间分析写成算子 DAG,由 geoharness 在执行之前 依据带地理类型的算子契约对其做静态验证;失败时返回结构化诊断(属性、要求、实际值、可否修复、修复方案、提示), 而不是一个布尔值。只有通过验证、并由服务器签发了 verified_hash 的 DAG 才能被执行。每次调用都会写入本地、 哈希链接的溯源账本。

它是 GeoAgent 规范的参考实现,用于支持一项即将开展的标准化工作(ISO/AWI TR 19182 的后续工作), 不代表获得 ISO 的认可。

状态:alpha(0.1.0)。 接口、算子集合和文件格式都可能变化,请先阅读下面的“局限”。

范围:geoharness 只验证、约束由规划器给出的 DAG,不负责搜索或合成工作流;规划由你的智能体完成。

安装与运行

uvx --from "geoharness[mcp,geo]" geoharness-mcp

需要 uv。mcp 额外依赖提供服务器,geo(shapely、rasterio、fiona、numpy)提供真实的栅格/矢量读写与执行; 只做验证时可不装 geo。

  • Claude Code(插件):claude --plugin-dir plugins/claude-code/geoharness,可用 claude plugin validate plugins/claude-code/geoharness 校验。

  • pi:pi mcp add geoharness -- uvx --from "geoharness[mcp,geo]" geoharness-mcp,并把 plugins/pi/skills/geoharness-workflow 复制到 ~/.pi/agent/skills/。

  • 其他 MCP 客户端:按上文 JSON 添加 stdio 服务器,并把 skill 文本交给智能体作为协议说明。

七个工具

ingest_asset(读入数据并签发 asset_id)、list_operators(列出算子契约)、verify_dag(验证整个 DAG)、 apply_repairs(应用可修复项并重新验证)、execute_dag(执行已验证的 DAG)、register_operator (注册 LLM 编写的临时算子,需通过 G1-G5 五道关卡)、export_trace(导出溯源包)。 刻意不提供“单算子执行”工具:闸门需要完整的 DAG。

隐私

  • 所有记录都保存在本地的 <工作区>/.geoharness/(可用 GEOHARNESS_HOME 修改,旧名 GEOAGENT_HOME 仍可用)。 任何内容都不会被上传。

  • 账本只记录路径、大小和 SHA-256,不复制你的数据;密钥与环境变量值会被脱敏;不读取、不保存思维链。

  • 服务器本身不需要任何 LLM API key,也不主动发起网络请求。

研究用溯源包提交

export_trace(profile="research") 会在智能体向你询问标注内容并获得你明确同意之后,导出脱敏的研究包 (绝对路径、用户名被移除),保存在 .geoharness/exports/。是否提交、提交到哪里完全由你手动决定,服务器不会上传。 分享前请自行检查该 zip。

局限

  • 沙箱只是纵深防御,不是安全边界。 临时算子运行的是 LLM 编写的 Python,只在受限子进程中执行(AST 扫描、 导入白名单、审计钩子、超时与内存限制),没有操作系统级隔离。请只注册你愿意运行的算子。

  • 溯源包重放不支持临时(provisional)算子。

  • 大栅格以 JSON 形式穿过沙箱边界,临时算子处理大栅格会很慢、占内存。

  • alpha 阶段:内置 25 个算子,许多常见 GIS 操作尚未覆盖(见 docs/OPERATOR_AUDIT.md)。

  • 验证器检查的是已声明的契约,不判断分析方法在科学上是否合适。

许可证:Apache-2.0。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers