# Pi Okf

> Harness-owned reader/author for Pi-agent OKF (Open Knowledge Format) knowledge bundles

- **Type:** MCP server
- **Install:** `agentstack add mcp-renezander030-pi-okf`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [renezander030](https://agentstack.voostack.com/s/renezander030)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [renezander030](https://github.com/renezander030)
- **Source:** https://github.com/renezander030/pi-okf

## Install

```sh
agentstack add mcp-renezander030-pi-okf
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# pi-okf

**A Pi-agent extension for [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) (OKF) bundles.** It lets an agent read a curated, git-versioned knowledge bundle so it does not start every session from scratch, and write enrichments back. Consumption is always allowed; new knowledge reaches the canonical bundle only through a trust gate, the same way [pi-gate](https://github.com/renezander030/pi-gate) gates code changes.

OKF (Google Cloud, v0.1) represents knowledge as a directory of markdown files with YAML frontmatter. One file is a **concept**; a directory of concepts is a **bundle**. The only required frontmatter field is a non-empty `type`. If you can `cat` a file you can read it; if you can `git clone` you can ship it.

## Why

MCP tools give an agent access to your systems. They do not tell it *where the data sits, which source is canonical, or how the systems connect* — that knowledge lives in people, and the agent re-discovers it every session. An OKF bundle is that knowledge written down, versioned in git, and served to the agent. `pi-okf` is the deterministic, harness-owned tool for reading and curating it.

## Install

Requires **Node ≥ 18** and **git**.

```sh
git clone https://github.com/renezander030/pi-okf
ln -s "$PWD/pi-okf/pi-okf" /usr/local/bin/pi-okf   # or add to PATH
pi-okf help
```

## Quick start

```sh
# CONSUME — what does the bundle hold, and is it conformant?
pi-okf survey   --bundle ./knowledge -H
pi-okf validate --bundle ./knowledge -H
pi-okf read tables/users --bundle ./knowledge      # one concept as JSON

# AUTHOR — the agent writes a concept into its staging copy
pi-okf enrich tables/orders --type "BigQuery Table" \
  --description "Canonical order ledger" --staging ./agent-tree

# LAND — merge staging enrichments into the trusted, git-versioned bundle
pi-okf trust  --bundle ./knowledge                 # bless the source once, after review
pi-okf plan   --canonical ./knowledge --staging ./agent-tree -H
pi-okf apply  --canonical ./knowledge --staging ./agent-tree
```

An untrusted bundle is read-only to `apply`: enrichments are withheld until you review and `pi-okf trust` it (or pass `--override ""`).

## CLI

| Command | Purpose |
|---|---|
| `survey` | Catalog every concept (id, type, title, description) for progressive disclosure. |
| `read ` | Fetch one concept: parsed frontmatter + body. |
| `validate` | OKF v0.1 conformance (spec §9). Exit 1 if any concept lacks a parseable frontmatter with non-empty `type`. Broken links / missing `index.md` are warnings. |
| `index [--write]` | Generate the progressive-disclosure `index.md`, grouped by `type`. |
| `enrich  --type T` | Author a conformant concept stub into `--staging`; logs to `log.md`. |
| `plan` | Concept-level diff (added / modified / removed) of staging vs canonical, plus trust state. |
| `apply [--override R]` | Merge staging enrichments into the canonical bundle, IFF staging is conformant **and** canonical is trusted. |
| `trust [--label L]` | Register the canonical bundle as a trusted knowledge source. |
| `bundles` | List trusted bundles. |

JSON by default; `-H`/`--human` for a table.

## Trust model

Faithful to pi-gate:

| Invariant | How |
|---|---|
| The record of what is *trusted* lives outside the agent's tree | trusted-bundle registry at `~/.config/pi-okf/bundles.json`; apply state at `~/.local/state/pi-okf/` |
| Stable bundle identity across moves | git root-commit sha, falling back to a path hash |
| Enrichments land only on a conformant, trusted bundle | `apply` gate; non-conformant or untrusted requires an explicit `--override ""` |
| Every land is auditable | appended to the bundle's `log.md` and to the state `apply.log` |

## Conformance (spec §9)

A bundle is conformant when every non-reserved `.md` file parses to a YAML frontmatter block with a non-empty `type`. Reserved files (`index.md`, `log.md`) carry no frontmatter. Consumers tolerate unknown types, unknown keys, broken cross-links, and a missing `index.md` — these are warnings, never errors.

## Roadmap

Typed-edge extraction from cross-links, `search` over concept bodies, an MCP server that exposes a trusted bundle as `resource://` URIs, and per-concept (rather than whole-bundle) trust promotion.

## License

MIT

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [renezander030](https://github.com/renezander030)
- **Source:** [renezander030/pi-okf](https://github.com/renezander030/pi-okf)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-renezander030-pi-okf
- Seller: https://agentstack.voostack.com/s/renezander030
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.