# OKFy

> Turn docs into agent-readable knowledge bundles using Open Knowledge Format (OKF)

- **Type:** MCP server
- **Install:** `agentstack add mcp-0dust-okfy`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [0dust](https://agentstack.voostack.com/s/0dust)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [0dust](https://github.com/0dust)
- **Source:** https://github.com/0dust/OKFy

## Install

```sh
agentstack add mcp-0dust-okfy
```

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

## About

Open Knowledge Format for AI agents.

  Turn docs into agent-readable knowledge bundles.

  
    OKF bundles | MCP server | local-first | no LLM key | Git-diffable context
  

  
    
    
    
    
    
  

  
    Use with agents |
    Activation packet |
    Preview Inspector |
    Project stack workspaces |
    Keep sources fresh |
    Create a bundle |
    CLI install |
    Why OKF |
    More clients
  

---

Agents are bad at reading docs when the only options are "paste everything" or "trust a hidden vector index".

`okfy` converts documentation websites and local Markdown folders into [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) v0.1-conformant bundles: typed Markdown concept files with frontmatter, reserved navigation files, source URLs, internal links, backlinks, and a read-only MCP server. It can also remember third-party docs sources locally and refresh their bundles when they go stale.

Use it when you want Claude, Codex, Cursor, or another MCP-capable agent to search one docs source or a whole project stack, read only the relevant pages, traverse neighbors, and cite sources without dumping docs sites into context.

## Use With Agents

okfy is meant to sit behind your coding agent as a local MCP server. Run setup once for a docs source, then Claude, Codex, Cursor, or any MCP client can search and read the local OKF bundle on demand.

Create a registered source and print a client-ready setup preview:

```bash
npx -y okfy-ai init stripe https://docs.stripe.com/checkout --client codex --max-pages 100 --max-depth 4
```

`init` prints the MCP launch command, client config, and a first prompt. It does not write client config files by default. The generated launch command will look like `npx -y okfy-ai serve stripe --mcp --auto-refresh`.

The MCP server uses the cached local bundle immediately. When the source is stale, `--auto-refresh` refreshes it according to the source policy while keeping freshness metadata visible through `bundle_summary`.

### Claude Code

```bash
claude mcp add --transport stdio stripe-okf -- npx -y okfy-ai serve stripe --mcp --auto-refresh
```

### Claude Desktop Or Cursor

Add this to `claude_desktop_config.json`, `.cursor/mcp.json`, or any client that accepts `mcpServers` JSON:

```json
{
  "mcpServers": {
    "stripe-okf": {
      "command": "npx",
      "args": ["-y", "okfy-ai", "serve", "stripe", "--mcp", "--auto-refresh"]
    }
  }
}
```

### Codex

Add this to `~/.codex/config.toml` or a trusted project config:

```toml
[mcp_servers.stripe_okf]
command = "npx"
args = ["-y", "okfy-ai", "serve", "stripe", "--mcp", "--auto-refresh"]
startup_timeout_sec = 20
tool_timeout_sec = 60
enabled = true
```

Now ask:

```text
Use the stripe-okf MCP server. Search for Checkout Sessions, read the most relevant concepts, inspect neighbors if needed, and explain the minimum backend flow with source URLs.
```

More setup details: [docs/mcp-clients.md](docs/mcp-clients.md).

Create a local activation packet when you want proof before or alongside client setup:

```bash
npx -y okfy-ai activate stripe --client codex --out okfy-activation
```

The packet contains an Inspector HTML file, a setup Markdown file, and a proof JSON transcript that follows the agent path: `bundle_summary`, `search_concepts`, `read_concept`, and `get_neighbors`.

Add `--task "checkout sessions"` when you want the proof search/read path to be scoped to the task you are about to give the agent.

If setup is not working, run:

```bash
npx -y okfy-ai doctor stripe --client codex
```

`doctor` checks the registered source, bundle validity, freshness, `npx` availability, generated command shape, MCP tool visibility, and JSON-RPC-clean stdout, then tells you the next repair command or config edit.

## Activation Packet

Use activation when you want the quickest shareable proof that a docs source is ready for an agent. Preview what your agent will know and get the setup/proof files in one folder:

```bash
npx -y okfy-ai activate stripe --client codex --out okfy-activation
```

`okfy activate` writes:

- `okfy-inspector.html`: static local Inspector with setup command and first prompt.
- `okfy-setup.md`: client-specific MCP config, launch command, first prompt, readiness, and file list.
- `okfy-proof.json`: deterministic proof of `bundle_summary`, `search_concepts`, `read_concept`, and `get_neighbors` over the selected docs.

Use `--task ""` to make `okfy-proof.json` prove a specific search/read path instead of the default first readable concept:

```bash
npx -y okfy-ai activate stripe --client codex --task "checkout sessions" --out okfy-activation
```

For a local OKF bundle path:

```bash
npx -y okfy-ai activate ./docs-okf --client codex --out okfy-activation
```

For a project stack workspace:

```bash
npx -y okfy-ai activate stripe clerk --client codex --out stack-activation
```

Activation does not write client config files by default. It gives you the exact config and prompt to review, paste, or send to a teammate.

## Preview The Inspector

Preview just the Inspector when you do not need the setup/proof packet:

```bash
npx -y okfy-ai map stripe --out okfy-inspector.html
```

`okfy map` writes a local static HTML Inspector you can open from disk. It summarizes readiness, validation warnings, source freshness, concept relationships, citation URLs, and the recommended MCP sequence: `bundle_summary`, `search_concepts`, `read_concept`, and `get_neighbors`.

For a local OKF bundle path:

```bash
npx -y okfy-ai map ./docs-okf --out okfy-inspector.html
```

For a project stack workspace:

```bash
npx -y okfy-ai map stripe clerk --out stack-inspector.html
```

Use `--json` when CI or tests need the same Inspector report model without writing HTML.

## Project Stack Workspaces

Most coding sessions need more than one docs source. Register each source locally, then serve a source-aware workspace through one MCP server:

```bash
npx -y okfy-ai add stripe https://docs.stripe.com/checkout --max-pages 100 --max-depth 4
npx -y okfy-ai add clerk https://clerk.com/docs --max-pages 100 --max-depth 4
npx -y okfy-ai doctor stripe clerk --client codex
npx -y okfy-ai serve stripe clerk --mcp --auto-refresh
```

Project-local docs work the same way when you manage the bundles yourself. Import each Markdown folder into its own OKF bundle, then serve those bundle paths together:

```bash
npx -y okfy-ai import ./docs/api --out ./okf/api-docs --source-name "API docs" --force
npx -y okfy-ai import ./docs/product --out ./okf/product-docs --source-name "Product docs" --force
npx -y okfy-ai validate ./okf/api-docs
npx -y okfy-ai validate ./okf/product-docs
npx -y okfy-ai serve ./okf/api-docs ./okf/product-docs --mcp
```

In local bundle workspaces, source filters use the bundle directory names, such as `api-docs` and `product-docs`.

Codex config for the registered-source workspace:

```toml
[mcp_servers.stripe_clerk_okf]
command = "npx"
args = ["-y", "okfy-ai", "serve", "stripe", "clerk", "--mcp", "--auto-refresh"]
startup_timeout_sec = 20
tool_timeout_sec = 60
enabled = true
```

Use `--all` only when you intentionally want every readable registered source in the current `OKFY_HOME`:

```bash
npx -y okfy-ai serve --all --mcp --auto-refresh
```

Workspace tool results preserve provenance. `search_concepts` includes `sourceName`, `seedUrl`, `ref`, `resource`, snippets, and scores. When you know the docs source, filter by source:

```json
{ "query": "checkout sessions", "source": "stripe", "limit": 5 }
```

If the same concept id exists in more than one source, read with source-aware disambiguation:

```json
{ "source": "stripe", "id": "guides/quickstart" }
```

Start workspace sessions with `bundle_summary`; it reports workspace totals plus per-source validation, freshness, refresh progress, and refresh errors.

## Keep Sources Fresh

Registered sources are the local-first workflow for third-party docs sites that change over time:

```bash
npx -y okfy-ai add stripe https://docs.stripe.com/checkout --max-pages 100 --max-depth 4
npx -y okfy-ai sources
npx -y okfy-ai check stripe
npx -y okfy-ai doctor stripe
npx -y okfy-ai update stripe
npx -y okfy-ai remove stripe --yes
npx -y okfy-ai serve stripe --mcp --auto-refresh
npx -y okfy-ai serve stripe clerk --mcp --auto-refresh
```

If you want registration plus client-specific setup artifacts, use `npx -y okfy-ai init stripe https://docs.stripe.com/checkout --client codex --max-pages 100 --max-depth 4`.

By default, okfy stores registered sources under `~/.okfy`. Set `OKFY_HOME` to use a different local cache for CI, tests, or per-project isolation:

```text
$OKFY_HOME/
  sources/
    stripe/
      source.json
      state.json
      bundle/
        index.md
        ...
```

`source.json` records the seed URL, crawl options, refresh policy, and bundle location. `state.json` records freshness, the last successful refresh, refresh failures, validation summary, and whether a refresh is in progress.

There is no OKFY cloud registry, account, hosted ranking, or cloud refresh worker. Refresh runs on your machine, using the stored source manifest and the same crawler safety defaults as `crawl`.

Freshness is age-based. A registered bundle is fresh when it exists, validates, and was successfully refreshed within its configured max age. The default mode is `stale-while-refresh`: if the bundle is stale, MCP search and read tools keep serving the current cached bundle while a background refresh runs. Use blocking mode when you want the server to refresh before answering tool calls:

```bash
npx -y okfy-ai serve stripe --mcp --auto-refresh --refresh-mode blocking
```

Use `--refresh-mode off` when MCP serving should never trigger network fetches; you can still run `npx -y okfy-ai update stripe` manually.

## Create A Bundle

The original crawl/import path still works for one-off snapshots and project-local bundles.

Docs website snapshot:

```bash
npx -y okfy-ai crawl https://docs.stripe.com/checkout --out ./stripe-checkout-okf --max-pages 25
npx -y okfy-ai validate ./stripe-checkout-okf
npx -y okfy-ai inspect ./stripe-checkout-okf
```

Local Markdown:

```bash
npx -y okfy-ai import ./docs --out ./docs-okf --source-name "Project docs" --force
npx -y okfy-ai validate ./docs-okf
```

Serve an existing bundle path when you already manage the bundle yourself:

```bash
npx -y okfy-ai serve ./docs-okf --mcp
```

Direct bundle paths do not use source auto-refresh. Do not run `serve --mcp` as a normal interactive terminal session. MCP clients start it as a subprocess and communicate over stdin/stdout.

## Optional CLI Install

You do not need global install for MCP configs. `npx -y okfy-ai ...` is usually better because the MCP client can launch okfy directly.

Install only if you want shorter local commands:

```bash
npm install -g okfy-ai
okfy demo
```

`okfy-ai` is the npm package name. `okfy` is the installed CLI command.

Package: [okfy-ai on npm](https://www.npmjs.com/package/okfy-ai)

Requires Node.js 20+.

Programmatic imports remain compatible with the existing `okfy-ai` root surface, including source-store and refresh helpers. New setup-only code can import the pure artifact helpers from `okfy-ai/setup`, such as `serveCommand`, `renderClientArtifacts`, and `expectedMcpTools`.

After installing, this MCP config is equivalent:

```json
{
  "mcpServers": {
    "stripe-okf": {
      "command": "okfy",
      "args": ["serve", "stripe", "--mcp", "--auto-refresh"]
    }
  }
}
```

## Demo

```bash
npx -y okfy-ai demo
```

The offline demo validates the bundled OKF fixture and prints a ready MCP config.

Expected shape:

```text
OKF bundle valid
Concepts: 6
Links: 10
Broken links: 0
MCP config:
```

## What You Get

```text
registered docs source or Markdown folder
  -> local OKF bundle: Markdown files + YAML frontmatter + links
  -> MCP server: bundle_summary, search_concepts, read_concept, get_neighbors, list_types, list_tags
  -> source-backed agent answers
```

| Output                   | Why it matters                                                      |
| ------------------------ | ------------------------------------------------------------------- |
| Plain Markdown concepts  | Humans can read, review, diff, and commit the knowledge.            |
| OKF frontmatter          | Agents get type, title, description, tags, source, and timestamp.   |
| Links and backlinks      | Agents can traverse related docs instead of reading everything.     |
| MCP stdio server         | Local clients can search and read the bundle with no hosted index.  |
| Deterministic validation | Malformed concept docs fail; broken links and missing indexes warn. |

## MCP Tools

| Tool              | Purpose                                                                                              |
| ----------------- | ---------------------------------------------------------------------------------------------------- |
| `bundle_summary`  | Show bundle or workspace stats, validation status, and source freshness when available.              |
| `search_concepts` | Search concept previews by query, optional source, type, or tags.                                    |
| `read_concept`    | Read one concept body, frontmatter, links, backlinks, and source; workspace reads can pass `source`. |
| `get_neighbors`   | Traverse outbound links and backlinks around a concept; workspace calls can pass `source`.           |
| `list_types`      | List concept types and counts, optionally filtered by workspace source.                              |
| `list_tags`       | List tags and counts, optionally filtered by workspace source.                                       |

The MCP server exposes read-only tools. Auto-refresh is server-side maintenance for registered sources, not an agent-callable write tool. `okfy serve --mcp` writes MCP JSON-RPC to stdout, so launch it through an MCP client rather than as a normal terminal command.

## Bundle Format

```md
---
type: "Guide"
title: "Import Local Markdown"
description: "Convert a local Markdown folder into an OKF bundle."
resource: "guides/import-local-markdown.md"
tags:
  - "okfy"
  - "import"
timestamp: "2026-06-14T00:00:00.000Z"
---

# Import Local Markdown

Run `okfy import  --out `.
```

Each non-reserved source page or file becomes one concept in v0.1. `index.md` and `log.md` are reserved OKF files, not concepts. Generated indexes are plain Markdown directory listings with no concept frontmatter, so concept counts, type counts, tag counts, search results, graph nodes, backlinks, and `read_concept` all exclude reserved files.

Validation follows Google OKF v0.1 conformance rules:

- Error: non-reserved `.md` concept missing parseable YAML frontmatter.
- Error: concept frontmatter missing non-empty string `type`.
- Error: present `index.md` or `log.md` does not follow reserved-file structure.
- Warning: broken internal link, missing folder index, or optional-field shape issue.

Unknown concept types, extra frontmatter keys, missing optional fields, broken links, and missing indexes do not make a bundle invalid.

## Why OKF

Most RAG systems hide knowledge inside an index. That can work, but it is hard to inspect, review, or ship with a repo.

OKF keeps knowledge as typed, linked Markdown files:

- humans can read it
- Git can diff it
- agents can search, read, and traverse it through MCP
- teams can keep source URLs and provenance visible

`llms.txt` is a useful entry point. OKF is a fuller bundle: one concept per file, typed frontmatter, internal links, backlinks, and progressive disclosure for agents.

## Security Defaults

- Crawls respect `robots.txt` by default.
- Crawls stay same-origin by default.
- Page count, depth, response size, and concurrency are capped.
- Private network URL literals and redirects to private targets are rejected by default for URL crawls.
- Preflight DNS-resolved private targets are rejected before fetch; f

…

## Source & license

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

- **Author:** [0dust](https://github.com/0dust)
- **Source:** [0dust/OKFy](https://github.com/0dust/OKFy)
- **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:** yes
- **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-0dust-okfy
- Seller: https://agentstack.voostack.com/s/0dust
- 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%.