geoharness
by GeoZcx
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。
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues