| type | reference | |||
|---|---|---|---|---|
| title | Features | |||
| description | Overview of Open Knowledge Catalog features including multi-format support, semantic search, and CI/CD integration | |||
| tags |
|
|||
| owner | felix | |||
| status | draft |
OKC provides a comprehensive set of tools for browsing, parsing, searching, and reasoning over OKF repositories.
| Command | Purpose |
|---|---|
okc agent-config |
List, preview, or safely write generated MCP client configuration |
okc scan |
Index a knowledge repository |
okc browse |
Browse the directory hierarchy |
okc get |
Retrieve a document with metadata, headings, and/or body |
okc section |
Extract a specific Markdown section |
okc search |
Full-text search with BM25 ranking and filters |
okc metadata |
Structured metadata queries with filtering and projection |
okc links |
Outgoing links from a document |
okc backlinks |
Documents referencing a concept |
okc traverse |
Explore related concepts via graph edges |
okc validate |
Multi-category repository validation |
okc stats |
Repository statistics |
okc serve |
Start MCP server (stdio for local clients, HTTP for remote/shared use) |
okc watch |
File system watching with incremental updates |
When running as an MCP server, these tools are exposed to AI agents:
| Tool | Description |
|---|---|
scan |
Scan/re-scan root directories and index documents |
browse |
Inspect one area of the OKF hierarchy |
get_document |
Retrieve one concept with opt-in metadata, identity fields, links, and backlinks |
get_context_pack |
Assemble bounded primary, linked, and backlink evidence around one document |
get_section |
Extract a specific Markdown section without the full document; bounded responses expose deterministic continuation metadata |
search |
Full-text search with optional path/type/tag filters |
query_metadata |
Exact structured filtering on front-matter fields |
get_links |
Outgoing links from a document (optional relation filter) |
get_backlinks |
Documents referencing a concept (optional relation filter) |
traverse_graph |
Explore related concepts via graph edges (optional relations) |
get_stats |
Repository statistics (file counts, link counts, etc.) |
validate |
Report structural problems (broken links, malformed YAML, missing index files) |
get_changes |
Read durable, paginated create/update/metadata/delete events for incremental sync |
All successful MCP tool responses advertise an outputSchema and return matching structuredContent. A JSON text
content block remains available for compatibility with clients that have not adopted structured MCP output.
get_changes is a pull-only MCP feed for agents that have already indexed a catalog and need to refresh local state
without rescanning every document. Events are ordered by a durable event ID and include root, path, type, content
hash when applicable, and modification time. Pass the returned opaque next_cursor unchanged to continue; filters for
change type, root, path prefix, and document type are evaluated after that stable position. Deleted documents are
represented by retained tombstones. An expired or invalid cursor returns structured recovery data with the earliest
retained cursor instead of silently skipping history.
Search results include optional heading lists for each matching document, providing a quick outline view without fetching the full document.
CLI options:
okc search "query" --max-headings 3 --heading-depth 2MCP tool params:
{
"query": "query",
"max_headings": 3,
"heading_depth": 2
}Configurable via TOML or environment variables:
[search]
max_headings = 3 # default: 1
heading_depth = 2 # default: 1 (h1 only)OKC_SEARCH_MAX_HEADINGS=5
OKC_SEARCH_HEADING_DEPTH=3Behavior:
- Only headings at or below
heading_depthare included (1=h1, 2=h1+h2, etc.) max_headingscaps the total across all allowed depths (budget interaction)- Headings inside fenced code blocks are excluded
- Matching headings are ranked first; when none match, the earliest allowed headings provide document orientation
- Returns empty list for documents with no body or headings
traverse follows both directions when no relation filter is supplied. Use
links_to to follow only outgoing document links or linked_from to follow
only backlinks; the returned edge relation always identifies the direction
that was traversed. Unknown relation names match no edges.
okc traverse metrics/monthly-revenue.md --relations links_to
okc traverse metrics/monthly-revenue.md --relations linked_fromokc search and the MCP search tool treat input as plain text by default.
Each Unicode-whitespace-delimited term is compiled as an FTS5 literal, so
ordinary documentation queries such as HTTP/SSE, config.json, top-k, and
serve --transport do not require FTS5 escaping.
Use raw FTS5 syntax only when it is intentional:
okc search "title:revenue OR body:recognition" --query-mode fts5{
"query": "title:revenue OR body:recognition",
"query_mode": "fts5"
}The supported modes are plain (the default) and fts5. Invalid advanced
syntax is reported as an input error; it does not cause a server panic.
Run the MCP server in two modes:
# stdio (default) — local MCP clients launch the child process automatically
okc serve --transport stdio
# HTTP — for web clients, remote access, or shared hosting
okc serve --transport http --host 0.0.0.0 --port 3001OpenCode and similar local clients own the stdio process lifetime automatically. Use HTTP only when you need a manually hosted remote server.
Keep your index up to date automatically:
okc watch # Watch configured roots
okc watch --root ./knowledge --debounce 300 --reconcile 600Features: debounced event batching, editor temp-file filtering (.swp, ~, .tmp), gitignore-aware exclusion, periodic full reconciliation, incremental index updates.
Content-hash based change detection (Blake3 sampling) enables fast re-scans — unchanged files are skipped entirely.
Each document is a Markdown file with YAML front matter:
---
type: Metric
title: Monthly Revenue
description: Recognized recurring revenue for the month
tags:
- finance
- executive
owner: Finance Analytics
status: published
---
# Definition
Monthly Revenue represents...
# Calculation
Revenue is recognized when.../
├── metrics/
│ ├── index.md
│ ├── monthly-revenue.md
│ └── customer-count.md
└── datasets/
├── index.md
└── customer-orders.md
index.mdfiles provide directory summaries (optional, configurable)- Relative links between documents are resolved and validated
- Custom front-matter fields are preserved as generic metadata
The typed_links front-matter extension adds relationship semantics
(depends-on, imports, extends, …) over the canonical Markdown
graph. Typed edges are additive rows in the same link store — they never
override Markdown links. See
docs/references/okc-typed-links.md for
the format, vocabulary, and resolution rules.
---
typed_links:
version: 1
links:
- target: /metrics/monthly-revenue.md
relation: depends-on
---Filter by relation where links are read. On the CLI that is
okc traverse; the MCP tools expose relation/relations inputs on
get_links, get_backlinks, and traverse_graph:
okc traverse metrics/monthly-revenue.md --relations depends-on,imports# MCP: get_links / get_backlinks accept { path, relation }
{"path": "metrics/monthly-revenue.md", "relation": "depends-on"}Unfiltered calls return all edges, so existing consumers see no change.
MCP tools expose the same filters via optional relation/relations
inputs.
okc validate checks structural problems — broken links (including
missing typed-link targets), malformed YAML, circular references,
duplicate content, missing index files, and mixed untyped/typed edges to
the same target (typed_link_conflict). Supports --json for
machine-parseable output:
It and the other result-producing CLI commands support --json for
machine-parseable output. Successful JSON is written to stdout; errors are
written to stderr:
okc validate --jsonConfigurable limits prevent excessive output:
max_response_chars: 500,000 charactersmax_graph_depth: 5max_graph_nodes: 100
Enriched get_document responses include truncated: true when the requested
body limit or aggregate max_response_chars limit is hit.