Skip to main content

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).

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。

Metadata

Release files for geoharness 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for geoharness 0.1.0
File Size Uploaded Provenance Actions
geoharness-0.1.0.tar.gz 330.7 kB Without provenance Details for geoharness-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for geoharness 0.1.0
File Interpreter ABI Platform Actions
geoharness-0.1.0-py3-none-any.whl Python 3 none any Details for geoharness-0.1.0-py3-none-any.whl

Total release size: 741.7 kB

Release files / geoharness-0.1.0.tar.gz

Download URL geoharness-0.1.0.tar.gz
Size 330.7 kB
Tags Source
SHA-256 checksum
How to use checksums
444fac0905acfcf9716cdbb830b7dd773e0790a4f7bc23bd8d0b88c792fbefd2
BLAKE2b-256 checksum
How to use checksums
ad55ecc5d72800ffa0382fd36838d40f345f1b64546190a7b1d77ddc3033fc77
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.3 {"installer":{"name":"uv","version":"0.11.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / geoharness-0.1.0-py3-none-any.whl

Download URL geoharness-0.1.0-py3-none-any.whl
Size 411.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0f098dca4bf79c54b420fd7693abf24c8c987f570bf5be7f340ee52a1b75e40d
BLAKE2b-256 checksum
How to use checksums
187b47b6c0950c8cd724a445e83487f05135e9edcfb75c244c0744a53242ff79
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.3 {"installer":{"name":"uv","version":"0.11.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for geoharness 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page