okf-mcp-server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@okf-mcp-server What is the health report for bundle /tmp/okf/bundles/acme?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 | 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 doneTransport 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 |
| What is in this bundle — concept count, types, groups, health summary. Start here. |
| Browse, filtered by |
| Read one concept in full: frontmatter, provenance, computation contract, body, links. |
| Full-text search across titles, ids, types, tags, descriptions, and bodies. |
| Broken links, staleness, unverified and deprecated content, orphans. |
| Conformance against OKF v0.2 (spec §11). |
| 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) —
deprecatedcontent stays readable but is flagged.Provenance (§5.1) — the
sourcesa 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 ad30107Then 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 --helpInspect it interactively:
npx @modelcontextprotocol/inspector node dist/index.jsEvaluation
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 toolsokf_get_conceptRead one OKF conceptARead-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 healthARead-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_afterdate (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 bundleARead-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 bundleARead-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 diskAIdempotent
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_searchSearch an OKF bundleARead-onlyIdempotent
Full-text search over a bundle's concepts — titles, ids, types, tags, descriptions, and bodies.
Args:
bundle_path (string): directory containing the bundle
query (string): search text, 1-200 characters
limit (number): 1-50, default 10
response_format ('markdown' | 'json'): default 'markdown'
Returns: { "query": string, "count": number, "results": [{ "id": string, "title": string, "type": string, "description": string, "tags": string[], "status": ..., "trust": ..., "updated_at": string, "stale_since": string }] }
Examples:
Use when: "Where is churn defined?" -> query="churn"
Use when: you do not know the concept id
Don't use when: you have the exact id (use okf_get_concept, it is cheaper)
Error Handling:
No matches returns the available types and tags to redirect the search
Inputs: query (required), bundle_path (required), limit, response_format.
okf_validateValidate an OKF bundle for conformanceARead-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
Scored across 7 tools
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.
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.
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.
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
Related MCP Connectors
Discover, search, invoke, and rate A2A (Agent-to-Agent) protocol agents.
Read-only AgentiScript concept search, catalog, authenticity, license, and approved asset discovery.
Search and share cited agent findings. Public reads; authenticated writes.
Public read-only discovery of agent, model, training, task, and verification opportunities.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to search, read, and traverse documentation bundles in Open Knowledge Format via MCP tools.771 npm74MIT
- AlicenseNot gradedqualityDmaintenanceProvides tools for AI agents to navigate and query OKF knowledge bundles through overview, read, search, and list operations.721 PyPIApache 2.0
- AlicenseNot gradedqualityCmaintenanceMCP 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
- AlicenseNot gradedqualityCmaintenanceEnables AI coding agents to search and retrieve cited line-level context from versioned knowledge bundles, as well as list workspaces and publish or pull immutable Markdown bundles.Apache 2.0