{
  "markdown": "# okf-mcp\n\n`okf-mcp` is a local-first consumer, validator, graph index, CLI, and MCP server for [Open Knowledge Format v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md).\n\nIt consumes an OKF bundle directory of Markdown files with YAML frontmatter. An optional workspace mode can federate several bundles. Concepts are exposed through CLI commands and MCP resources and tools for validation, structured search, graph navigation, provenance inspection, and proposal-based authoring.\n\nThe core intentionally has no database, embeddings, build step, or hosted-service dependency. It uses `js-yaml` for safe YAML, CommonMark for Markdown structure, MiniSearch for in-memory BM25+ text retrieval, and the official Model Context Protocol TypeScript SDK v2 for stdio MCP. Local root mode makes no network calls. Optional remote loading fetches public Markdown concepts and only their explicitly referenced inert assets from GitHub. Nothing in the v0.2 computation support executes code or attests a receipt.\n\n## OKF v0.2 Support And Extensions\n\nOKF v0.2 intentionally specifies a portable file format, not a serving or query runtime. `okf-mcp` keeps that boundary explicit:\n\n| Area | Official OKF v0.2 | okf-mcp behavior |\n| --- | --- | --- |\n| Bundle and identity | A directory tree of Markdown files; a Concept ID is its bundle-relative path without `.md` | `--root` maps directly to one bundle; `okf://` is an optional workspace locator, not the portable Concept ID |\n| Concept metadata | Required `type`; recommended `title`, `description`, `resource`, and `tags`; unknown keys are allowed | Preserves extension fields and unknown types while reporting normative conformance separately from workspace policy |\n| Provenance and lifecycle | `sources`, `usage_window`, `generated`, `verified`, `status`, and `stale_after` | Normalizes these fields for search, provenance traversal, trust tiers, and deterministic freshness checks |\n| References | Markdown links and path-valued `resource`, `sources[].resource`, `computation`, `executor.resource`, and `attester.resource` fields | Builds graph edges and bounded inert asset snapshots without executing or implicitly fetching referenced code |\n| Attested Computation | Defines contract fields and an informative consumer flow while deferring runtime wire protocols and attester packaging | Statically inspects contracts and digests, checks declared parameter and receipt field names, and never executes or claims attestation |\n| v0.1 compatibility | Allows `timestamp` fallback when the whole `generated` mapping is absent and `# Citations` fallback when the `sources` key is absent | Consumes both forms and adds review-only migration checks and proposals |\n\nThe following are okf-mcp extensions rather than requirements of the format:\n\n- CLI, MCP, and HTTP interfaces; in-memory search and graph views\n- optional multi-bundle `okf.project.yaml` workspaces and typed `relations`\n- compatibility `id`, `aliases`, and `okf://` locators\n- proposal-backed authoring with explicit acceptance\n- bounded GitHub remote loading and explicitly mapped pinned Git sources\n- generator plugins and stricter opt-in project policies such as `strictLinks`\n\n## Install And Run\n\nNode 22 or newer is required.\n\nInstall from the GitHub release:\n\n```bash\ngit clone --branch v0.8.0 https://github.com/mfdaves/okf-mcp.git\ncd okf-mcp\nnpm ci\nnode bin/okf-mcp.js --root ./path/to/okf validate\n```\n\nPin the published version for reproducible use:\n\n```bash\nnpx -y @mfdaves/okf-mcp@0.8.0 --version\nnpx -y @mfdaves/okf-mcp@0.8.0 --root ./path/to/okf validate\n```\n\nFor a persistent installation:\n\n```bash\nnpm install --global @mfdaves/okf-mcp@0.8.0\n\nokf --version\nokf --root ./path/to/okf validate\nokf-mcp --root ./path/to/okf mcp\n```\n\nTo work from the current source branch:\n\n```bash\ngit clone https://github.com/mfdaves/okf-mcp.git\ncd okf-mcp\nnpm ci\nnpm test\nnode bin/okf-mcp.js --version\n```\n\n`--root` accepts one local OKF bundle directory and is the recommended okf-mcp interface for a single bundle. The portable identity of each concept is its extensionless path inside that root.\n\n`--bundle` accepts either a path or `id=path`. Multiple flags remain supported for compatibility. `--project` and its `bundles:` list are an optional okf-mcp federation/authoring extension, not part of OKF v0.2.\n\n`--remote-bundle` accepts `id=https://github.com/<owner>/<repo>/tree/<ref>/<path>`. It fetches public Markdown first, then only bundle-local files explicitly named by standard v0.2 resource fields. Remote content remains read-only and inert.\n\n`--inspect` prints a compact graph summary and exits. Without `--inspect` and without an explicit command, the process starts a stdio MCP server.\n\nThe package exposes both `okf` and `okf-mcp` binaries when installed. Without an explicit source, the CLI first discovers the nearest root `index.md` declaring `okf_version`; nearest-project discovery remains a compatibility fallback.\n\nCLI exit statuses are `0` for success, `1` for validation or operational failure, and `2` for invalid usage. Unknown options are rejected.\n\n## Included OKF Reference\n\nThis repository publishes a self-describing OKF bundle for the product, its runtime boundaries, interfaces, authoring workflows, and safety policy. Its portable entry Concept ID is `overview/okf-mcp`; `okf://okf-mcp/overview/okf-mcp` remains the workspace/MCP resource locator.\n\nValidate and query the bundled reference from a checkout or installed package:\n\n```bash\nokf --root okf/bundles/okf-mcp validate\nokf --root okf/bundles/okf-mcp search \"proposal\"\nokf --root okf/bundles/okf-mcp concept overview/okf-mcp\n```\n\nLoad the reference bundle directly from this release:\n\n```bash\nokf --remote-bundle okf-mcp=https://github.com/mfdaves/okf-mcp/tree/v0.8.0/okf/bundles/okf-mcp --inspect\n```\n\nThe `@mfdaves/okf-mcp` npm package includes both `okf.project.yaml` and the\ncomplete reference bundle.\n\n## Optional Multi-Bundle Project Config\n\nUse `okf.project.yaml` only when one process must federate multiple roots, configure generators, or enforce a project-wide relation vocabulary:\n\n```yaml\nproject: Example\nstrictLinks: false\nbundles:\n  - id: app\n    root: okf/bundles/app\n    include: [\"**/*.md\"]\n    exclude: [\"archive/**\"]\n  - id: data\n    root: okf/bundles/data\nrelationTypes:\n  - deployed_by\nremoteBundles:\n  - id: shared\n    url: https://github.com/example/okf-atlas/tree/main/bundles/shared\n    include: [\"public/**\"]\n    exclude: [\"drafts/**\"]\nplugins:\n  - name: docs\n    type: filesystem\n    root: docs\n    output: okf/bundles/app/generated/docs\n    bundle: app\n```\n\nRun project commands:\n\n```bash\nokf --project okf.project.yaml validate\nokf --project okf.project.yaml search \"orders\"\nokf --project okf.project.yaml graph mermaid\nokf --project okf.project.yaml generate\nokf --project okf.project.yaml mcp\nokf --project okf.project.yaml mcp --authoring\nokf --project okf.project.yaml mcp --allow-remote-tool\nOKF_WRITE_TOKEN=change-me okf --project okf.project.yaml serve\nokf --remote-bundle shared=https://github.com/example/okf-atlas/tree/main/bundles/shared --inspect\n```\n\nCommands:\n\n- `mcp`\n- `validate`\n- `graph [json|dot|mermaid]`\n- `search <query>`\n- `concept <concept-id-or-locator>`\n- `neighbors <concept-id-or-locator>`\n- `paths <from> <to>`\n- `provenance <uri>`\n- `edge-kinds`\n- `computation inspect|prepare|check-receipt`\n- `asset <okf-asset-uri>`\n- `source <concept-id-or-locator> <source-id>`\n- `migrate check|preview`\n- `generate`\n- `serve`\n\n`serve` options:\n\n- `--host <host>`: bind host, default `127.0.0.1`\n- `--port <port>`: bind port, default `8765`\n- `--write-token <token>`: bearer token for write endpoints; defaults to `OKF_WRITE_TOKEN`\n- `--proposal-root <path>`: proposal JSON directory; defaults to `.okf-proposals` under the selected local root or project\n\n## MCP Client Config\n\nThe npm-based examples below use the current published release. A source checkout can invoke its executable `bin/okf-mcp.js` with the same arguments.\n\nExample client configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"okf\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@mfdaves/okf-mcp@0.8.0\",\n        \"--root\",\n        \"/absolute/path/to/okf\",\n        \"mcp\"\n      ]\n    }\n  }\n}\n```\n\nProject config mode, with read-only project helpers but without proposal mutations:\n\n```json\n{\n  \"mcpServers\": {\n    \"okf\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@mfdaves/okf-mcp@0.8.0\",\n        \"--project\",\n        \"/absolute/path/to/repo/okf.project.yaml\",\n        \"mcp\"\n      ]\n    }\n  }\n}\n```\n\nAdd `--authoring` to enable proposal creation, acceptance, and rejection. For a smaller direct-write surface, add `--write --actor <actor>` to expose read-only `okf_validate_changes` and validated-batch `okf_apply_changes`; add `--git-commit` to commit each successful batch when the catalog is in a clean Git worktree. Add `--allow-remote-tool` to let MCP clients load arbitrary supported public remote bundles at runtime. Configured remote bundles remain readable without that runtime-loading flag.\n\nThe stdio server uses `@modelcontextprotocol/server` v2. It serves the modern\n`2026-07-28` MCP revision and the SDK's compatibility path for 2025-era\nclients, including `2025-11-25`. The SDK owns protocol negotiation, framing,\nresource dispatch, tool dispatch, and advertised-schema validation.\n\nExpected failures from a known tool, such as a missing concept, a read-only\nbundle, a failed remote fetch, invalid arguments, or a proposal conflict, are\nreturned as MCP tool results with `isError: true`. Calls to tools that are not\nenabled are rejected by SDK dispatch. Unexpected implementation errors are\nmasked instead of exposing internal details.\n\n## MCP Registry Metadata\n\n`server.json` describes the npm package as the stdio server\n`io.github.mfdaves/okf-mcp`. Registry-aware clients should prompt for an\nabsolute OKF root path, pass it through `--root`, and append the fixed `mcp`\ncommand.\n\n## Concept Identity And Extensions\n\nConcept IDs are their bundle-relative Markdown paths with `.md` removed. This extensionless path is the portable OKF identity. okf-mcp also exposes a workspace-scoped compatibility locator:\n\n```text\nokf://<bundle-id>/<extensionless-concept-id>\n```\n\nThe former `.md` URI and a valid custom `id` remain compatibility lookup aliases. A bare Concept ID resolves only when unique across loaded bundles. For standalone aggregate catalogs, a URI-shaped portable path such as `okf://services/queue.md` also resolves when `services/queue` is globally unique and `services` is not a loaded bundle id. Exact canonical URIs always win; a known-bundle miss or ambiguous portable path stays unresolved. Reserved `index.md` and `log.md` resources retain their filenames because they are not concepts.\n\nThe `id`, `aliases`, and typed `relations` fields below are `okf-mcp` extensions. The standard v0.2 identity remains path-derived:\n\n```markdown\n---\nid: okf://app/routes/order-status\ntype: API Route\ntitle: Order Status Route\ndescription: Serves order status state.\naliases: [order-status]\ntags: [api, orders]\nrelations:\n  - type: consumes\n    target: okf://data/tables/order_status\n  - type: configured_by\n    target: repo://src/routes/order-status.js\n---\n\n# Order Status Route\n```\n\nNew content should use normal relative or bundle-root Markdown paths for internal links and extension relation targets. Existing `okf://` targets remain supported; non-OKF schemes such as `repo://` remain opaque compatibility references.\n\n### Pinned Git Sources\n\nCode knowledge may live outside the code repository without recording a machine-specific path. Point a standard `sources` entry at a `Git Repository` concept and add the okf-mcp `git` extension below:\n\n```yaml\nsources:\n  - id: implementation\n    resource: /repositories/application.md\n    git:\n      revision: 0123456789abcdef0123456789abcdef01234567\n      path: src/application.js\n      lines: { from: 10, to: 30 }\n```\n\nMap the repository concept only in the local process configuration:\n\n```bash\nokf --root /path/to/catalog \\\n  --repo repositories/application=/work/application \\\n  source architecture/application implementation\n```\n\n`read_git_source` and the `source` CLI command read the pinned blob from the mapped Git object database. They never read the dirty worktree or fetch. Missing mappings and unpinned revisions remain visible but unavailable. Repository mappings may point to normal checkouts, bare repositories, or mounted paths; credentials and local paths stay outside the OKF bundle.\n\n## Tools\n\n- `list_bundles`\n- `list_concepts`\n- `get_concept`\n- `search_concepts`\n- `list_types`\n- `list_tags`\n- `list_relation_types`\n- `list_edge_kinds`\n- `get_provenance`\n- `inspect_attested_computation`\n- `read_bundle_asset`\n- `read_git_source`\n- `prepare_attested_computation`\n- `check_computation_receipt`\n- `check_v02_migration`\n- `load_remote_bundle`\n- `list_remote_bundles`\n- `okf_validate_concept`\n- `okf_suggest_concept_path`\n- `okf_propose_concept`\n- `okf_propose_update`\n- `okf_propose_attested_computation`\n- `okf_propose_v02_migration`\n- `okf_list_proposals`\n- `okf_get_proposal`\n- `okf_accept_proposal`\n- `okf_reject_proposal`\n- `okf_validate_changes`\n- `okf_apply_changes`\n- `get_graph`\n- `get_neighbors`\n- `get_subgraph`\n- `find_paths`\n- `graph_summary`\n- `validate_bundle`\n- `validate_project`\n- `export_graph`\n\nMost MCP tools are read-only over the current index. `load_remote_bundle` mutates only the server's in-memory index by fetching a public GitHub tree; it does not write files. Concept listing and search default to compact summaries; pass `detail: \"full\"` when navigation metadata, signals, ranking, or snippets are required. Relationship paths are deduplicated by node sequence even when parallel edge kinds connect the same concepts.\n\nEvery MCP tool includes a purpose-specific description, descriptions for its input parameters, and standard annotations covering read-only behavior, destructive behavior, idempotency, and external access.\n\nTool arguments are validated against the advertised input schemas before\nexecution. Unsupported fields, missing required values, incorrect primitive\ntypes, and out-of-range integers are rejected without coercion. Unknown or\ndisabled tool names remain protocol-level invalid-parameter errors.\n\nTool discovery and direct invocation use the same capability checks:\n\n| Mode | Normal proposals | Direct live write | Computation proposal | Runtime remote load |\n| --- | --- | --- | --- | --- |\n| default | disabled | disabled | disabled | disabled |\n| `--authoring` | enabled | disabled | disabled | disabled |\n| `--write --actor openai/gpt-5.6` | disabled | enabled | disabled | disabled |\n| `--authoring --allow-computation-authoring` | enabled | disabled | enabled | disabled |\n| `--allow-remote-tool` | disabled | disabled | disabled | enabled |\n\nAn explicit local root or project workspace exposes concept validation, path suggestion, and proposal inspection helpers. Proposal mutation tools require `--authoring`. The direct live tools instead require `--write` plus a truthful actor using `human:<id>`, `process:<id>`, or `provider/model` syntax. In normal single-root mode, callers omit `bundle`; it is required only to select among multiple project roots. Remote roots remain read only.\n\nGeneric concept tools cannot create or change an Attested Computation contract. `okf_propose_attested_computation` additionally requires `--allow-computation-authoring` and creates one coordinated review proposal for the concept plus an optional external computation file.\n\n## Live Concept Authoring\n\nStart the server with the direct-write capability only when the MCP client/user approval boundary is sufficient review:\n\n```bash\nokf --root /path/to/catalog --write --actor openai/gpt-5.6 mcp\n```\n\nThe agent sees one read-only batch validator and one destructive apply tool. It supplies structured concept fields rather than YAML; OKF serializes compatible Markdown frontmatter and stamps the configured `generated.by` plus one `generated.at` timestamp for the whole batch.\n\n```json\n{\n  \"name\": \"okf_apply_changes\",\n  \"arguments\": {\n    \"message\": \"docs(okf): document order creation\",\n    \"changes\": [\n      {\n        \"op\": \"create\",\n        \"type\": \"MCP Tool\",\n        \"title\": \"Create Order\",\n        \"body\": \"# Create Order\\n\\nCreates a validated order.\",\n        \"tags\": [\"orders\", \"mcp\"],\n        \"sources\": [\"/repositories/orders-service.md\"],\n        \"relations\": [\n          { \"type\": \"related_to\", \"target\": \"/workflows/order-creation.md\" }\n        ]\n      }\n    ]\n  }\n}\n```\n\nCreate paths are optional. The server first uses a strong dominant directory convention from existing same-type concepts within the requested prefix, then falls back to deterministic type/title slugs. `okf_suggest_concept_path` reports the strategy, evidence, path availability, and same-type/title matches so an available filename is not mistaken for a safe duplicate. Updates identify an existing `uri`; stale locators return bounded likely replacements, while scalar fields replace existing values and `tags`, `sources`, and `relations` use explicit `add`/`remove` patches. `metadata` carries extension frontmatter but cannot override identity, generation, collection, or computation fields. Paths and URIs are immutable during update: moving a concept changes its portable identity and remains a separate, intentionally unsupported operation.\n\nEvery 1–100 item batch is validated as one future graph, so concepts created together can reference one another and same-type/title conflicts are detected across creates and updates. Call `okf_validate_changes` with the complete intended batch to receive a time-of-check preview without writing files. Validation and apply share the same planner; apply repeats every check under the writer queue because revisions and Git state can change after a preview. Compact receipts are the v0.8 default; pass `detail: \"full\"` for the v0.7 planning layout. Effects expose structured relations and keep server-managed generation provenance separate from substantive `changedFields`.\n\nThe server writes nothing unless every candidate is valid, revision checks still match, and every target stays inside one writable bundle. Process-generated documents, generator output directories, hidden/control-plane paths such as `.git/**`, reserved files, and Attested Computation contracts are not live-write targets. Rollback checks revisions immediately before each restore and reports detected replacements as a partial `rollback_conflict`. That protection is best effort under the documented single-external-writer requirement; it is not a cross-process compare-and-swap guarantee.\n\nAdd `--git-commit` as server policy to create one commit per successful batch. A detected Git worktree must be completely clean and have a configured identity before publication. Active Git filter attributes and `assume-unchanged`/`skip-worktree` index flags block the operation so validation cannot execute configured filters or overlook hidden user changes; replace-object resolution is disabled so hidden replacement history cannot alter the parent tree. The server builds an isolated index from the validated Markdown bytes, creates that exact tree with `commit-tree`, publishes it with a compare-and-swap ref update, synchronizes only the affected ordinary-index paths afterward, and never pushes. Concurrent unrelated staged entries cannot enter the commit. A determinate commit failure leaves matching valid files as working-tree-only; an ambiguous ref-update timeout is reported as unknown unless the resulting commit tree can be proven. Non-Git catalogs are written normally. Every response makes the repository root, commit state, index state, target-byte state, and persistence boundary explicit.\n\n## Authoring Concepts\n\nThe reviewable proposal workflow remains available through MCP tools started with `--authoring` and through the HTTP API. Clients never need direct local file access.\n\nMCP proposal flow:\n\n```json\n{\n  \"name\": \"okf_propose_concept\",\n  \"arguments\": {\n    \"path\": \"tools/create-order.md\",\n    \"frontmatter\": {\n      \"type\": \"MCP Tool\",\n      \"title\": \"Create Order\",\n      \"relations\": [\n        {\n          \"type\": \"related_to\",\n          \"target\": \"/workflows/order-creation.md\"\n        }\n      ]\n    },\n    \"body\": \"# Create Order\\n\\nCreates an order through the application MCP tool.\",\n    \"message\": \"Document create_order for agents.\"\n  }\n}\n```\n\nThen call `okf_accept_proposal` with the returned `proposal.id`.\n\nTo correct an existing concept, read it with `get_concept`, then propose only the fields that need to change:\n\n```json\n{\n  \"name\": \"okf_propose_update\",\n  \"arguments\": {\n    \"uri\": \"okf://app/tools/create-order\",\n    \"frontmatter\": {\n      \"title\": \"Create Order Tool\",\n      \"description\": \"Creates a validated order.\"\n    },\n    \"removeFrontmatterKeys\": [\"deprecatedField\"],\n    \"message\": \"Correct outdated tool metadata.\"\n  }\n}\n```\n\nOmitted frontmatter fields and an omitted body are preserved. The concept URI cannot change through an update. Each update proposal records the source file revision, and acceptance checks it again immediately before replacing the file so detected concurrent changes are rejected.\n\nSafety rules:\n\n- concept paths must be safe, non-hidden relative `.md` paths inside a writable bundle\n- concept writes cannot traverse symbolic links under a writable bundle\n- missing subdirectories are created only when a proposal is accepted\n- `index.md` and `log.md` cannot be authored as concepts\n- duplicate paths and duplicate `okf://` IDs are rejected\n- updates cannot change concept identity and reject detected changes made after proposal creation\n- invalid IDs, invalid relation types, and broken internal OKF relations fail validation\n- external relation targets such as `repo://...` are allowed\n- direct batches are serialized within one process and validate the combined future graph before publication\n- independent processes still require external single-writer coordination\n\n## HTTP API\n\nStart the HTTP server:\n\n```bash\nOKF_WRITE_TOKEN=change-me okf --root /path/to/catalog serve --host 127.0.0.1 --port 8765\n```\n\nRead/validation endpoints:\n\n- `GET /health`\n- `GET /v1/bundles`\n- `POST /v1/concepts/validate`\n- `POST /v1/concepts/suggest-path`\n\nProposal inspection and mutation endpoints require `Authorization: Bearer <OKF_WRITE_TOKEN>` because pending records can contain complete candidate Markdown and computation code:\n\n- `GET /v1/proposals`\n- `GET /v1/proposals/:id`\n- `POST /v1/proposals`\n- `POST /v1/proposals/update`\n- `POST /v1/proposals/:id/accept`\n- `POST /v1/proposals/:id/reject`\n\nThe default file-backed proposal store writes proposal JSON under `.okf-proposals` in the selected root or project. Accepted proposals write Markdown concepts into the selected local root.\n\n`POST /v1/concepts/validate` and `POST /v1/concepts/suggest-path` do not persist anything. `POST /v1/proposals` persists only a proposal record. Only `POST /v1/proposals/:id/accept` writes a concept Markdown file.\n\n## Remote Bundles\n\nRemote bundles let one workspace consume concepts published by another repository without vendoring them. For a host-agnostic setup, clone or mount an OKF repository from any Git host and pass its directory through `--root`; transport and synchronization remain outside the OKF specification.\n\nSupported source:\n\n- Public GitHub repository tree URLs: `https://github.com/<owner>/<repo>/tree/<ref>/<path>`\n\nRemote loading:\n\n- inventories the tree, fetches selected `.md` documents first, then fetches only explicitly referenced bundle-local assets\n- records resolved revision metadata, SHA256 digests, document/asset byte counts, and unresolved references\n- inventories remote paths but never downloads the contents of unreferenced `.sql`, `.py`, or binary files\n- keeps each remote bundle under its configured bundle id\n- supports `include` and `exclude` filters\n- resolves Markdown links inside the remote bundle path\n- enforces file count and byte limits\n- does not execute code from the remote repository\n\nCLI examples:\n\n```bash\nokf --remote-bundle shared=https://github.com/example/okf-atlas/tree/main/bundles/shared --inspect\nokf --project okf.project.yaml --remote-bundle vendor=https://github.com/example/vendor-okf/tree/main/bundles/catalog validate\n```\n\nMCP runtime loading:\n\nStart the MCP server with `--allow-remote-tool` before calling `load_remote_bundle`.\n\n```json\n{\n  \"name\": \"load_remote_bundle\",\n  \"arguments\": {\n    \"id\": \"shared\",\n    \"url\": \"https://github.com/example/okf-atlas/tree/main/bundles/shared\",\n    \"include\": [\"public/**\"]\n  }\n}\n```\n\nUse `list_remote_bundles` to inspect what was loaded.\n\n## Structured Search\n\n`search_concepts` accepts:\n\n- `query`\n- `bundle`\n- `types`\n- `tagsAny`\n- `tagsAll`\n- `pathPrefix`\n- `frontmatter`\n- `linkedTo`\n- `linkedFrom`\n- `relationType`\n- `orphanOnly`\n- `statuses`\n- `trustTiers`\n- `freshness` and deterministic `asOf`\n- `hasSources`\n- `runtime` and `attestationReady`\n- `generatedBy` and `verifiedBy`\n- `detail` (`compact` by default, or `full`)\n- `limit`\n- `offset`\n\n`list_concepts` also accepts a text `query` and applies it together with its\nlisting filters. Text search tokenizes case-insensitively and requires every\nquery term, regardless of order. BM25+ ranks title, type, tags, aliases,\ndescription, path, and body matches; frontmatter remains available through\nexact structured filters but is not copied into the text index. Scores are\nrelative within a result set and are not a stable cross-version scale. Compact results contain only `uri`, `title`, `type`, and `description`; title, type, and description are bounded, while full results remain lossless.\n\nQueries are bounded to 512 characters and 16 terms. Prefix expansion, fuzzy\nmatching, stemming, and stop-word removal are intentionally disabled so code\nidentifiers and domain terminology remain literal. Punctuation-only queries\nreturn no matches. Tags and types are matched case-insensitively. Arbitrary\nfrontmatter filters support exact scalar matching and array-contains\nmatching. `relationType` selects concepts with an outgoing relation of that\ntype.\n\nThe SDK regression suite also budgets a neutral four-step research path from actual serialized MCP text. It uses UTF-8 bytes divided by four as a deterministic estimate, not an exact model tokenizer or billing count, and guards both an absolute compact budget and a compact/full ratio.\n\nExample:\n\n```json\n{\n  \"query\": \"catalog\",\n  \"types\": [\"API Route\"],\n  \"tagsAll\": [\"api\", \"orders\"],\n  \"limit\": 10\n}\n```\n\nFor local relevance and performance checks, run the non-packaged development\nbenchmark with a bundle root and an optional JSON array of `{ \"query\": \"...\",\n\"expected\": \"path/or/concept-id\" }` judgments:\n\n```bash\nnode --expose-gc scripts/search-benchmark.js \\\n  --root /path/to/okf \\\n  --qrels /path/to/qrels.json\n```\n\nIt reports OKF and search-index build time, retained heap/RSS, p50/p95 query\nlatency, Recall@10, MRR@10, and representative rankings. Search indexes are\nprocess-local and keyed to the parsed OKF index, so remote loads and accepted\nproposals receive a fresh index automatically.\n\n## Graph Behavior\n\nAs an okf-mcp graph projection, Markdown links become `markdown_link` edges, extension `relations` become typed `relation` edges, and standard v0.2 path-valued fields become `resource`, `source`, `computation`, `executor`, and `attester` edges. Internal concept references resolve to canonical nodes; explicitly referenced non-Markdown files resolve to okf-mcp `okf-asset://` nodes; URLs and scope descriptors remain unfetched external or opaque leaves.\n\nFor navigation convenience, okf-mcp resolves links to a nested bundle directory to that directory's reserved\n`index.md` when there is no exact document target. This applies to local and\nremote bundles and to candidate validation during proposal authoring.\n\nGraph tools return bounded JSON:\n\n```json\n{\n  \"nodes\": [\n    {\n      \"id\": \"okf://app/routes/order-status\",\n      \"bundle\": \"app\",\n      \"path\": \"routes/order-status.md\",\n      \"type\": \"API Route\",\n      \"title\": \"Order Status Route\",\n      \"tags\": [\"api\", \"orders\"],\n      \"description\": \"Serves order status state.\"\n    }\n  ],\n  \"edges\": [],\n  \"warnings\": []\n}\n```\n\nUse `graph_summary` first for counts by lifecycle, trust, freshness, runtime, readiness, and edge kind. Graph tools accept `edgeKinds`; pass `includeExternal: true` or `includeAssets: true` when those leaf nodes are needed.\n\nDefault relation types:\n\n- `depends_on`\n- `produces`\n- `consumes`\n- `persists_to`\n- `materializes_to`\n- `configured_by`\n- `checked_by`\n- `owned_by`\n- `supersedes`\n- `related_to`\n\nAdd project-specific relation types with `relationTypes` in `okf.project.yaml`.\n\nProject paths in `bundles` and `plugins` must be relative paths that stay inside the directory containing `okf.project.yaml`. Absolute paths and `../` escapes are rejected.\n\nBundle `include` and `exclude` filters use simple path patterns:\n\n- exact file paths, such as `services/order-status.md`\n- directory prefixes, such as `archive/`\n- `*` for one path segment\n- `**` for any nested path\n\n## Validation\n\n`validate`, `validate_bundle`, and `validate_project` return separate `conformant` and `validForProject` fields plus structured diagnostics. `valid` remains a compatibility alias for `validForProject`.\n\nOKF conformance covers, when the corresponding files are present:\n\n- parseable YAML mapping frontmatter on non-reserved concept documents\n- a non-empty `type`\n- the reserved structure of `index.md` and `log.md`\n\nUnknown frontmatter keys and unknown concept type values do not fail conformance. The YAML parser supports nested mappings, arrays, block scalars, and other structures accepted by its safe YAML core schema; duplicate keys and unsupported custom tags are rejected.\n\nMissing `index.md` files and broken cross-links do not fail OKF conformance. `strictLinks` affects only okf-mcp workspace validity (`validForProject`), not the normative `conformant` result.\n\nProject validity additionally reports:\n\n- duplicate OKF URIs\n- broken internal Markdown links as advisories by default; set project `strictLinks: true` or pass `--strict-links` to make them project-invalid\n- invalid relation types\n- missing relation targets\n- broken `okf://` relation targets\n- duplicate bundle IDs\n- invalid or escaping project paths\n- links that resolve outside the configured bundle root\n- missing bundle roots\n\nThe server keeps serving valid concepts from partial bundles.\n\nOptional v0.2 families are normalized into `signals`. Malformed provenance, generation, verification, lifecycle, freshness, or computation metadata produces an advisory and never creates a fourth trust tier. Verification fails closed to `unverified`; absent status defaults to `stable`; freshness is evaluated at an explicit `asOf` date when supplied. Authoring is stricter than consumption and rejects malformed known v0.2 fields.\n\n## Attested Computation\n\n`inspect_attested_computation` reports the runtime, declared parameters, sanctioned inline or file computation digest, executor receipt fields, attester reference, indexed assets, readiness, and diagnostics. `prepare_attested_computation` checks declared parameter names and returns digests without returning values. `check_computation_receipt` checks field presence without returning values, persisting the receipt, or claiming attestation.\n\nokf-mcp has no execution or attestation adapter. It never runs the computation, executor resource, or attester resource, and it never fetches an external contract URI on demand.\n\nCLI parity is available through `computation inspect|prepare|check-receipt`, `provenance`, `edge-kinds`, and `asset`. Supply sensitive values with `--parameters-file <path|->` or `--receipt-file <path|->`; raw parameter and receipt JSON is intentionally rejected in process arguments. `-` reads one JSON object from stdin. Asset reads accept `--max-content-bytes` up to the indexed 1 MiB limit.\n\n## Migrating Existing Catalogs To v0.2\n\nThe v0.2 specification keeps v0.1 bundles consumable through two fallbacks: legacy `timestamp` when `generated` is absent, and a legacy body `# Citations` list when `sources` is absent. okf-mcp applies those fallbacks during reads and offers an optional review-only conversion workflow.\n\nFor one root, inspect migration readiness and preview the proposed native fields without writing anything:\n\n```bash\nokf --root /path/to/catalog migrate check\nokf --root /path/to/catalog migrate preview \\\n  '{\"metrics/revenue.md\":{\"by\":\"human:owner\",\"confirmed\":true}}'\n```\n\nIn optional multi-root project mode, supply the root id before the actor-mapping JSON.\n\nMigration is deliberately conservative:\n\n- native `generated` and `sources` fields always win\n- a valid `timestamp` is copied into a new `generated: { by, at }` mapping only after a truthful `by` actor is explicitly confirmed\n- `# Citations` becomes `sources` only from one top-level H1 section containing at least one safely parseable list entry and no unparsed prose, nested sections, ambiguous entries, or escaping paths\n- legacy fields and citation prose are retained for compatibility\n- concepts marked by `--generated-path`, a document flag, or `generated_file`/`generatedFile` frontmatter must be changed through their generator; remote roots are report-only\n- identity collisions, invalid documents, unsafe references, and unresolved assets block the version declaration\n\n`okf_propose_v02_migration` requires local-root authoring. It creates a review manifest, one proposal per affected file, and a gated root `okf_version: \"0.2\"` proposal. Nothing is accepted automatically; the root proposal can be accepted only after every child is accepted and the complete catalog validates.\n\n## Generator Plugins\n\nGenerator plugins are configured in `okf.project.yaml` and run with `generate`.\n\nBuilt-in plugins:\n\n- `filesystem`: creates one concept per matching source file. Defaults to Markdown files.\n- `json-spec`: creates one concept per JSON file and can emit `persists_to` relations when a destination table is present.\n\nGenerated output is regular Markdown/YAML OKF and is validated by the same indexer as hand-authored concepts.\n\n## Limitations\n\n- MCP transport is stdio only. The separate HTTP authoring API is not MCP over HTTP.\n- MCP protocol compatibility follows the pinned official SDK v2 dependency.\n- There is no file watcher. Restart the server after external file changes. Concepts accepted through MCP authoring refresh the MCP server index immediately.\n- The HTTP API is a lightweight built-in server, not a full hosted multi-tenant service.\n- OKF v0.2 computation support is static inspection and preflight only; no computation or attester is executed.\n",
  "bytes": 34800,
  "sha": "e75dab835adfb2dca6a167821446641491f1aa6b6f67bb2b8fa71348183f29e2",
  "repo_slug": "mfdaves/okf-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mfdaves_okf_mcp_3359eec2/readme"
}