Skip to content

Latest commit

 

History

History
269 lines (208 loc) · 8.95 KB

features.md

File metadata and controls

269 lines (208 loc) · 8.95 KB
type reference
title Features
description Overview of Open Knowledge Catalog features including multi-format support, semantic search, and CI/CD integration
tags
features
overview
reference
owner felix
status draft

Features

OKC provides a comprehensive set of tools for browsing, parsing, searching, and reasoning over OKF repositories.

CLI Commands

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

MCP Tools

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.

Durable Incremental Sync

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 with Structured Headings

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 2

MCP 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=3

Behavior:

  • Only headings at or below heading_depth are included (1=h1, 2=h1+h2, etc.)
  • max_headings caps 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

Directional Graph Traversal

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_from

Search Query Modes

okc 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.

MCP Server Transport

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 3001

OpenCode and similar local clients own the stdio process lifetime automatically. Use HTTP only when you need a manually hosted remote server.

Filesystem Watcher

Keep your index up to date automatically:

okc watch                    # Watch configured roots
okc watch --root ./knowledge --debounce 300 --reconcile 600

Features: debounced event batching, editor temp-file filtering (.swp, ~, .tmp), gitignore-aware exclusion, periodic full reconciliation, incremental index updates.

Incremental Scanning

Content-hash based change detection (Blake3 sampling) enables fast re-scans — unchanged files are skipped entirely.

Supported OKF Format

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...

Repository Structure

/
├── metrics/
│   ├── index.md
│   ├── monthly-revenue.md
│   └── customer-count.md
└── datasets/
    ├── index.md
    └── customer-orders.md
  • index.md files provide directory summaries (optional, configurable)
  • Relative links between documents are resolved and validated
  • Custom front-matter fields are preserved as generic metadata

Typed Links

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.

Repository Validation

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 --json

Response Size Limits

Configurable limits prevent excessive output:

  • max_response_chars: 500,000 characters
  • max_graph_depth: 5
  • max_graph_nodes: 100

Enriched get_document responses include truncated: true when the requested body limit or aggregate max_response_chars limit is hit.