okf-mcp

One MCP server that gives agents read access to any number of OKF bundles, wherever they live. The server speaks MCP on one side and a small connector interface on the other; a connector knows how to reach one kind of source — a git remote, a local directory — and nothing about what the tools do with the content.

The full design rationale is in docs/okf-mcp.md.

What is OKF?

The Open Knowledge Format (v0.2) represents knowledge as a directory of markdown files with YAML frontmatter — a bundle, distributed as a git repository, a tarball, or a subdirectory of a larger repo. Every non-reserved .md file is a concept: one subject, written whole, with its provenance in frontmatter. The only always-required field is type; everything else is convention, and consumers must tolerate what they don't recognize.

---
type: Concept
title: Buyer's premium
description: The percentage added to the hammer price.
generated:                        # who last changed the content, and when (§5.2)
  by: process:ingest-pipeline     # actors: process:<id>, human:<id>, <tool>/<version> (§7)
  at: 2026-07-26T22:56:22Z
verified:                         # independent of generated — who confirmed it (§5.2)
  - by: human:ryan
    at: 2026-08-01T00:00:00Z
sources:                          # what the concept derives from (§5.1)
  - id: fee-schedule
    resource: https://example.com/fee-schedule.pdf
status: stable                    # draft | stable | deprecated (§5.4)
stale_after: 2027-01-01           # trust decays on a date, not silently (§5.5)
---

A percentage added to the hammer price…

What makes the format worth building on:

• Trust is derived, not asserted. A concept verified by a human: actor is human-reviewed; by machines only, machine-confirmed; otherwise unverified (§5.3). Nobody writes a trust tier into a file — consumers compute it, which is what concept_status does.
• Two reserved filenames. index.md is a directory's table of contents (§8) and log.md its date-grouped history, newest first (§9). Both are optional; consumers may synthesize an index on the fly.
• Producers stay honest, consumers stay lenient. §11 tells producers what a conformant bundle looks like, and simultaneously forbids consumers from rejecting bundles over missing options, unknown keys, or broken links. Enforcement is a producer-side act — which is why validation here is a separate tool rather than a gate in the read path.

okf-mcp sits on the consumer side of that contract, with validate_bundle as the opt-in producer-side check.

Add to Claude Desktop (with a config form)

Build the desktop bundle and open it:

npm install && npm run pack:mcpb
open build/okf-mcp.mcpb

Claude Desktop shows an install dialog with a configuration form: pick local bundle folders with a native directory picker, paste git clone URLs (optionally #branch), and for private repositories either enter a git token (stored in the OS keychain, never in a config file) or pick an SSH deploy key file for git@… URLs. Settings → Extensions → OKF Connector reopens the form any time.

Shipping a preconfigured installer

Pass defaults at pack time and the form comes pre-filled — the recipient double-clicks, at most drops in a credential, and is done:

npm run pack:mcpb -- --name okf-dash --display-name "DASH Wiki" \
  --git https://github.com/DashAuction/dash-wiki.git#main

That writes build/okf-dash.mcpb with the repository already in the form. For a public repository the install is literally double-click → Install. For a private one the recipient adds either a fine-grained PAT scoped to that repository (HTTPS URL) or a deploy key file (SSH URL). Give each client's installer its own --name — Claude Desktop identifies extensions by name, so distinct names can coexist.

To distribute with a read-only deploy key — a two-double-click install:

ssh-keygen -t ed25519 -f deploy-key -N ""       # add deploy-key.pub to the repo, write access off
npm run pack:mcpb -- --name okf-dash --display-name "DASH Wiki" \
  --git git@github.com:org/wiki.git#main
npm run key:installer -- deploy-key             # → "build/Install OKF Deploy Key.command"

Send both build outputs. Recipients double-click the .command first (it writes the key to ~/.config/okf-mcp/deploy-key with the permissions ssh requires — on macOS, right-click → Open the first time, since it's unsigned), then double-click the .mcpb and hit Install. The server finds a key at that standard location automatically, so the form needs nothing; its SSH-key picker still overrides it when set. The server also preflights the key before any sync and fails with the exact fix (chmod 600) if it was placed by hand with open permissions.

One SSH key serves all SSH bundles in an install; deploy keys are per-repository on GitHub, so multiple private repositories need the PAT route instead.

Automating per-bundle installers

A bundle repository can publish its own preconfigured installer at a stable URL — releases/download/installer/<name>.mcpb — and have it rebuilt automatically whenever okf-mcp releases. The bundle repo carries only its parameters:

# .github/workflows/publish-installer.yml
on:
  workflow_dispatch:
  repository_dispatch:
    types: [okf-mcp-release]
jobs:
  installer:
    permissions: { contents: write }
    uses: ganttastic/okf-mcp/.github/workflows/build-installer.yml@main
    with:
      installer-name: okf-dash
      display-name: DASH Wiki
      git-url: git@github.com:DashAuction/dash-wiki.git#main

The build logic lives here in build-installer.yml, so a fix lands in every bundle's next build instead of drifting per template clone. The release workflow's fan-out dispatches okf-mcp-release to every repo in the INSTALLER_REPOS repository variable, using the INSTALLER_DISPATCH_TOKEN secret (a PAT with contents write on those repos — GITHUB_TOKEN cannot dispatch cross-repository); without both set, the fan-out skips cleanly.

Add to Codex

codex mcp add okf -- node /path/to/okf-mcp/dist/server.js --local ~/Repositories/dash-wiki

or in ~/.codex/config.toml:

[mcp_servers.okf]
command = "node"
args = ["/path/to/okf-mcp/dist/server.js", "--git", "https://github.com/DashAuction/dash-wiki.git#main"]
env = { OKF_GIT_TOKEN = "…" }

(Build first with npm install && npm run build. The same shape works for Claude Code: claude mcp add okf -- node /path/to/okf-mcp/dist/server.js --local <dir>.)

Configuring sources

Three equivalent channels, merged in this order:

1. sources.json — full control, including per-bundle maxStalenessMinutes and custom names. Copy sources.example.json; point at it with --sources <path> or OKF_MCP_SOURCES. A sources.json in the working directory is picked up automatically. auth.env names the environment variable holding a credential; config never holds one.
2. CLI flags — --local <dir> [<dir>…] and --git <url[#branch]> [<url>…]. Bundle names derive from the directory or repository basename.
3. Env vars — OKF_MCP_LOCAL_BUNDLES / OKF_MCP_GIT_BUNDLES (comma-separated).

Git bundles use OKF_GIT_TOKEN when it is set, and clone under OKF_MCP_CACHE_DIR (default: ~/.cache/okf-mcp).

Tools

Tool	Purpose
list_bundles()	the source registry, with each bundle's last-sync time
list_directories(bundle)	category directories
read_index(bundle, directory?)	the designed discovery surface — prefer before search
read_concept(bundle, path)	one concept, verbatim bytes
concept_status(bundle, path)	derived OKF signals: trust tier, status, staleness
validate_bundle(bundle)	producer-side §11 conformance report
search_concepts(bundle, query)	full-text search across a bundle's markdown

When the registry holds exactly one bundle, the bundle parameter is optional and defaults to it — so a dedicated single-corpus instance never repeats its own name. A server fronting several bundles requires it, and the error names the candidates.

Each bundle's AGENTS.md is exposed as the MCP resource okf://{bundle}/agents-guide.

Read-only, deliberately: bundles are written by their own pipelines and corrected by humans in git.

OKF v0.2 support

Section references are to the spec.

Consuming (always lenient)

• Unknown frontmatter keys and type values pass through untouched; reads are verbatim bytes.
• concept_status derives trust tiers per §5.3 (unverified / machine-confirmed / human-reviewed, keyed off human: actors), normalizes a bare verified mapping to a one-element list (§11), applies the status default and stale_after staleness (§5.4–5.5), and falls back to the v0.1 timestamp when generated is absent (§13).
• Missing index.md files never reject a bundle: indexes are synthesized on the fly in the §8 shape, and a bundle needs no root index or okf_version declaration to be served (§11–§12).

Validating (opt-in enforcement)

The read path tolerates everything §11 permits it to — which means a hand-added file with broken frontmatter, or an index that grew frontmatter it shouldn't have, sails through silently. validate_bundle is the producer-side counterweight:

• Errors are §11 violations: unparseable or missing frontmatter, an empty type, index files carrying frontmatter beyond the root's okf_version (§8), log files with frontmatter or non-## YYYY-MM-DD headings (§9).
• Warnings are SHOULD-level slips in the §5 families: a sources entry without its required resource, generated or verified without by, a status outside draft | stable | deprecated, a malformed stale_after.
• Machinery directories named in okf.json are skipped; dot-directories always are.

The same checks run from the command line — okf-mcp --validate <dir> prints the report and exits 1 on errors — so a bundle repository can gate every push on conformance with a two-step workflow:

# .github/workflows/validate-bundle.yml
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npx --yes https://github.com/ganttastic/okf-mcp/releases/latest/download/okf-mcp.tgz --validate .

The tarball is a prebuilt release artifact — no auth, no clone, no build step. Pin a version by replacing latest/download with download/vX.Y.Z. Releases are cut by pushing a version tag (git tag v0.1.1 && git push --tags); each release also carries the Claude Desktop installer (okf-mcp.mcpb).

dash-wiki runs exactly this. The validator lives here rather than in the bundle repositories because those are templates: template clones fork and drift by design, and a checker baked into a template stays broken in every clone already stamped from it.

Development

npm test           # connector contract + git sync policy + manifest/registry tests
npm run typecheck

Every connector is tested against the same fixture bundle in test/fixtures/, so "all connectors behave identically" is asserted rather than hoped.