Skip to main content
Glama
lorsabyan

okf-mcp-server

by lorsabyan
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesConcept id: path without .md, e.g. "metrics/revenue"
bundle_pathYesPath to the OKF bundle directory (a folder of .md files). Absolute paths are safest.
include_bodyNoInclude the markdown body
response_formatNo'markdown' for reading, 'json' for machine processingmarkdown

TDQS

A4.4/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint and idempotentHint annotations, the description adds meaningful behavioral context: trust and stale_since are advisory signals, not access control; for Attested Computation the caller must not author or rewrite the computation, only supply parameter values; unknown IDs return near-miss suggestions. These details disclose important behavioral nuances.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is organized into clear sections (Args, Returns, Trust note, Computation note, Examples, Error Handling) and front-loaded with the core purpose. It is lengthy, but the detailed return schema and caveats are necessary given the absence of an output schema. No redundant fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (trust signals, computation type, various fields) and no output schema, the description is exceptionally complete. It documents the full return structure, error behavior, usage examples, and critical trust/computation caveats. Everything an agent needs to invoke and interpret the tool is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All four tool parameters are already well-documented in the schema (100% coverage), so the description's parameter list adds little new semantic value. The note about 'declared parameters ONLY' refers to the computation's parameters, not the tool's own parameters, so it doesn't elevate the score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with 'Read a single concept in full' and enumerates the content (frontmatter, trust and lifecycle signals, provenance, body, links). This specific verb+resource clearly distinguishes it from siblings like okf_list_concepts (listing) and okf_search (searching).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides concrete use cases ('How is revenue defined?' -> id='metrics/revenue' and 'need a concept's sources to cite it'), which clearly indicate when to use the tool. It does not explicitly name sibling tools or state when not to use it, but the examples and 'single concept' framing imply appropriate usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

ParametersJSON Schema
NameRequiredDescriptionDefault
as_ofNoEvaluate staleness as of this date instead of today
bundle_pathYesPath to the OKF bundle directory
response_formatNo'markdown' for reading, 'json' for machine processingmarkdown

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds substantial behavioral nuance beyond that: it distinguishes between 'stale' (spec-derived) and 'aging' (heuristic), warns against conflating them, and includes error handling for invalid as_of. This provides context that annotations alone cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded with a clear summary, followed by a necessary disambiguation of stale vs. aging, then Args, Returns, Examples, and Error Handling. Every paragraph serves a purpose; the length is justified by the tool's semantic complexity, and no information is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description fully documents the return JSON structure. It also covers error handling and includes usage examples. Combined with annotations for safety and a straightforward input schema, the description leaves no critical gaps for an AI agent to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description's Args section restates the schema parameters and adds clarity (e.g., as_of evaluates staleness against a date 'instead of today', response_format default is 'markdown'). While largely redundant with the schema, the narrative context reinforces the semantics, justifying a slightly higher score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Analyze a bundle for documentation-health problems' and enumerates specific issue types (broken links, missing descriptions, untyped concepts, staleness, unverified/deprecated content, orphans). This is a specific verb+resource that distinguishes it from sibling tools like okf_open_bundle or okf_get_concept.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit 'Use when' examples ('Is anything in this catalog out of date?', 'What still needs human review?', 'auditing before relying on a bundle') that give clear context for when to invoke the tool. However, it does not mention when not to use it or name alternatives like okf_validate, so it lacks the explicit exclusions that would earn a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

ParametersJSON Schema
NameRequiredDescriptionDefault
tagNoExact tag to filter by
typeNoExact OKF type to filter by
limitNoMaximum results
trustNoTrust tier derived from `verified` (§5.3)
offsetNoResults to skip, for pagination
statusNoLifecycle status (§5.4)
bundle_pathYesPath to the OKF bundle directory (a folder of .md files). Absolute paths are safest.
response_formatNo'markdown' for reading, 'json' for machine processingmarkdown

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses that it returns summaries only, is safe for large bundles, and explains error behavior for unmatched filters. This adds meaningful context without contradicting the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with distinct sections for overview, parameters, return format, examples, and error handling. Every section earns its place, and the key purpose is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite lacking an output schema, the description provides a full inline return structure, covers all parameters, includes examples, and addresses error handling. This makes it complete for a complex listing tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds value by providing examples for the type parameter (e.g., 'Metric') and clarifying the 'response_format' default, though it mostly repeats schema information.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists concepts with optional filters by type, tag, or lifecycle status. It also distinguishes itself from okf_get_concept by noting it returns summaries without bodies, making it suitable for large bundles.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly advises using okf_get_concept to read a concept in full, and provides concrete 'Use when' examples for type, trust, and status filters. This gives clear guidance on when to choose this tool over alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

ParametersJSON Schema
NameRequiredDescriptionDefault
bundle_pathYesPath to the OKF bundle directory (a folder of .md files). Absolute paths are safest.
response_formatNo'markdown' for reading, 'json' for machine processingmarkdown

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context beyond those hints: it explains the return shape (JSON structure with counts and health summary), error behavior for missing directories or non-concept folders, and the default response_format. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections: intro, bundle definition, Args, Returns, Examples, and Error Handling. The 'Start here' opener is immediately useful, and each section adds necessary context without fluff. The length is justified by the tool's role as an entry point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of an output schema, the description fully compensates by including a detailed return structure. It covers usage context, error cases, and relationships to sibling tools. The bundle definition provides essential domain knowledge for an AI agent, making the description complete for this tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds marginal value by including an Args section that restates defaults and types, plus concrete examples like bundle_path='./knowledge' and an explanation that response_format 'json' is for machine processing. This is helpful but not essential beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Open') and resource ('OKF bundle') and clearly states it describes the bundle's contents with 'Start here.' It distinguishes from siblings by noting when not to use it (if you already know the concept id, use okf_get_concept).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides 'Use when' examples, including concrete bundle_path values and a comparison to okf_list_concepts, plus a 'Don't use when' exclusion with a named alternative. This gives clear guidance on when to choose this tool over siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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)

ParametersJSON Schema
NameRequiredDescriptionDefault
bundle_pathNoBundle to drop; omit for all

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations (idempotent, non-destructive), the description discloses the caching-per-path behavior, the effect on subsequent calls, and the return value structure ({ cleared: number }). It also states that the action is a cache drop, aligning with readOnlyHint=false while adding context about what actually happens.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with a one-sentence summary, followed by rationale, args, returns, and examples. Every section adds value and the description is appropriately concise for the tool's simplicity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter tool with no output schema, the description covers when to use, what happens (cache drop, next read), the optional parameter meaning, and the return shape. No gaps in context are evident.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers the single parameter bundle_path with 100% coverage and a clear description ('Bundle to drop; omit for all'). The description repeats essentially the same meaning ('bundle to drop; omit to drop every cached bundle') without adding significant new detail, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Drop the cached copy of a bundle') and resource (bundle cache), distinguishing it from sibling tools like okf_open_bundle or okf_get_concept. It explains the purpose with a concrete verb and outcome (re-read from disk), not a tautology.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says to call after editing files, and provides both 'Use when' and 'Don't use when' examples. This gives clear conditions for use and implicitly names the alternative (do nothing when only reading), which satisfies the requirement for usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

ParametersJSON Schema
NameRequiredDescriptionDefault
bundle_pathYesPath to the OKF bundle directory
response_formatNo'markdown' for reading, 'json' for machine processingmarkdown

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate a safe, read-only idempotent operation. The description adds substantial behavioral context: the distinction between errors and warnings, the tolerance of warnings per spec §11, the conformance rules themselves, and error handling for missing paths. This goes far beyond the annotations and schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (intro, errors/warnings, args, returns, examples, error handling). Every part earns its place; no fluff or redundancy. It's longer than average, but the complexity of the tool justifies it.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema, the description fully documents the return object with field names, types, and meanings. It also covers error handling for missing paths. Given the tool's complexity (conformance logic, multiple response formats), this is a complete and self-contained description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that bundle_path is a directory containing the bundle and that response_format is 'markdown' for reading vs 'json' for machine processing, reinforcing and expanding on the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states exactly what the tool does: 'Check a bundle against the OKF v0.2 specification.' It clearly identifies the resource (bundle) and verb (check/validate), and distinguishes itself from sibling okf_health_report by focusing on conformance rather than quality signals.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit usage guidance with 'Use when' and 'Don't use when' sections. Directly names an alternative tool (okf_health_report) for non-conformance use cases, making it easy for an agent to decide when to select this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 7 tool updatesv0.1.1
    • First observedokf_get_concept
    • First observedokf_health_report
    • First observedokf_list_concepts
    • First observedokf_open_bundle
    • First observedokf_reload_bundle
    • First observedokf_search
    • First observedokf_validate
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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

ActivityMaintained
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers

  • okfy

    0dust
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI agents to search, read, and traverse documentation bundles in Open Knowledge Format via MCP tools.
    108 npm
    71
    MIT

  • okf-mcp

    ganttastic
    A
    license
    Not graded
    quality
    A
    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