Skip to main content
Glama
README.md
# 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](#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`](docs/SPEC.md). Authoring contracts and operators:
[`docs/AUTHORING.md`](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](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。