okf-mcp

okf-mcp

okf-mcp は、ナレッジをすでに保持しているシステムから Open Knowledge Format v0.2 を公開し、その結果をエージェントに提供します。ローカルファーストのコンシューマー、バリデーター、グラフインデックス、CLI、MCP サーバーです。

難しいのは、カタログへの安全な書き込みです。設定されたプロデューサーが外部ソースを読み取り、候補バンドルを返すと、okf-mcp はそれを検証し、所有するファイルを正確に記録した所有権マニフェストのもとで公開します。手作業で作成されたコンテンツが取り込まれることはなく、変更のないソースを書き換えることもなく、プロデューサーの出力がバンドルの外に出ることもありません。@mfdaves/okf-postgres は、テーブルの行を一切読み取らずに、この方法で PostgreSQL カタログを読み取ります。

読み取りは、通常の処理です。YAML フロントマター付きの Markdown ファイルからなる OKF バンドルディレクトリを読み取ります。オプションのワークスペースモードでは、複数のバンドルを統合できます。概念は、CLI コマンドと、検証、構造化検索、グラフナビゲーション、来歴の確認、提案ベースのオーサリングを行う MCP リソースおよびツールを通じて利用できます。

コアには意図的に、データベース、埋め込み、ビルドステップ、ホスト型サービスへの依存がありません。安全な YAML 処理には js-yaml、Markdown 構造の解析には CommonMark、インメモリの BM25+ テキスト検索には MiniSearch、stdio MCP には公式の Model Context Protocol TypeScript SDK v2 を使用します。ローカルルートモードではネットワーク呼び出しは行われません。オプションのリモート読み込みでは、GitHub から公開 Markdown 概念と、明示的に参照されている不活性アセットのみを取得します。v0.2 の計算サポートでは、コードの実行もレシートの証明も行いません。

OKF v0.2 のサポートと拡張

OKF v0.2 は、意図的にポータブルなファイル形式を規定しており、提供やクエリのランタイムは規定していません。okf-mcp は、この境界を明確に保ちます。

領域	公式の OKF v0.2	okf-mcp の動作
バンドルと識別	Markdown ファイルのディレクトリツリー。Concept ID は、.md を除いたバンドル相対パスです	--root は単一のバンドルに直接対応します。okf:// はオプションのワークスペースロケーターであり、ポータブルな Concept ID ではありません
概念のメタデータ	type は必須です。title、description、resource、tags は推奨されます。不明なキーも許可されます	拡張フィールドと不明なタイプを保持しながら、規範への適合性とワークスペースポリシーへの適合性を分けて報告します
来歴とライフサイクル	sources、usage_window、generated、verified、status、stale_after	検索、来歴のたどり、信頼階層、決定論的な鮮度チェックのために、これらのフィールドを正規化します
参照	Markdown リンク、およびパス値を持つ resource、sources[].resource、computation、executor.resource、attester.resource フィールド	コードを実行したり、参照先のコードを暗黙的に取得したりすることなく、グラフエッジと範囲を限定した不活性アセットのスナップショットを構築します
Attested Computation	コントラクトのフィールドと参考用のコンシューマーフローを定義し、ランタイムのワイヤープロトコルとアテスターのパッケージングは規定しません	コントラクトとダイジェストを静的に調査し、宣言されたパラメーター名とレシートのフィールド名を確認します。実行も証明の主張も行いません
v0.1 との互換性	generated マッピング全体が存在しない場合の timestamp フォールバックと、sources キーが存在しない場合の # Citations フォールバックを許可します	両方の形式を読み取り、レビュー専用の移行チェックと提案を追加します

以下は形式の要件ではなく、okf-mcp の拡張機能です。

• CLI、MCP、HTTP インターフェイス、インメモリ検索、グラフビュー
• オプションの複数バンドル対応 okf.project.yaml ワークスペースと、型付きの relations
• 互換性用の id、aliases、okf:// ロケーター
• 明示的な承認を伴う、提案ベースのオーサリング
• 範囲を限定した GitHub リモート読み込みと、明示的にマッピングされた固定 Git ソース
• ジェネレータープラグインと、strictLinks などの、より厳格なオプトイン型プロジェクトポリシー

インストールと実行

Node 22 以降が必要です。

GitHub リリースからインストールします。

git clone --branch v0.9.1 https://github.com/mfdaves/okf-mcp.git
cd okf-mcp
npm ci
node bin/okf-mcp.js --root ./path/to/okf validate

再現性のある利用のため、公開済みのバージョンを固定します。

npx -y @mfdaves/[email protected] --version
npx -y @mfdaves/[email protected] --root ./path/to/okf validate

永続的にインストールする場合：

npm install --global @mfdaves/[email protected]

okf --version
okf --root ./path/to/okf validate
okf-mcp --root ./path/to/okf mcp

現在のソースブランチから作業する場合：

git clone https://github.com/mfdaves/okf-mcp.git
cd okf-mcp
npm ci
npm test
node bin/okf-mcp.js --version

--root はローカルの OKF バンドルディレクトリを 1 つ受け取り、単一のバンドルに対する推奨の okf-mcp インターフェースです。各コンセプトのポータブルな識別子は、そのルート内の拡張子を除いたパスです。

--bundle はパスまたは id=path を受け取ります。互換性のため、複数のフラグも引き続きサポートされます。--project とその bundles: リストは、オプションの okf-mcp フェデレーション／オーサリング拡張であり、OKF v0.2 の一部ではありません。

--remote-bundle は id=https://github.com/<owner>/<repo>/tree/<ref>/<path> を受け取ります。まず公開済みの Markdown を取得し、その後、標準 v0.2 のリソースフィールドで明示的に指定されたバンドル内のファイルのみを取得します。リモートコンテンツは読み取り専用で、動作を実行しません。

--inspect は簡潔なグラフの概要を出力して終了します。--inspect も明示的なコマンドも指定しない場合、プロセスは stdio MCP サーバーを起動します。

インストール時に、このパッケージは okf と okf-mcp の両方のバイナリを提供します。ソースを明示的に指定しない場合、CLI はまず okf_version を宣言する最も近いルートの index.md を検索します。最も近いプロジェクトを検索する方法は、互換性のための代替手段として引き続き利用できます。

CLI の終了ステータスは、成功時が 0、検証または運用上の失敗時が 1、無効な使い方の場合が 2 です。不明なオプションは拒否されます。

同梱の OKF リファレンス

このリポジトリでは、製品、そのランタイムの境界、インターフェース、オーサリングワークフロー、安全性ポリシーを説明する、自己記述型の OKF バンドルを公開しています。ポータブルなエントリー Concept ID は overview/okf-mcp です。okf://okf-mcp/overview/okf-mcp は引き続き、ワークスペース／MCP リソースロケーターとして使用できます。

チェックアウトまたはインストール済みパッケージから、同梱のリファレンスを検証してクエリを実行します。

okf --root okf/okf-mcp validate
okf --root okf/okf-mcp search "proposal"
okf --root okf/okf-mcp concept overview/okf-mcp

現在のソースブランチからリファレンスバンドルを直接読み込みます。

okf --remote-bundle okf-mcp=https://github.com/mfdaves/okf-mcp/tree/main/okf/okf-mcp --inspect

公開済みの v0.8.0 タグでは、元の okf/bundles/okf-mcp パスが維持されています。より短い okf/okf-mcp パスは、 未公開の 0.8.1 メンテナンスチェックポイントで準備され、v0.9.0 に同梱されます。 不変の v0.8.0 リリースに変更はありません。

@mfdaves/okf-mcp npm パッケージには、okf.project.yaml と完全なリファレンスバンドルの両方が含まれています。

オプションのマルチバンドルプロジェクト設定

1 つのプロセスで複数のルートをフェデレーションする必要がある場合、ジェネレーターまたは外部メタデータプロデューサーを設定する場合、あるいはプロジェクト全体に適用する関係の語彙を定める場合にのみ、okf.project.yaml を使用します。

project: Example
strictLinks: false
bundles:
  - id: app
    root: okf/bundles/app
    include: ["**/*.md"]
    exclude: ["archive/**"]
  - id: data
    root: okf/bundles/data
  - id: company-database
    root: okf/company-database
relationTypes:
  - deployed_by
remoteBundles:
  - id: shared
    url: https://github.com/example/okf-atlas/tree/main/bundles/shared
    include: ["public/**"]
    exclude: ["drafts/**"]
plugins:
  - name: docs
    type: filesystem
    root: docs
    output: okf/bundles/app/generated/docs
    bundle: app
producers:
  - name: main-database
    type: postgresql
    package: "@mfdaves/okf-postgres"
    bundle: company-database
    config:
      connectionEnv: DATABASE_URL
      source: company-db
      schemas: [public]
      includeIndexes: true

プロジェクトコマンドを実行します。

okf --project okf.project.yaml validate
okf --project okf.project.yaml search "orders"
okf --project okf.project.yaml graph mermaid
okf --project okf.project.yaml generate
okf --project okf.project.yaml producer list
okf --project okf.project.yaml producer preview main-database
okf --project okf.project.yaml producer run main-database --write --actor process:nightly-refresh
okf --project okf.project.yaml mcp
okf --project okf.project.yaml mcp --authoring
okf --project okf.project.yaml mcp --allow-remote-tool
OKF_WRITE_TOKEN=change-me okf --project okf.project.yaml serve
okf --remote-bundle shared=https://github.com/example/okf-atlas/tree/main/bundles/shared --inspect

コマンド：

• mcp
• validate
• graph [json|dot|mermaid]
• search <query>
• concept <concept-id-or-locator>
• neighbors <concept-id-or-locator>
• paths <from> <to>
• provenance <uri>
• edge-kinds
• computation inspect|prepare|check-receipt
• asset <okf-asset-uri>
• source <concept-id-or-locator> <source-id>
• migrate check|preview
• generate
• producer list|preview|run
• serve

外部メタデータプロデューサー

プロデューサーは、組み込みの plugins: ジェネレーターとは別のものです。プロデューサーは外部ソースからメタデータを読み取り、メモリ上の候補 OKF バンドルを返します。okf-mcp はその候補を検証して公開します。各プロデューサーパッケージをプロジェクトと同じ場所にインストールし、信頼されたプロジェクト設定で正確なベアパッケージ名を許可リストに登録します。MCP の呼び出し元は設定済みのプロデューサーを選択できますが、そのパッケージ、設定、認証情報、クエリ、バンドル、出力パスを差し替えることはできません。

パッケージはプロジェクトに属する node_modules ディレクトリにインストールし、正確なベア名で解決できる必要があります。通常のレジストリからのインストール、npm ワークスペース、npm link、pnpm などのストアを利用するレイアウトはすべて条件を満たします。設定内のパスでは条件を満たしません。

パッケージは、バージョン管理された okfProducer API をエクスポートする必要があります。プロデューサー API v1 は OKF v0.2 を対象とし、副作用のない出力先生成と validateConfig() を分離します。候補の概念には、ネイティブの generated と空でない sources の来歴情報が必要です。ホストは、安全でないパス、不正な概念、解決されていないリンクまたは型付きリレーション、所有されていないファイルとの衝突、ローカルで変更された管理対象ファイル、出力内のシークレット値、およびプロジェクト全体が無効な状態になる候補を拒否します。

両方のインターフェースは同じホストを使用します。スケジュールされた更新には CLI を使用します。

okf --project okf.project.yaml producer preview main-database
okf --project okf.project.yaml producer run main-database --write --actor process:nightly-refresh

producer preview は候補が無効な場合に 1 で終了します。producer run は何も公開されなかった場合に 1 で終了します。どちらも MCP ツールが返すものと同じレシートを出力します。

設定済みのプロジェクトでは、MCP に次の機能が公開されます。

• okf_list_producers：パッケージコードを読み込まず、ソースも読み取らずに設定を一覧表示します
• okf_preview_producer：ソースメタデータを読み取り、検証済みの書き込みを伴わない差分を返します
• okf_run_producer：共有ライターキュー内で再生成し、リビジョンを確認してロールバックできる状態で公開します。--write と、human:<id>、process:<id>、または provider/model の形式を使用した正確な --actor の指定がある場合にのみ利用できます

プレビューと実行では、設定済みのプロデューサー名と、任意のレシート詳細のみを受け付けます。レシートには、上限のある数値形式のソースオブジェクトの概要と、公開差分の件数が含まれます。公開記録では、所有する相対パスと SHA-256 ダイジェストをバンドル内の .okf-producer.json に記録します。更新または削除できるのは、前回のマニフェストが所有する変更されていないパスだけです。手書きのコンテンツが暗黙に取り込まれることはありません。マニフェストには、プロデューサーの設定、認証情報、接続情報は含まれません。

管理対象バンドルを繰り返し実行しても安定させるため、次の 2 つのルールがあります。

• プロデューサーは実行のたびに generated.at を再設定します。ホストはこのスタンプを無視して各候補を公開済みファイルと比較するため、ソースに変更がない場合は unchanged と報告し、バイト列、タイムスタンプ、マニフェストは変更しません。そのため、公開差分の件数は実行ではなくソースの変更を表します。
• マニフェストのエントリーだけでは、作業を破棄する権限にはなりません。ホストが書き換えまたは削除するファイル自体に generated の来歴情報が必要です。これにより、破損したマニフェスト、手作業で統合されたマニフェスト、偽造されたマニフェストによって、プロデューサーが手書きのコンテンツを削除することを防ぎます。

古くなったファイルの削除によって空になったディレクトリは、最後の管理対象ファイルとともに削除されます。

@mfdaves/okf-postgres は PostgreSQL の実装です。一般的な用途を対象とする v1 では、テーブルの行を読み取らずに、データベース、スキーマ、テーブル／ビュー、カラム、キー、チェック制約、列挙型、インデックス、説明のメタデータを扱います。接続文字列は connectionEnv で指定する環境変数に保管してください。YAML に接続文字列を記載しないでください。

serve のオプション：

• --host <host>：バインドするホスト。既定値は 127.0.0.1
• --port <port>：バインドするポート。既定値は 8765
• --write-token <token>：書き込みエンドポイント用のベアラートークン。既定値は OKF_WRITE_TOKEN
• --proposal-root <path>：提案 JSON ディレクトリ。既定値は、選択したローカルルートまたはプロジェクト内の .okf-proposals

MCP クライアント設定

以下の npm ベースの例では、現在公開されているリリースを使用します。ソースをチェックアウトした場合は、同じ引数で実行可能ファイル bin/okf-mcp.js を呼び出せます。

クライアント設定の例：

{
  "mcpServers": {
    "okf": {
      "command": "npx",
      "args": [
        "-y",
        "@mfdaves/[email protected]",
        "--root",
        "/absolute/path/to/okf",
        "mcp"
      ]
    }
  }
}

読み取り専用のプロジェクトヘルパーを使用し、提案の変更を行わないプロジェクト設定モード：

{
  "mcpServers": {
    "okf": {
      "command": "npx",
      "args": [
        "-y",
        "@mfdaves/[email protected]",
        "--project",
        "/absolute/path/to/repo/okf.project.yaml",
        "mcp"
      ]
    }
  }
}

提案の作成、承認、却下を有効にするには、--authoring を追加します。直接書き込みの対象を絞るには、--write --actor <actor> を追加して、読み取り専用の okf_validate_changes と検証済みバッチ用の okf_apply_changes を公開します。カタログがクリーンな Git ワークツリーにある場合、成功した各バッチをコミットするには、--git-commit を追加します。MCP クライアントが実行時に任意のサポート対象パブリックリモートバンドルを読み込めるようにするには、--allow-remote-tool を追加します。設定済みのリモートバンドルは、この実行時読み込みフラグがなくても読み取り可能です。

stdio サーバーは @modelcontextprotocol/server v2 を使用します。最新の 2026-07-28 MCP リビジョンと、2025-11-25 を含む 2025 年代のクライアント向けに SDK が提供する互換性パスをサポートします。プロトコルネゴシエーション、フレーミング、リソースディスパッチ、ツールディスパッチ、および公開スキーマの検証は SDK が担います。

既知のツールで発生する想定内の失敗（概念の欠落、読み取り専用バンドル、リモート取得の失敗、無効な引数、提案の競合など）は、isError: true を含む MCP ツール結果として返されます。有効になっていないツールへの呼び出しは、SDK のディスパッチによって拒否されます。想定外の実装エラーは、内部の詳細を公開しないようにマスクされます。

MCP レジストリのメタデータ

server.json は、npm パッケージを stdio サーバー io.github.mfdaves/okf-mcp として記述します。レジストリ対応クライアントは、絶対パスの OKF ルートをユーザーに入力するよう求め、それを --root に渡し、固定の mcp コマンドを追加してください。

概念の識別情報と拡張

概念 ID は、.md を除いたバンドル相対の Markdown パスです。この拡張子のないパスが、移植可能な OKF 識別子です。okf-mcp は、ワークスペーススコープの互換ロケーターも公開します。

okf://<bundle-id>/<extensionless-concept-id>

従来の .md URI と、有効なカスタム id は、互換性のある検索エイリアスとして引き続き使用できます。単独の概念 ID は、読み込まれたバンドル全体で一意の場合にのみ解決されます。スタンドアロンの集約カタログでは、okf://services/queue.md のような URI 形式の移植可能なパスも、services/queue が全体で一意であり、services が読み込み済みバンドル ID でない場合に解決されます。正確な正規 URI が常に優先されます。既知のバンドル内で見つからないパスや、曖昧な移植可能パスは未解決のままです。予約済みの index.md と log.md は概念ではないため、ファイル名が保持されます。

以下の id、aliases、型付きの relations フィールドは、okf-mcp の拡張機能です。標準の v0.2 識別情報は、引き続きパスから導出されます。

---
id: okf://app/routes/order-status
type: API Route
title: Order Status Route
description: Serves order status state.
aliases: [order-status]
tags: [api, orders]
relations:
  - type: consumes
    target: okf://data/tables/order_status
  - type: configured_by
    target: repo://src/routes/order-status.js
---

# Order Status Route

新しいコンテンツでは、内部リンクと拡張リレーションのターゲットに、通常の相対パスまたはバンドルルートからの Markdown パスを使用してください。既存の okf:// ターゲットは引き続きサポートされます。repo:// などの OKF 以外のスキームは、互換性のため不透明な参照として扱われます。

Git ソースの固定

コードのナレッジは、マシン固有のパスを記録せずにコードリポジトリの外部に置くことができます。標準の sources エントリで Git Repository 概念を指定し、以下の okf-mcp git 拡張を追加してください。

sources:
  - id: implementation
    resource: /repositories/application.md
    git:
      revision: 0123456789abcdef0123456789abcdef01234567
      path: src/application.js
      lines: { from: 10, to: 30 }

リポジトリ概念のマッピングは、ローカルのプロセス設定にのみ追加してください。

okf --root /path/to/catalog \
  --repo repositories/application=/work/application \
  source architecture/application implementation

read_git_source と source CLI コマンドは、マッピングされた Git オブジェクトデータベースから固定済みの blob を読み取ります。ダーティーなワークツリーを読み取ったり、フェッチしたりすることはありません。マッピングがない場合やリビジョンが固定されていない場合は、表示されますが利用できません。リポジトリのマッピング先には、通常のチェックアウト、ベアリポジトリ、マウント済みパスを指定できます。認証情報とローカルパスは OKF バンドルの外部に保持されます。

ツール

• list_bundles
• list_concepts
• get_concept
• search_concepts
• list_types
• list_tags
• list_relation_types
• list_edge_kinds
• get_provenance
• inspect_attested_computation
• read_bundle_asset
• read_git_source
• prepare_attested_computation
• check_computation_receipt
• check_v02_migration
• load_remote_bundle
• list_remote_bundles
• okf_validate_concept
• okf_suggest_concept_path
• okf_propose_concept
• okf_propose_update
• okf_propose_attested_computation
• okf_propose_v02_migration
• okf_list_proposals
• okf_get_proposal
• okf_accept_proposal
• okf_reject_proposal
• okf_validate_changes
• okf_apply_changes
• okf_list_producers
• okf_preview_producer
• okf_run_producer
• get_graph
• get_neighbors
• get_subgraph
• find_paths
• graph_summary
• validate_bundle
• validate_project
• export_graph

ほとんどの MCP ツールは、現在のインデックスに対する読み取り専用です。load_remote_bundle は、公開 GitHub ツリーを取得してサーバーのメモリ内インデックスのみを変更し、ファイルには書き込みません。コンセプトの一覧表示と検索では、デフォルトで簡潔な概要が表示されます。ナビゲーションメタデータ、シグナル、ランキング、またはスニペットが必要な場合は、detail: "full" を指定してください。同じコンセプト間を複数のエッジ種別が結んでいる場合でも、関係パスはノードの並び順に基づいて重複排除されます。

各 MCP ツールには、用途に応じた説明、入力パラメーターの説明、読み取り専用の動作、破壊的な動作、冪等性、外部アクセスを網羅する標準アノテーションが含まれています。

ツールの引数は、実行前に公開されている入力スキーマに照らして検証されます。未対応のフィールド、必須値の欠落、プリミティブ型の不一致、範囲外の整数は、型変換されずに拒否されます。不明なツール名や無効化されたツール名は、プロトコルレベルの無効なパラメーターエラーになります。

ツールの検出と直接呼び出しでは、同じ機能チェックが適用されます。

モード	通常の提案	直接のライブ書き込み	計算の提案	実行時のリモート読み込み
デフォルト	無効	無効	無効	無効
--authoring	有効	無効	無効	無効
--write --actor openai/gpt-5.6	無効	有効	無効	無効
--authoring --allow-computation-authoring	有効	無効	有効	無効
--allow-remote-tool	無効	無効	無効	有効

明示的なローカルルートまたはプロジェクトワークスペースを指定すると、コンセプト検証、パスの提案、提案の確認を行うヘルパーが利用可能になります。提案を変更するツールには --authoring が必要です。これに対し、直接ライブツールには --write と、human:<id>、process:<id>、または provider/model の構文を使用した正確なアクター情報が必要です。通常の単一ルートモードでは、呼び出し元は bundle を省略します。これは複数のプロジェクトルートから選択する場合にのみ必要です。リモートルートは引き続き読み取り専用です。

汎用のコンセプトツールでは、Attested Computation コントラクトを作成または変更できません。okf_propose_attested_computation を使用するには、追加で --allow-computation-authoring が必要です。このツールは、コンセプトと任意の外部計算ファイルを対象とする、連携したレビュー提案を1件作成します。

ライブコンセプトの作成

書き込みを直接行う機能を有効にしてサーバーを起動するのは、MCP クライアント／ユーザーの承認境界で十分なレビューが確保されている場合に限ります。

okf --root /path/to/catalog --write --actor openai/gpt-5.6 mcp

エージェントには、読み取り専用の一括バリデーターと、破壊的な適用ツールが1つずつ表示されます。エージェントは YAML ではなく、構造化されたコンセプトフィールドを指定します。OKF は、互換性のある Markdown フロントマターをシリアライズし、設定された generated.by と、バッチ全体で共通の1つの generated.at タイムスタンプを付与します。

{
  "name": "okf_apply_changes",
  "arguments": {
    "message": "docs(okf): document order creation",
    "changes": [
      {
        "op": "create",
        "type": "MCP Tool",
        "title": "Create Order",
        "body": "# Create Order\n\nCreates a validated order.",
        "tags": ["orders", "mcp"],
        "sources": ["/repositories/orders-service.md"],
        "relations": [
          { "type": "related_to", "target": "/workflows/order-creation.md" }
        ]
      }
    ]
  }
}

作成時のパス指定は任意です。サーバーはまず、指定されたプレフィックス内にある同じ種類の既存コンセプトから、優勢なディレクトリ規則を強い根拠に基づいて判断します。その後、判断できない場合は、決定的な種類／タイトルのスラッグにフォールバックします。okf_suggest_concept_path は、使用する戦略、根拠、パスの利用可否、同じ種類／タイトルの一致項目を報告するため、利用可能なファイル名を安全な重複なしと誤認することはありません。更新では、既存の uri を指定します。古くなったロケーターに対しては、該当する可能性の高い置き換え候補を上限付きで返します。スカラー項目は既存の値を置き換え、tags、sources、relations には明示的な add／remove パッチを使用します。metadata には拡張フロントマターを格納できますが、識別情報、生成情報、コレクション、計算フィールドは上書きできません。更新時にパスと URI を変更することはできません。コンセプトを移動すると、ポータブルな識別情報が変わります。そのため、これは意図的にサポート対象外とされている別個の操作です。

1～100件のすべてのバッチは、将来のグラフ全体として検証されるため、同時に作成するコンセプト同士を相互参照できます。また、作成項目と更新項目全体で同じ種類／タイトルの競合が検出されます。ファイルを書き込まずに時点確認プレビューを受け取るには、意図するバッチ全体を指定して okf_validate_changes を呼び出します。検証と適用では同じプランナーを共有します。リビジョンや Git の状態はプレビュー後に変化する可能性があるため、適用時にはライターキュー内ですべてのチェックを再実行します。コンパクトなレシートが v0.8 のデフォルトです。v0.7 の計画レイアウトを使用するには、detail: "full" を指定します。変更内容には構造化された関係が含まれ、サーバー管理の生成情報の来歴は、実質的な changedFields と分けて保持されます。

すべての候補が有効で、リビジョンチェックが引き続き一致し、すべての対象が1つの書き込み可能なバンドル内にある場合を除き、サーバーは何も書き込みません。プロセスによって生成されたドキュメント、ジェネレーターの出力ディレクトリ、.git/** などの非表示／制御プレーンパス、予約ファイル、Attested Computation のコントラクトは、ライブ書き込みの対象ではありません。ロールバックでは、復元の直前にリビジョンを確認し、検出された置き換えを部分的な rollback_conflict として報告します。この保護は、文書化された単一の外部ライター要件のもとでのベストエフォートであり、プロセスをまたいだ compare-and-swap 保証ではありません。

サーバーポリシーとして --git-commit を追加すると、バッチが成功するたびに1つのコミットが作成されます。Git ワークツリーが検出された場合、公開前に完全にクリーンであり、ID が設定済みである必要があります。有効な Git フィルター属性や、assume-unchanged／skip-worktree のインデックスフラグがある場合、操作はブロックされます。これにより、検証時に設定済みフィルターが実行されたり、ユーザーによる非表示の変更が見落とされたりすることを防ぎます。非表示の置換履歴によって親ツリーが変更されないよう、replace-object の解決は無効になります。サーバーは、検証済みの Markdown バイトから分離されたインデックスを構築し、commit-tree でその正確なツリーを作成し、compare-and-swap による ref 更新で公開した後、影響を受けた通常のインデックスパスのみを同期します。プッシュは行いません。並行して追加された無関係なステージ済みエントリーがコミットに含まれることはありません。コミットの失敗が確定している場合、妥当性のあるファイルはワーキングツリーのみに残ります。ref 更新のタイムアウトにより結果が不明な場合、作成されたコミットツリーを証明できない限り、状態は不明として報告されます。Git 管理されていないカタログは通常どおり書き込まれます。すべての応答で、リポジトリのルート、コミット状態、インデックス状態、対象バイトの状態、永続化の境界が明示されます。

オーサリングの概念

レビュー可能な提案ワークフローは、--authoring を指定して起動した MCP ツールと HTTP API を通じて引き続き利用できます。クライアントがローカルファイルに直接アクセスする必要はありません。

MCP の提案フロー：

{
  "name": "okf_propose_concept",
  "arguments": {
    "path": "tools/create-order.md",
    "frontmatter": {
      "type": "MCP Tool",
      "title": "Create Order",
      "relations": [
        {
          "type": "related_to",
          "target": "/workflows/order-creation.md"
        }
      ]
    },
    "body": "# Create Order\n\nCreates an order through the application MCP tool.",
    "message": "Document create_order for agents."
  }
}

その後、返された proposal.id を指定して okf_accept_proposal を呼び出します。

既存の概念を修正するには、get_concept で読み込んでから、変更が必要なフィールドのみを提案します。

{
  "name": "okf_propose_update",
  "arguments": {
    "uri": "okf://app/tools/create-order",
    "frontmatter": {
      "title": "Create Order Tool",
      "description": "Creates a validated order."
    },
    "removeFrontmatterKeys": ["deprecatedField"],
    "message": "Correct outdated tool metadata."
  }
}

省略されたフロントマターのフィールドと本文は保持されます。更新によって概念 URI を変更することはできません。各更新提案にはソースファイルのリビジョンが記録され、ファイルを置き換える直前に受理時の再確認が行われるため、検出された同時変更は拒否されます。

安全性に関するルール：

• 概念のパスは、安全で、非表示ではない相対 .md パスであり、書き込み可能なバンドル内にある必要があります
• 概念の書き込みでは、書き込み可能なバンドル内のシンボリックリンクをたどることはできません
• 存在しないサブディレクトリは、提案が受理された場合にのみ作成されます
• index.md と log.md は概念としてオーサリングできません
• 重複するパスと重複する okf:// ID は拒否されます
• 更新によって概念の識別情報を変更することはできず、提案の作成後に行われた変更が検出された場合は拒否されます
• 無効な ID、無効な関係タイプ、および壊れた内部 OKF 関係は検証でエラーになります
• repo://... などの外部関係ターゲットは使用できます
• 直接のバッチ処理は単一プロセス内で直列化され、公開前に統合後のグラフ全体を検証します
• 独立したプロセス間では、引き続き外部での単一ライター調整が必要です

HTTP API

HTTP サーバーを起動します：

OKF_WRITE_TOKEN=change-me okf --root /path/to/catalog serve --host 127.0.0.1 --port 8765

読み取り／検証エンドポイント：

• GET /health
• GET /v1/bundles
• POST /v1/concepts/validate
• POST /v1/concepts/suggest-path

保留中のレコードには完全な候補 Markdown や計算コードが含まれる可能性があるため、提案の確認および変更エンドポイントには Authorization: Bearer <OKF_WRITE_TOKEN> が必要です：

• GET /v1/proposals
• GET /v1/proposals/:id
• POST /v1/proposals
• POST /v1/proposals/update
• POST /v1/proposals/:id/accept
• POST /v1/proposals/:id/reject

デフォルトのファイルベースの提案ストアは、選択したルートまたはプロジェクト内の .okf-proposals に提案 JSON を書き込みます。受理された提案は、選択したローカルルートに Markdown の概念を書き込みます。

POST /v1/concepts/validate と POST /v1/concepts/suggest-path は何も永続化しません。POST /v1/proposals が永続化するのは提案レコードのみです。概念の Markdown ファイルを書き込むのは POST /v1/proposals/:id/accept のみです。

リモートバンドル

リモートバンドルを使うと、あるワークスペースから、別のリポジトリが公開している概念をベンダー化せずに利用できます。ホストに依存しない構成にするには、任意の Git ホストから OKF リポジトリをクローンまたはマウントし、そのディレクトリを --root で指定します。転送と同期は OKF 仕様の対象外です。

サポート対象のソース：

• 公開 GitHub リポジトリのツリー URL：https://github.com/<owner>/<repo>/tree/<ref>/<path>

リモート読み込み：

• ツリーを一覧表示し、選択された .md ドキュメントを先に取得してから、明示的に参照されたバンドル内のアセットのみを取得します
• 解決されたリビジョンのメタデータ、SHA256 ダイジェスト、ドキュメント／アセットのバイト数、および未解決の参照を記録します
• リモートパスを一覧表示しますが、参照されていない .sql、.py、またはバイナリファイルの内容はダウンロードしません
• 各リモートバンドルを、設定されたバンドル ID の配下に保持します
• include と exclude のフィルターをサポートします
• リモートバンドル内の Markdown リンクを解決します
• ファイル数とバイト数の上限を適用します
• リモートリポジトリのコードを実行しません

CLI の例：

okf --remote-bundle shared=https://github.com/example/okf-atlas/tree/main/bundles/shared --inspect
okf --project okf.project.yaml --remote-bundle vendor=https://github.com/example/vendor-okf/tree/main/bundles/catalog validate

MCP ランタイムでの読み込み：

load_remote_bundle を呼び出す前に、--allow-remote-tool を指定して MCP サーバーを起動します。

{
  "name": "load_remote_bundle",
  "arguments": {
    "id": "shared",
    "url": "https://github.com/example/okf-atlas/tree/main/bundles/shared",
    "include": ["public/**"]
  }
}

読み込まれた内容を確認するには、list_remote_bundles を使用します。

構造化検索

search_concepts は次の項目を受け付けます。

• query
• bundle
• types
• tagsAny
• tagsAll
• pathPrefix
• frontmatter
• linkedTo
• linkedFrom
• relationType
• orphanOnly
• statuses
• trustTiers
• freshness と決定的な asOf
• hasSources
• runtime と attestationReady
• generatedBy と verifiedBy
• detail（デフォルトは compact、または full）
• limit
• offset

list_concepts もテキストの query を受け付け、一覧表示フィルターと組み合わせて適用します。テキスト検索では大文字と小文字を区別せずにトークン化し、順序に関係なくクエリ内のすべての語句を必要とします。BM25+ は、タイトル、タイプ、タグ、エイリアス、説明、パス、本文の一致度に基づいて順位付けします。フロントマターは完全一致の構造化フィルターで利用できますが、テキストインデックスにはコピーされません。スコアは結果セット内で相対的なものであり、バージョンをまたいで安定した尺度ではありません。コンパクトな結果には uri、title、type、description のみが含まれます。タイトル、タイプ、説明には上限が設けられていますが、完全な結果は情報を損ないません。

クエリは512文字、16語に制限されています。コード識別子とドメイン用語をそのまま扱えるよう、接頭辞展開、ファジーマッチング、ステミング、ストップワード除去は意図的に無効化されています。句読点のみのクエリは一致する結果を返しません。タグとタイプは大文字と小文字を区別せずに照合されます。任意のフロントマターフィルターは、スカラー値の完全一致と、配列に値が含まれるかどうかの照合をサポートします。relationType は、指定したタイプの出方向のリレーションを持つコンセプトを選択します。

SDK の回帰テストスイートでは、実際にシリアライズされた MCP テキストから、中立的な4ステップのリサーチ経路の予算も算出します。これは UTF-8 バイト数を4で割った決定的な推定値であり、モデルの正確なトークナイザーや課金カウントではありません。また、コンパクト出力の絶対予算と、コンパクト出力と完全出力の比率の両方を検証します。

例：

{
  "query": "catalog",
  "types": ["API Route"],
  "tagsAll": ["api", "orders"],
  "limit": 10
}

ローカルで関連性とパフォーマンスを確認するには、バンドルのルートと、任意で { "query": "...", "expected": "path/or/concept-id" } 形式の要素を含む JSON 配列の判定データを指定して、パッケージに含まれない開発用ベンチマークを実行します。

node --expose-gc scripts/search-benchmark.js \
  --root /path/to/okf \
  --qrels /path/to/qrels.json

OKF と検索インデックスのビルド時間、保持ヒープ／RSS、クエリレイテンシの p50／p95、Recall@10、MRR@10、代表的な順位を報告します。検索インデックスはプロセス内に保持され、解析済み OKF インデックスをキーとしているため、リモートからの読み込みや承認済みの提案には自動的に新しいインデックスが割り当てられます。

グラフの動作

okf-mcp のグラフ投影では、Markdown リンクは markdown_link エッジに、拡張の relations は型付きの relation エッジに、標準の v0.2 のパス値フィールドは resource、source、computation、executor、attester エッジになります。内部のコンセプト参照は正規ノードに解決され、明示的に参照された Markdown 以外のファイルは okf-mcp の okf-asset:// ノードに解決されます。URL とスコープ記述子は、取得されない外部ノードまたは不透明なリーフノードのままです。

ナビゲーションを便利にするため、okf-mcp は、同じパスのドキュメントが見つからない場合に、ネストされたバンドルディレクトリへのリンクを、そのディレクトリに予約された index.md に解決します。これはローカルおよびリモートのバンドルと、提案の作成時に行う候補の検証に適用されます。

グラフツールはサイズが制限された JSON を返します。

{
  "nodes": [
    {
      "id": "okf://app/routes/order-status",
      "bundle": "app",
      "path": "routes/order-status.md",
      "type": "API Route",
      "title": "Order Status Route",
      "tags": ["api", "orders"],
      "description": "Serves order status state."
    }
  ],
  "edges": [],
  "warnings": []
}

まず graph_summary を使って、ライフサイクル、信頼度、新しさ、ランタイム、準備状況、エッジの種類ごとの件数を確認します。グラフツールは edgeKinds を受け付けます。リーフノードが必要な場合は、includeExternal: true または includeAssets: true を渡してください。

デフォルトのリレーションタイプ：

• depends_on
• produces
• consumes
• persists_to
• materializes_to
• configured_by
• checked_by
• owned_by
• supersedes
• related_to

okf.project.yaml の relationTypes を使って、プロジェクト固有のリレーションタイプを追加できます。

bundles および plugins に指定するプロジェクトパスは、okf.project.yaml を含むディレクトリ内に収まる相対パスでなければなりません。絶対パスと ../ によるディレクトリ外への移動は拒否されます。

バンドルの include および exclude フィルターは、単純なパスパターンを使用します。

• services/order-status.md のようなファイルパスの完全一致
• archive/ のようなディレクトリの接頭辞
• 1つのパスセグメントに一致する *
• 任意の階層に一致する **

検証

validate、validate_bundle、validate_project は、個別の conformant フィールドと validForProject フィールドに加え、構造化された診断情報を返します。valid は validForProject の互換性エイリアスとして引き続き使用できます。

OKF 適合性では、対応するファイルが存在する場合、次の項目を確認します。

• 予約済みではない概念ドキュメントの、解析可能な YAML マッピング形式のフロントマター
• 空でない type
• index.md と log.md の予約済み構造

不明なフロントマターキーや不明な概念タイプ値があっても、適合性検証は失敗しません。YAML パーサーは、ネストされたマッピング、配列、ブロックスカラー、およびセーフ YAML コアスキーマで受け入れられるその他の構造をサポートします。重複キーとサポートされていないカスタムタグは拒否されます。

index.md ファイルの欠落やクロスリンクの破損があっても、OKF 適合性検証は失敗しません。strictLinks が影響するのは okf-mcp ワークスペースの有効性（validForProject）のみであり、規範的な conformant の結果には影響しません。

プロジェクトの有効性では、さらに次の項目を報告します。

• 重複した OKF URI
• 既定ではアドバイザリとして扱われる、壊れた内部 Markdown リンク。プロジェクトの strictLinks: true を設定するか、--strict-links を渡すと、プロジェクトは無効になります
• 無効な関係タイプ
• 関係の参照先の欠落
• 壊れた okf:// 関係の参照先
• 重複したバンドル ID
• 無効なプロジェクトパス、またはプロジェクトの範囲外に出るパス
• 設定されたバンドルルートの外部に解決されるリンク
• バンドルルートの欠落

サーバーは、不完全なバンドルからも有効な概念の提供を継続します。

オプションの v0.2 ファミリーは signals に正規化されます。不正な来歴、生成、検証、ライフサイクル、鮮度、または計算のメタデータはアドバイザリを生成しますが、第4の信頼ティアが作られることはありません。検証に失敗した場合は安全側に倒して unverified となり、ステータスがない場合は既定で stable となります。鮮度は、asOf 日付が指定されている場合、その日付に基づいて評価されます。作成時の検証は利用時よりも厳格であり、不正な既知の v0.2 フィールドを拒否します。

証明付き計算

inspect_attested_computation は、ランタイム、宣言されたパラメーター、承認されたインラインまたはファイル計算のダイジェスト、実行者のレシートフィールド、証明者の参照、インデックス化されたアセット、準備状態、診断情報を報告します。prepare_attested_computation は、宣言されたパラメーター名を検証し、値を返さずにダイジェストを返します。check_computation_receipt は、値を返したり、レシートを永続化したり、証明済みであると主張したりせずに、フィールドの有無を確認します。

okf-mcp には実行アダプターも証明アダプターもありません。計算、実行者のリソース、証明者のリソースを実行することはなく、外部のコントラクト URI をオンデマンドで取得することもありません。

CLI でも computation inspect|prepare|check-receipt、provenance、edge-kinds、asset を使用できます。機密値は --parameters-file <path|-> または --receipt-file <path|-> で指定してください。生のパラメーター JSON とレシート JSON は、意図的にプロセス引数での指定を拒否します。- を指定すると、標準入力から 1 つの JSON オブジェクトを読み込みます。アセットの読み取りでは、インデックス化された 1 MiB の上限まで --max-content-bytes を指定できます。

既存カタログを v0.2 に移行する

v0.2 仕様では、2 つのフォールバックにより v0.1 バンドルを引き続き利用できます。generated がない場合は従来の timestamp を使用し、sources がない場合は本文の従来の # Citations リストを使用します。okf-mcp は読み取り時にこれらのフォールバックを適用し、任意のレビュー専用変換ワークフローを提供します。

1 つのルートについて、移行の準備状況を確認し、書き込みを行わずに提案されるネイティブフィールドをプレビューするには、次のようにします。

okf --root /path/to/catalog migrate check
okf --root /path/to/catalog migrate preview \
  '{"metrics/revenue.md":{"by":"human:owner","confirmed":true}}'

任意の複数ルートプロジェクトモードでは、アクターマッピングの JSON より前にルート ID を指定します。

移行は意図的に慎重に行われます。

• ネイティブの generated フィールドと sources フィールドが常に優先されます
• 有効な timestamp は、正確な by アクターが明示的に確認された後にのみ、新しい generated: { by, at } マッピングにコピーされます
• # Citations が sources に変換されるのは、トップレベルの H1 セクションが 1 つだけあり、安全に解析できるリスト項目が少なくとも 1 つ含まれ、解析できない文章、ネストされたセクション、曖昧な項目、ルート外へ抜けるパスがない場合に限られます
• 互換性のため、従来のフィールドと引用の文章は保持されます
• --generated-path、ドキュメントフラグ、またはフロントマターの generated_file／generatedFile でマークされたコンセプトは、生成元を通じて変更する必要があります。リモートルートはレポートのみです
• 識別子の衝突、無効なドキュメント、安全でない参照、未解決のアセットがあると、バージョン宣言はブロックされます

okf_propose_v02_migration では、ローカルルートでの作成が必要です。レビュー用マニフェスト、影響を受けるファイルごとの提案、およびゲート付きのルート okf_version: "0.2" 提案を作成します。自動的に承認されるものはありません。すべての子提案が承認され、カタログ全体の検証に合格した後にのみ、ルート提案を承認できます。

ジェネレータープラグイン

ジェネレータープラグインは okf.project.yaml で設定し、generate で実行します。

組み込みプラグイン：

• filesystem：一致するソースファイルごとに 1 つのコンセプトを作成します。デフォルトでは Markdown ファイルを対象とします。
• json-spec：JSON ファイルごとに 1 つのコンセプトを作成し、宛先テーブルが存在する場合は persists_to 関係を出力できます。

生成された出力は通常の Markdown/YAML OKF であり、手動作成されたコンセプトと同じインデクサーで検証されます。

制限事項

• MCP トランスポートは stdio のみです。別途提供される HTTP 作成 API は、HTTP 経由の MCP ではありません。
• MCP プロトコルの互換性は、固定された公式 SDK v2 依存関係に準拠します。
• ファイルウォッチャーはありません。外部でファイルを変更した場合は、サーバーを再起動してください。MCP 作成機能を通じて承認されたコンセプトは、MCP サーバーのインデックスに直ちに反映されます。
• HTTP API は組み込みの軽量サーバーであり、完全なホスト型マルチテナントサービスではありません。
• OKF v0.2 の計算サポートは静的検査と事前チェックのみです。計算やアテスターは実行されません。