okf-mcp

English · 简体中文

Local runtime for Open Knowledge Format v0.2: validate bundles, search concepts, expose knowledge over MCP, and build database Bundles from dbexplain for agent NL2SQL.

Fork of mfdaves/okf-mcp (MIT). Enterprise rollout extensions: hosted Streamable HTTP MCP, immutable knowledge generations, okf dbexplain, and bundled Agent Skills.

What you get

No database server, vector DB, or embeddings required for the runtime itself.

Related MCP server: 50 First Tapes MCP Server

Prerequisites

Check:

node --version          # v22+
command -v dbexplain && dbexplain --version

Quick start (database knowledge and querying)

The CLI and Skills are independent capabilities. Install the ones needed for a task:

okf CLI / MCP       → validate, index, and serve knowledge
okf-dbexplain       → generate or refresh physical facts
okf-bundle-business → add or correct Business knowledge
okf-nl2sql          → query real data and return traceable results

1. Install okf-mcp

git clone https://github.com/doctormacky/okf-mcp.git
cd okf-mcp
npm ci
npm link                    # optional: register `okf` on PATH
okf --version

Extended install, update, and rollback guide (Chinese): docs/OKF_CLI_SOURCE_INSTALL_UPDATE_ZH.md.

2. Sync physical layer (Skill or CLI)

Prepare dbexplain (releases), then:

$okf-dbexplain
Inspect prod-main and sync to /data/okf/my-database

Or manually:

okf dbexplain check --include prod-main
okf dbexplain sync \
  --include prod-main \
  --bundle-root /data/okf/my-database \
  --generated-at 2026-08-26T09:00:00Z \
  --dry-run
# review plan → apply with --expect-plan <digest>
okf dbexplain validate --bundle-root /data/okf/my-database

3. Add business semantics

$okf-bundle-business
Bundle: /data/okf/my-database
Task: add buyer aliases to Customers and project explicit order-state codes
from the column comment. Inventory and propose before writing.

After writes:

okf dbexplain overlay-index --bundle-root /data/okf/my-database
okf dbexplain validate --bundle-root /data/okf/my-database

Skill details: docs/SKILLS.md.

4. Connect an MCP client

See MCP modes below. Restart or reload after Bundle changes.

Built-in Agent Skills

Skills live under .agents/skills/. Register them in your agent host (Cursor, Codex, etc.).

Also shipped: okf-v02-migration — only when migrating legacy v0.1 catalogs to v0.2.

Each Skill may be installed alone or in any combination and does not assume the others exist. Composition is a user or Agent Host decision.

Full reference: docs/SKILLS.md · docs/SKILLS_ZH.md

MCP modes

stdio and Streamable HTTP expose the same tools when started with the same flags. For database NL2SQL, the default read-only profile is enough.

Full tool catalog: docs/MCP_TOOLS.md · docs/MCP_TOOLS_ZH.md

Tools (read-only — all three modes above)

Resources: okf-documents template — read any indexed Markdown concept by okf:// URI.

NL2SQL workflow: $okf-nl2sql calls search_concepts → get_concept → get_neighbors, then assembles SQL from business knowledge, physical bindings, and Saved Queries. It falls back to bounded dbexplain discovery only when needed.

Optional write/authoring tools (okf_propose_*, okf_apply_changes, load_remote_bundle) are available on local stdio/HTTP only with extra flags; hosted omits them. Knowledge publishing uses okf knowledge CLI, not MCP writes.

stdio (local agent)

{
  "mcpServers": {
    "okf": {
      "command": "node",
      "args": [
        "/absolute/path/to/okf-mcp/bin/okf-mcp.js",
        "--root",
        "/absolute/path/to/your/bundle",
        "mcp"
      ]
    }
  }
}

Or after npm link:

{
  "mcpServers": {
    "okf": {
      "command": "okf",
      "args": ["--root", "/absolute/path/to/your/bundle", "mcp"]
    }
  }
}

Default with no subcommand also starts stdio MCP when a bundle root is configured.

hosted (Streamable HTTP + rollout)

Authenticated enterprise profile: MCP at /mcp, rollout API at /v1/rollout/*.

export OKF_READ_TOKEN="<read-token>"
export OKF_ROLLOUT_TOKEN="<rollout-token>"
okf hosted --root /path/to/catalog --host 127.0.0.1 --port 8765
# → http://127.0.0.1:8765/mcp

Use okf-knowledge-publisher Skill to download → dry-run → submit snapshots. Other agents consume published knowledge through this MCP URL with Authorization: Bearer $OKF_READ_TOKEN.

Standalone unauthenticated HTTP (dev only):

okf --root /path/to/bundle mcp --http --host 127.0.0.1 --port 8765

Prefer hosted for anything beyond localhost.

Common CLI checks

okf --root /path/to/bundle validate
okf --root /path/to/bundle search "order state"
okf --root /path/to/bundle concept business/datasets/my-dataset
okf dbexplain inspect --include prod-main
okf dbexplain validate --bundle-root /path/to/database-bundle

Documentation

Development

npm ci
npm test
npm run self:validate

License

MIT — see LICENSE. Upstream mfdaves/okf-mcp contributors remain credited.