OKF Server

A generic MCP server that browses, searches, and optionally edits any set of OKF (Open Knowledge Format) knowledge bundles. An AI agent can list bundles and folders, read individual concepts, run semantic or keyword search, and (with write mode enabled) create or delete concepts.

OKF organizes documentation into portable bundles of markdown concepts with YAML frontmatter and relative links. This server is content-agnostic: drop any OKF bundles into bundles/ and they are immediately browsable. It ships with two small example bundles to get started.

Requires Scriptling ≥ 0.18.0. Uses @mcp.tool decorators and app-bundle packaging.

Layout

okf-server/
  manifest.toml            app bundle manifest (serve = ["mcp"])
  tools/
    okf_tools.py           read tools as @mcp.tool decorated functions
    okf_write.py           write/delete tools (enabled with --allow-write)
  lib/
    okf_lib.py             shared library (bundle discovery, indexing, search helpers)
    okf_spec.py            loads the OKF spec from the package via scriptling.package
  okf/
    spec.md                the full OKF specification (shipped via additional_files)
  bundles/                 the OKF root (one folder per bundle)
    examples-docs/         example guides bundle
    examples-reference/    example reference bundle

Tools

Tool	Description
okf_get	Read a concept's raw markdown, or browse a folder (returns index.md if present, else synthesized listing per OKF section 6). Empty path lists all bundles including the virtual okf-spec bundle.
okf_search	Semantic search: rank concepts by relevance to a natural-language query.
okf_grep	Exact keyword/identifier search (OR, case-insensitive) across names, frontmatter, and bodies.
okf_facets	List the tags and types present in a bundle (or all bundles), with concept counts.
okf_concept_write	Write or create a concept. Validates frontmatter (type required for concepts, none for index.md). Auto-creates folders. Write mode only.
okf_concept_delete	Delete a concept. Cleans up empty parent directories and removes empty bundles. Write mode only.

Faceted filtering

Every concept carries a required frontmatter type and an optional list of tags. okf_facets lists the values present so an agent knows what it can filter by; okf_search and okf_grep both accept tags and types parameters that narrow the result set. Matching is OR within a facet (a concept qualifies if it carries any of the listed tags / any of the listed types) and AND across facets and the query.

On-demand indexes

okf_search ranks concepts using a per-bundle .vectors.json sidecar. okf_facets and the tags/types filters use .tags.json and .types.json sidecars. Each sidecar is built automatically on first use of the tool that needs it (and cached on disk for subsequent calls), so bundles work out of the box without a separate build step. The generated files are gitignored.

Running

# stdio MCP (default), bundles from ./bundles
scriptling --package .

# HTTP — MCP served at /mcp
scriptling --package . --server :8765

# Point at a different bundle root via --bundles flag
scriptling --package . -- --bundles /abs/path/to/my-bundles

# Or via env var
OKF_BUNDLES=/abs/path/to/my-bundles scriptling --package .

Bundle resolution order (checked at each tool call):

1. --bundles <path> flag (passed after -- on the CLI, available via sys.argv)
2. OKF_BUNDLES env var
3. ./bundles (default, relative to working directory)

Write Mode

By default the server is read-only — the okf_concept_write and okf_concept_delete tools are not registered. Enable write mode with --allow-write on the CLI or OKF_ALLOW_WRITE=true in the environment:

# Via CLI flag (after --)
scriptling --package . -- --allow-write

# Via env var
OKF_ALLOW_WRITE=true scriptling --package .

# Combine with --bundles
scriptling --package . -- --bundles /data --allow-write

When write mode is enabled, two additional tools appear:

• okf_concept_write — writes a concept .md file, auto-creating parent folders. Validates that concepts have YAML frontmatter with a required type field (OKF section 4.1/9); index.md files are exempt (no frontmatter per section 6). The tool description tells the LLM to read okf-spec/spec.md for the full formatting rules. Indexes are invalidated so search and facets regenerate on next use.
• okf_concept_delete — removes a concept file, walks up deleting empty parent directories to the bundle root, and removes the bundle itself if it becomes empty. Invalidates indexes the same way.

OKF Specification

The OKF specification is always available as a virtual bundle named okf-spec. Browse it with okf_get("okf-spec") or read it directly with okf_get("okf-spec/spec.md"). The write tool's error messages point agents here when frontmatter validation fails.

Adding your own bundles

A bundle is just a folder of markdown concepts under bundles/. The OKF spec does not define bundle-level metadata — the directory name IS the bundle identity:

bundles/my-docs/
  index.md          optional directory listing (OKF section 6, no frontmatter)
  install.md        concept (frontmatter with type + title + description)
  usage.md

The server discovers bundles by scanning bundles/, so no registry or manifest is needed.

MCP client configuration

{
  "mcpServers": {
    "okf": {
      "command": "scriptling",
      "args": ["--package", "/abs/path/to/okf-server"],
      "env": { "OKF_BUNDLES": "/abs/path/to/bundles" }
    }
  }
}

See also

• OKF specification