Skip to main content
Glama
okf-mcp-server

okf-mcp-server

by lorsabyan

okf-mcp-server

An MCP server that exposes Open Knowledge Format (OKF) bundles to agents — browse, search, read concepts, and audit trust and freshness.

An OKF bundle is a directory of markdown files with YAML frontmatter, each describing one concept: a dataset, table, metric, API, playbook, policy, or attested computation. This server lets an agent use one without being taught the format.

Built on @lorsabyan/okf-core.

Is this the one you want?

If you use Claude Code or Codex, probably not — use the OKF skill instead.

Your agent

Use

Why

Cursor, Windsurf, Zed, other MCP clients

this server

No skill support, so the format arrives as tools.

An agent with no filesystem access

this server

The skill needs to read files and run scripts; this works over a protocol.

Claude Code, Codex

the skill

Skills load automatically and carry the format itself, so the agent reads bundles with the file tools it already has.

That last row is measured rather than assumed. With the skill installed, a real Claude Code session answered a bundle question using the skill plus Read and Bash, making zero calls to this server. The skill triggers on any mention of OKF and prescribes a complete procedure, while MCP tools cost a ToolSearch round-trip before the first call. In that environment this server can only add latency, never capability — so installing both is worse than installing either.

Where there is no skill, the calculus inverts: this is the only thing that teaches the agent the format.

Related MCP server: okft

Install

In your MCP client's config:

{
  "mcpServers": {
    "okf": { "command": "npx", "args": ["-y", "okf-mcp-server"] }
  }
}

For Claude Code — worth repeating that the skill is the better fit there, so this is mainly for testing the server itself:

claude mcp add okf -- npx -y okf-mcp-server
claude mcp remove okf            # when you are done

Transport is stdio — bundles are read from the local filesystem, so this is a local integration with nothing to authenticate.

Tools

Every tool takes bundle_path, so no tool has to be called before another. There is no "active bundle" to set up and no ordering to get wrong.

Tool

Purpose

okf_open_bundle

What is in this bundle — concept count, types, groups, health summary. Start here.

okf_list_concepts

Browse, filtered by type, tag, status, or trust. Paginated.

okf_get_concept

Read one concept in full: frontmatter, provenance, computation contract, body, links.

okf_search

Full-text search across titles, ids, types, tags, descriptions, and bodies.

okf_health_report

Broken links, staleness, unverified and deprecated content, orphans.

okf_validate

Conformance against OKF v0.2 (spec §11).

okf_reload_bundle

Drop the cache after editing files on disk.

All are read-only. okf_reload_bundle only clears an in-process cache; nothing here writes.

Each returns both human-readable markdown and structuredContent, selectable with response_format.

What it surfaces that a plain file read does not

OKF v0.2 records whether a definition can be trusted, and this server puts those signals in front of the agent rather than leaving them buried in frontmatter:

  • Trust tier (§5.3) — derived from verified: unverified, machine-confirmed, or human-reviewed.

  • Staleness (§5.5) — whether a concept is past its author-chosen stale_after. Reported separately from aging (not updated in a year), because they are different claims: a concept can be two years old and deliberately current, or a week old and expired.

  • Lifecycle status (§5.4) — deprecated content stays readable but is flagged.

  • Provenance (§5.1) — the sources a concept derives from, with author and last-modified.

  • Attested Computations (§10) — the sanctioned runtime, parameters, receipt fields, executor, and attester. The tool description states the rule the type exists to enforce: a caller may supply values for declared parameters and must never rewrite the computation.

okf_health_report accepts as_of so staleness questions have reproducible answers.

Try it

Against any OKF bundle:

git clone https://github.com/GoogleCloudPlatform/open-knowledge-format /tmp/okf
git -C /tmp/okf checkout ad30107

Then ask an agent something like "Open the bundle at /tmp/okf/bundles/acme_retail — which metric is deprecated, and what replaced it?"

Development

npm install
npm run build
npm test            # builds, then runs node --test over dist
npm start           # speaks MCP on stdin/stdout
node dist/index.js --help

Inspect it interactively:

npx @modelcontextprotocol/inspector node dist/index.js

Evaluation

evaluation.xml holds ten questions over the upstream Acme Retail reference bundle, each needing several tool calls. Every answer was verified by driving this server over stdio, and the questions that involve staleness name an explicit as_of so the clock cannot change the answer.

License

Apache-2.0.

Available Tools

7 tools
okf_get_conceptRead one OKF conceptA
Read-onlyIdempotent

Read a single concept in full: its frontmatter, trust and lifecycle signals, provenance, body, and links.

Args:

  • bundle_path (string): directory containing the bundle

  • id (string): concept id — the file path without .md, e.g. "metrics/revenue"

  • include_body (boolean): default true; set false for metadata only

  • response_format ('markdown' | 'json'): default 'markdown'

Returns: { "id": string, "title": string, "type": string, "description": string, "tags": string[], "resource": string, "status": ..., "trust": ..., "verified_by": string[], "verified_at": string, "updated_at": string, "stale_since": string, "generated": { "by": string, "at": string }, "sources": [{ "id": string, "resource": string, "title": string, "author": string, "lastModified": string, "usageCount": number }], "computation": { // present only for type "Attested Computation" "runtime": string, "parameters": [{ "name": string, "type": string, "required": boolean }], "path": string, "executor": { "resource": string, "receipt": string[] }, "attester": { "resource": string } }, "links_to": string[], "cited_by": string[], "body": string // omitted when include_body is false }

Trust and freshness are worth checking before relying on a definition: "trust" is derived from verified (§5.3) and "stale_since" from stale_after (§5.5). They are advisory signals, not access control.

For an Attested Computation, the caller may supply values for the declared parameters ONLY, and must never author or rewrite the computation itself — that boundary is the point of the type (§10).

Examples:

  • Use when: "How is revenue defined?" -> id="metrics/revenue"

  • Use when: you need a concept's sources to cite it

Error Handling:

  • An unknown id returns near-miss suggestions from the bundle

Inputs: id (required), bundle_path (required), include_body, response_format.

okf_health_reportReport an OKF bundle's healthA
Read-onlyIdempotent

Analyze a bundle for documentation-health problems: broken links, missing descriptions, untyped concepts, staleness, unverified and deprecated content, and orphans.

Two distinct notions of "old" are reported separately, and conflating them is the mistake this guards against:

  • "stale" means past the author's own stale_after date (spec §5.5) — an explicit expiry.

  • "aging" means not updated in over a year — a heuristic, not part of the spec. A concept can be two years old and deliberately current, or a week old and expired.

Args:

  • bundle_path (string): directory containing the bundle

  • as_of (string, optional): ISO date (YYYY-MM-DD) to evaluate staleness against, instead of today

  • response_format ('markdown' | 'json'): default 'markdown'

Returns: { "as_of": string, "broken_links": [{ "from": string, "target": string }], "missing_descriptions": string[], "untyped": string[], "stale": [{ "id": string, "stale_since": string }], "aging": [{ "id": string, "updated_at": string }], "undated": string[], "unverified": string[], "deprecated": string[], "orphans": string[] }

Examples:

  • Use when: "Is anything in this catalog out of date?"

  • Use when: "What still needs human review?" -> read "unverified"

  • Use when: auditing before relying on a bundle

Error Handling:

  • An invalid as_of returns a message naming the expected YYYY-MM-DD format

Inputs: bundle_path (required), as_of, response_format.

okf_list_conceptsList concepts in an OKF bundleA
Read-onlyIdempotent

List concepts, optionally filtered by type, tag, or lifecycle status.

Returns summaries without bodies, so it is safe to call on a large bundle. Use okf_get_concept to read one in full.

Args:

  • bundle_path (string): directory containing the bundle

  • type (string, optional): exact OKF type, e.g. "Metric", "BigQuery Table", "Attested Computation"

  • tag (string, optional): exact tag

  • status ('draft' | 'stable' | 'deprecated', optional): lifecycle filter (spec §5.4)

  • trust ('unverified' | 'machine-confirmed' | 'human-reviewed', optional): trust tier (spec §5.3)

  • limit (number): 1-200, default 50

  • offset (number): default 0

  • response_format ('markdown' | 'json'): default 'markdown'

Returns: { "total": number, "count": number, "offset": number, "has_more": boolean, "next_offset": number, // present only when has_more "concepts": [{ "id": string, "title": string, "type": string, "description": string, "tags": string[], "resource": string, "status": "draft"|"stable"|"deprecated", "trust": "unverified"|"machine-confirmed"|"human-reviewed", "verified_by": string[], "verified_at": string, "updated_at": string, "stale_since": string }] }

Examples:

  • Use when: "What metrics are defined?" -> type="Metric"

  • Use when: "Which definitions has nobody verified?" -> trust="unverified"

  • Use when: "Show me anything deprecated" -> status="deprecated"

Error Handling:

  • An unmatched type or tag returns an empty list plus the values that do exist

Inputs: bundle_path (required), tag, type, limit, +4 more.

okf_open_bundleOpen an OKF bundleA
Read-onlyIdempotent

Open an Open Knowledge Format bundle and describe what is in it. Start here.

An OKF bundle is a directory of markdown files with YAML frontmatter, each describing one concept — a dataset, table, metric, API, playbook, policy, or attested computation.

Args:

  • bundle_path (string): directory containing the bundle

  • response_format ('markdown' | 'json'): default 'markdown'

Returns: { "name": string, // bundle directory name "concept_count": number, "types": { [type: string]: number }, // concept count per OKF type "groups": [{ "group": string, "count": number }], // top-level directories "health_summary": { "broken_links": number, "missing_descriptions": number, "untyped": number, "stale": number, "aging": number, "undated": number, "unverified": number, "deprecated": number, "orphans": number } }

Examples:

  • Use when: "What's in the bundle at ./knowledge?" -> bundle_path="./knowledge"

  • Use when: you need the type names before filtering okf_list_concepts

  • Don't use when: you already know the concept id (use okf_get_concept)

Error Handling:

  • Returns a message naming the path if the directory does not exist

  • Returns a message explaining what a bundle is if the directory holds no concept docs

Inputs: bundle_path (required), response_format.

okf_reload_bundleReload a bundle from diskA
Idempotent

Drop the cached copy of a bundle so the next call re-reads it from disk.

Bundles are cached per path for speed. Call this after editing files, otherwise subsequent tools keep answering from the version loaded earlier.

Args:

  • bundle_path (string, optional): bundle to drop; omit to drop every cached bundle

Returns: { "cleared": number } // how many cached bundles were dropped

Examples:

  • Use when: you have just written to a bundle and want fresh results

  • Don't use when: you have only been reading (the cache is already correct)

Inputs: bundle_path.

okf_validateValidate an OKF bundle for conformanceA
Read-onlyIdempotent

Check a bundle against the OKF v0.2 specification.

Errors are the three conformance rules of spec §11: every non-reserved .md file has a parseable YAML frontmatter block, every block has a non-empty type, and reserved files (index.md, log.md) follow their structure.

Warnings are soft guidance the spec says consumers MUST tolerate — broken links, missing optional fields, unknown types. A bundle with warnings is still conformant, and §11 explicitly forbids rejecting a bundle for them.

Args:

  • bundle_path (string): directory containing the bundle

  • response_format ('markdown' | 'json'): default 'markdown'

Returns: { "conformant": boolean, // true when there are zero errors "checked_version": string, // OKF version validated against "declared_version": string, // okf_version from the root index.md, when declared (§12) "concept_count": number, "error_count": number, "warning_count": number, "errors": string[], "warnings": string[] }

Examples:

  • Use when: "Is this bundle valid OKF?"

  • Use when: authoring a bundle and checking work before publishing

  • Don't use when: you want quality signals rather than conformance (use okf_health_report)

Error Handling:

  • A missing or non-directory path returns a message naming it

Inputs: bundle_path (required), response_format.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.7/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a distinct operation: open gives an overview, list/get/search retrieve concepts, health/validate analyze quality and conformance, and reload manages the cache. The 'use when' examples clearly differentiate overlapping pairings like search vs. list and health vs. open.

    Naming Consistency5/5

    All tools share the consistent okf_ prefix and use clear action-oriented names (open_bundle, list_concepts, get_concept, search, health_report, validate, reload_bundle). While health_report is a noun compound, the pattern is otherwise verb_noun, and the prefix makes prediction trivial.

    Tool Count5/5

    Seven tools is a well-scoped size for an OKF bundle server. Each tool earns its place, covering discovery, retrieval, search, health analysis, validation, and cache management without unnecessary bloat or fat.

    Completeness5/5

    The tool surface fully covers the read/analyze lifecycle for OKF bundles: entry point, listing, detail retrieval, search, quality health, spec conformance, and cache refresh. No obvious gaps exist for the stated purpose, and editing is intentionally left outside the server.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to search, read, and traverse documentation bundles in Open Knowledge Format via MCP tools.
      771 npm
      74
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server giving agents read access to OKF bundles from local directories or git remotes, with tools to list bundles, browse indices, read concepts, and search markdown content.
      Apache 2.0