@contextwise/okflow-ai

Turn docs into agent-readable Open Knowledge Format v0.2-conformant bundles, then serve them to Claude, Codex, Cursor, or any MCP client. OKFlow also builds fact-first engineering documentation for local repositories.

Install and Verify

Requires Node.js 24 LTS or newer. Install the published CLI with npm install --global @contextwise/okflow-ai, or use npx -y @contextwise/okflow-ai without a global install. From a checkout, verify the package with pnpm install --frozen-lockfile, pnpm build, pnpm test:release, and npm pack --dry-run.

The package includes docs/Markdown bundles, six-tool read-only MCP, repository engineering memory, taxonomy/evidence/snippets, deep validation, the local workbench, safe PR/GitHub paths, daemon jobs, hosted registry adapters, schemas, examples, and the official agent skill. Write paths, daemon execution, and hosted registry use are disabled by default and require independent configuration gates.

Project quick start:

okflow project init .
okflow project doctor . --json
okflow project index . --provider all --json
okflow project questions . --execute --json
okflow project enrich . --json
okflow project generate . --run <authoring-run-id> --json
okflow project validate . --deep --json
okflow workbench . --no-open

Use --json for automation, --dry-run for previews, --provider/--family to narrow work, --deep/--online-providers for validation, --confirm and --allow-provider-write for explicit mutations, and --write-mode proposal|apply for workbench editing. Project parameters live in .okflow/config.json schema v2; credentials belong only in environment variables.

Project Engineering Memory

Create fact-first, reviewable engineering documentation for a local repository:

okflow project init .
okflow project status . --json
okflow project doctor . --json
okflow project index . --json
okflow project questions . --execute --json
okflow project enrich . --json
okflow project generate . --run <authoring-run-id> --json
okflow project drift . --base main --head HEAD --json
okflow project sync . --base main --head HEAD --dry-run --json
okflow validate ./okf --json

Replace okflow with npx -y @contextwise/okflow-ai when running without a global install. OKFlow stores bounded provider evidence and sanitized receipts under .okflow/, stages managed-content conflicts, and keeps generated memory under okf/ readable through the existing six-tool MCP server.

See Repository Engineering Memory, Provider Adapters, Migration from OKFy, and the offline project-memory-small example.

Use With Agents

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

npx -y @contextwise/okflow-ai init stripe https://docs.stripe.com/checkout --client generic --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 @contextwise/okflow-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 exposing freshness metadata through bundle_summary.

Add the source-backed server to an MCP client:

{
  "mcpServers": {
    "stripe-okf": {
      "command": "npx",
      "args": ["-y", "@contextwise/okflow-ai", "serve", "stripe", "--mcp", "--auto-refresh"]
    }
  }
}

Ask your agent:

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.

Client Setup

Claude Code:

npx -y @contextwise/okflow-ai init stripe https://docs.stripe.com/checkout --client claude-code
claude mcp add --transport stdio stripe-okf -- npx -y @contextwise/okflow-ai serve stripe --mcp --auto-refresh

Codex:

[mcp_servers.stripe_okf]
command = "npx"
args = ["-y", "@contextwise/okflow-ai", "serve", "stripe", "--mcp", "--auto-refresh"]
startup_timeout_sec = 20
tool_timeout_sec = 60
enabled = true

Claude Desktop, Cursor, and other mcpServers clients can use the JSON config above. More setup: https://github.com/sekmet/OKFlow/blob/main/docs/mcp-clients.md

The official OKFlow agent skill at skills/okflow/SKILL.md ships with the package and gives skill-aware agents the OKFlow setup workflow, MCP tool order, workspace source filters, and safety rules.

If setup is not working, run:

npx -y @contextwise/okflow-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

Create a local proof packet before or alongside MCP setup. Preview what your agent will know and get setup/proof files in one folder:

npx -y @contextwise/okflow-ai activate stripe --client codex --out okflow-activation

The packet contains okflow-inspector.html, okflow-setup.md, and okflow-proof.json. It shows the exact MCP command/config, first prompt, readiness, and a deterministic proof path through bundle_summary, search_concepts, read_concept, and get_neighbors.

Add --task "checkout sessions" when you want the proof search/read path to match the task you plan to ask the agent:

npx -y @contextwise/okflow-ai activate stripe --client codex --task "checkout sessions" --out okflow-activation

Use a local OKF bundle path when you already manage the bundle yourself:

npx -y @contextwise/okflow-ai activate ./docs-okf --client codex --out okflow-activation

Activation does not write client config files by default.

Preview The Inspector

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

npx -y @contextwise/okflow-ai map stripe --out okflow-inspector.html

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

Use npx -y @contextwise/okflow-ai map ./docs-okf --out okflow-inspector.html for a local OKF bundle path, or npx -y @contextwise/okflow-ai map stripe clerk --out stack-inspector.html for a source-aware workspace.

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

Multi-Source Workspaces

Register several docs sources and expose them through one source-aware MCP server:

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

For project-local docs, import each Markdown folder into its own OKF bundle and serve the bundle paths together:

npx -y @contextwise/okflow-ai import ./docs/api --out ./okf/api-docs --source-name "API docs" --force
npx -y @contextwise/okflow-ai import ./docs/product --out ./okf/product-docs --source-name "Product docs" --force
npx -y @contextwise/okflow-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:

[mcp_servers.stripe_clerk_okf]
command = "npx"
args = ["-y", "@contextwise/okflow-ai", "serve", "stripe", "clerk", "--mcp", "--auto-refresh"]
startup_timeout_sec = 20
tool_timeout_sec = 60
enabled = true

Workspace bundle_summary reports totals plus per-source validation, freshness, refresh progress, and refresh errors. Search and list tools accept a source filter, and duplicate concept ids can be read with { "source": "stripe", "id": "guides/quickstart" }.

Keep Sources Fresh

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

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

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

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

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:

npx -y @contextwise/okflow-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 @contextwise/okflow-ai update stripe manually.

Create Bundles

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

Docs website snapshot:

npx -y @contextwise/okflow-ai crawl https://docs.stripe.com/checkout --out ./stripe-checkout-okf --max-pages 25
npx -y @contextwise/okflow-ai validate ./stripe-checkout-okf
npx -y @contextwise/okflow-ai inspect ./stripe-checkout-okf

Local Markdown:

npx -y @contextwise/okflow-ai import ./docs --out ./docs-okf --source-name "Project docs" --force
npx -y @contextwise/okflow-ai validate ./docs-okf

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

npx -y @contextwise/okflow-ai serve ./docs-okf --mcp

Direct bundle paths, including local bundle workspaces, do not use source auto-refresh.

Optional CLI Install

You do not need global install for MCP configs. npx -y @contextwise/okflow-ai ... is usually better because the MCP client can launch okflow directly.

Install only if you want shorter local commands:

npm install -g @contextwise/okflow-ai
okflow demo

@contextwise/okflow-ai is the npm package name. okflow is the installed CLI command.

Requires Node.js 24 LTS or newer. Node 25 is EOL; Node 26 is tested as a forward-compatibility lane.

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

After installing, this MCP config is equivalent:

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

Demo

npx -y @contextwise/okflow-ai demo

No-Install MCP Config

{
  "mcpServers": {
    "stripe-okf": {
      "command": "npx",
      "args": ["-y", "@contextwise/okflow-ai", "serve", "stripe", "--mcp", "--auto-refresh"]
    }
  }
}

CLI Commands

okflow init <name> <url>
okflow doctor <name> [more-names...]
okflow add <name> <url>
okflow sources
okflow check <name-or-bundle>
okflow update <name>
okflow remove <name> --yes
okflow crawl <url> --out <dir>
okflow import <path> --out <dir>
okflow validate <bundle>
okflow inspect <bundle>
okflow activate <name-or-bundle> [more-source-names...] --client codex --out okflow-activation
okflow map <name-or-bundle> [more-source-names...] --out okflow-inspector.html
okflow serve <name-or-bundle> [more-source-names...] --mcp
okflow demo

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. | | get_neighbors | Traverse outbound links and backlinks around a concept. | | list_types | List concept types and counts, optionally filtered by workspace source. | | list_tags | List tags and counts, optionally filtered by workspace source. |

What okflow Generates

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

Each non-reserved source page or Markdown file becomes one OKF concept in v0.1. index.md and log.md are reserved files, not concepts, and generated indexes are plain Markdown. Concept counts, search, graph links, types, tags, and read_concept exclude reserved files.

Validation errors are limited to OKF conformance: malformed or missing concept frontmatter, missing type, or invalid reserved-file structure. Broken internal links and missing indexes are warnings.

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; fetch-time DNS is not IP-pinned.
• --force refuses unsafe output directories such as ., /, the home dir, repo root, input path, input parent, and symlink output dirs unless an explicit dangerous override is provided.
• HTML and Markdown are treated as text. Scripts are not executed.
• MCP tools are read-only; refresh is server-side maintenance, not an agent-callable write tool.

Links

• GitHub: https://github.com/sekmet/OKFlow
• MCP client setup: https://github.com/sekmet/OKFlow/blob/main/docs/mcp-clients.md
• OKF: https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf

License

MIT.