okf-mcp

이 저장소는 엔터프라이즈 빠른 롤아웃 워크플로를 위해 원본 mhdaves/okf-mcp 프로젝트를 확장합니다. 원본 프로젝트와 그 기여자는 MIT 라이선스에 따라 크레딧이 유지됩니다.

okf-mcp는 Open Knowledge Format v0.2를 위한 로컬 우선 소비자, 검증기, 그래프 인덱스, CLI 및 MCP 서버입니다.

YAML frontmatter를 포함한 Markdown 파일로 구성된 OKF 번들 디렉터리를 소비합니다. 선택적 워크스페이스 모드는 여러 번들을 연합할 수 있습니다. 개념은 CLI 명령과 MCP 리소스 및 도구를 통해 노출되며, 검증, 구조화 검색, 그래프 탐색, 출처 조사, 제안 기반 작성을 수행합니다.

핵심은 의도적으로 데이터베이스, 임베딩, 빌드 단계, 또는 호스팅 서비스 의존성이 없습니다. 안전한 YAML에는 js-yaml, Markdown 구조에는 CommonMark, 인메모리 BM25+ 텍스트 검색에는 MiniSearch, stdio MCP에는 공식 Model Context Protocol TypeScript SDK v2를 사용합니다. 로컬 루트 모드는 네트워크 호출을 하지 않습니다. 선택적 원격 로딩은 공개 Markdown 개념과 명시적으로 참조된 비활성 에셋만 GitHub에서 가져옵니다. v0.2 계산 지원은 어떤 것도 코드를 실행하거나 수신 증명(attestation receipt)을 하지 않습니다.

OKF v0.2 지원 및 확장

OKF v0.2는 의도적으로 이식 가능한 파일 형식을 명시하며, 서빙 또는 쿼리 런타임을 명시하지 않습니다. okf-mcp는 그 경계를 명확히 유지합니다:

다음은 형식의 요구 사항이 아닌 okf-mcp 확장입니다:

• CLI, MCP 및 HTTP 인터페이스; 인메모리 검색 및 그래프 뷰

• 선택적 다중 번들 okf.project.yaml 워크스페이스 및 타입이 있는 relations

• 호가성 id, aliases, okf:// 로케이터

• 명시적 수락을 포함한 제안 기반 제작

• 제한된 GitHub 원격 로딩 및 명시적으로 매핑된 고정 Git 소스

• 생성기 플러그인 및 strictLinks와 같은 더 엄격한 옵트인 프로젝트 정책

Related MCP server: okf-wiki

설치 및 실행

Node 22 이상이 필요합니다.

npm 레지스트리 없이 소스에서 실행

내부 npm 레지스트리는 필요하지 않습니다. 빌드 머지에서 종속성을 한 번 설치한 다음 node_modules를 포함한 전체 런타임 디렉터리를 배포하십시오:

git clone https://github.com/doctormacky/okf-mcp.git
cd okf-mcp
npm ci --omit=dev
node bin/okf-mcp.js --version

그런 다음 런타임을 에이전트 호스트로 복사하여 직접 호출할 수 있습니다:

node /opt/okf-mcp/bin/okf-mcp.js --version
node /opt/okf-mcp/bin/okf-mcp.js knowledge --help

안정적인 명령을 사용하려면 /usr/local/bin/okf에 작은 래퍼를 설치하십시오:

#!/usr/bin/env bash
set -euo pipefail
exec node /opt/okf-mcp/bin/okf-mcp.js "$@"

에이전트 Skill은 이 명령과 그 버전을 확인하지만, 런타임을 자동으로 설치하거나 업그레이드하지 않습니다.

GitHub 릴리스에서 설치합니다:

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

이 포크는 현재 npm 레지스트리가 아닌 소스에서 배포됩니다. 재현 가능한 배포를 위해 Git 커밋 또는 릴리스 아카이브를 핀하십시오. 업스트림 npm 패키지는 업스트림 전용 기능에서 계속 사용할 수 있지만, 이 포크의 호스팅 롤아웃 확장은 포함되지 않습니다.

git clone https://github.com/doctormacky/okf-mcp.git
cd okf-mcp
git checkout <commit-or-tag>
npm ci --omit=dev

현재 소스 브랜치에서 작업하려면:

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

--root은 하나의 로컬 OKF 번들 디렉터리를 받으며, 단일 번들에서 권장되는 okf-mcp 인터페이스입니다. 각 개념의 이식 가능한 정체성은 해당 루트 안에서 확장자가 없는 경로입니다.

--bundle은 경로 또는 id=path를 받습니다. 여러 플래그는 계속 지원됩니다. --project 및 해당 bundles: 목록은 OKF v0.2의 일부가 아니라 선택적 okf-mcp 연합/작성 확장입니다.

--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/bundles/okf-mcp validate
okf --root okf/bundles/okf-mcp search "proposal"
okf --root okf/bundles/okf-mcp concept overview/okf-mcp

이 릴리스에서 참조 번들을 직접 로드하십시오:

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

소스 런타임 아카이브에는 okf.project.yaml과 전체 참조 번들이 모두 포함됩니다.

선택적 다중 번들 프로젝트 구성

하나의 프로세스가 여러 루트를 연합하거나, 생성기를 구성하거나, 프로젝트 전반의 지침 어휘를 강제해야 하는 경우에만 okf.project.yaml을 사용하세요:

project: Example
strictLinks: false
bundles:
  - id: app
    root: okf/bundles/app
    include: ["**/*.md"]
    exclude: ["archive/**"]
  - id: data
    root: okf/bundles/data
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

프로젝트 명령을 실행합니다:

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

• serve

serve의 옵션:

• --host <host>: 바인딩 호스트, 기본값 127.0.0.1

• --port <port>: 바인딩 포트, 기본값 8765

• --write-token <token>: 쓰기 엔드포인트에 대한 bearer 토큰; 기본값은 `OKF_WRITE_TOKEN``입니다.

• --proposal-root <path>: 제안 JSON 디렉터리, 기본값은 선택한 로컬 루트 또는 프로젝트 아래 .okf-proposals입니다.

MCP 클라이언트 구성

이 포크는 소스로 배포됩니다. MCP 클라이언트를 체크 아웃된 실행 파일의 절대 경로를 지정하십시오.

클라이언트 구성 예:

{
  "mcpServers": {
    "okf": {
      "command": "node",
      "args": [
        "/absolute/path/to/okf-mcp/bin/okf-mcp.js",
        "--root",
        "/absolute/path/to/okf",
        "mcp"
      ]
    }
  }
}

프로젝트 구성 모드: 읽기 전용 프로젝트 헬퍼만 제공하고 제안 변경은 하지 않습니다.

{
  "mcpServers": {
    "okf": {
      "command": "node",
      "args": [
        "/absolute/path/to/okf-mcp/bin/okf-mcp.js",
        "--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 개정판과 SDK의 2025년대 클라이언트용 호환 경로(2025-11-25 포함)를 제공합니다. SDK는 프로토콜 협상, 프레이밍, 리소스 디스패치, 도구 디스패치 및 광고된 스키마 검증을 담당합니다.

알려진 도구에서 예상되는 실패(누락된 개념, 읽기 전용 번들, 실패한 원격 페치, 잘못된 인수 또는 제안 충돌)는 isError: true로 지정된 MCP 도구 결과로 반환됩니다. 활성화되지 않는 도구에 대한 호출는 SDK 디스패치에서 거부됩니다. 의도하지 않은 구현 오류는 내부 세부 정보를 노출하지 않도록 차단됩니다.

MCP 레지스트리 메타데이터

server.json은 이 포크의 소스 패키지 정체성과 stdio MCP 엔트리를 io.github.doctormacky/okf-mcp로 설명합니다. 메타데이터는 소스 패키지와 동기화되어 향후 레지스트리 게시에 사용될 수 있습니다. 그러나 이 포크는 현재 소스로 설치됩니다. 클라이언트는 절대 OKF 루트를 --root를 통해 전달하고 고정된 mcp 명령을 추가해야 합니다.

개념 정체성 및 확장

Concept ID는 번들-상대 Markdown 경로에서 .md를 제거한 것입니다. 이 확장자가 없는 경로는 휴대용 OKF 정체성입니다. okf-mcp는 워크스페이스 범위의 호환 로케이터도 노출합니다.

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

이전 .md URI와 유효한 사용자 정의 id는 호환 조회 별칭으로 남습니다. 단일 Concept 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 extension을 추가하세요.

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을 읽습니다. 이것들은 지저분한 작업 트리를 읽거나 가져오지 않습니다. 누락된 매핑 및 고정되지 않은 개정은 표시되지만 사용할 수 없습니다. 저장소 매핑은 일반 체크아웃, bare 저장소 또는 마운트된 경로를 가리킬 수 있습니다. 자격 증명과 로컬 경로는 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

• 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와 human:<id>, process:<id>, 또는 provider/model 구문의 진실한 행위자를 요구합니다. 일반적인 단일 루트 모드에서 호출자는 bundle을 생략합니다. bundle은 여러 프로젝트 루트를 선택할 때만 필요합니다. 원격 루트는 읽기 전용으로 유지됩니다.

일반 개념 도구는 Attested Computation 계약을 만들거나 변경할 수 없습니다. okf_propose_attested_computation은 추가로 --allow-computation-authoring이 필요하며, 해당 개념에 대한 하나의 조정된 검토 제안과 외부 컴퓨테이션 파일을 함께 만듭니다.

라이브 개념 저작

직접 쓰기 기능을 가진 서버는 MCP 클라이언트/사용자 승인 경계만으로 충분한 검토가 이루어질 때 시작하십시오:

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

에이전트는 읽기 전용 배치 검증기 하나와 파괴적 적용 도구 하나를 보게 됩니다. YAML 대신 구조화된 개념 필드를 제공하며, OKF는 호환 가능한 Markdown frontmatter를 직렬화하고 구성된 generated.by와 배치 전체에 대한 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" }
        ]
      }
    ]
  }
}

생성 경로는 선택 사항입니다. 서버는 먼저 요청된 prefix 내의 기존 같은 종류의 개념에서 강력한 우세한 디렉터리 규칙을 사용한 다음, 결정적 type/title slugs로 폴백합니다. okf_suggest_concept_path는 전략, 증거, 경로 사용 가능 여부, 같은 종류/제목 일치 항목을 보고하므로, 사용 가능한 파일명이 안전한 중복으로 오인되지 않습니다. 업데이트는 기존 uri를 식별합니다. 만료된 위치 항목은 제한된 가능한 대체 후보를 반환하며, 스칼라 필드는 기존 값을 대체하고 tags, sources, relations는 명시적 add/remove 패치를 사용합니다. metadata는 확장 frontmatter를 전달하지만 신원, 생성, 컬렉션 또는 방대한 양식 필드를 재정의할 수 없습니다. 경로와 URI는 업데이트 중에 변경할 수 없습니다. 개념 이동은 휴대형 신원을 변경하므로 별도의 의도적으로 지원되지 않는 작업으로 남습니다.

모든 1–100개 항목은 배치 단위로 하나의 미래 그래프로 검증되므로 함께 생성된 파고물이 서로 참조할 수 있고, 같은 종류/제목 충돌은 생성과 업데이트 모두에서 감지됩니다. okf_validate_changes를 의도한 전체 배치와 함께 호출하면 파일을 쓰지 않고 검증 시점의 미리보기를 받습니다. 검증와 적용은 같은 플래너를 공유하며, 적용은 미리보기 이후 리비전과 Git 상태가 변경될 수 있으므로 쓰기 큐 아래에서 모든 검사를 다시 진행합니다. 간결한 영수증은 v0.8 기본이며, v0.7 계획 레이아웃이 필요하면 detail: "full"을 전달하십시오. 효과는 구조화된 관계를 노출하고 서버 관리형 생성 출처를 실제 changedFields와 분리합니다.

서버는 모든 후보가 유효하고, 리비전 검사가 여전히 일치하며, 모든 대상이 하나의 쓰기 가능한 번들 안에 남아 있을 때만 아무것도 쓰지 않습니다. 프로세스 생성 데이터, 생성 출력 디렉터리, .git/** 같은 숨김/제어 평면 경로, 예약 파일, Attested Computation 계약은 라이브 쓰기 대상이 아닙니다. 롤백은 각 복원 직전에 리비전을 검사하고 감지된 교체를 부분적인 rollback_conflict로 보고합니다. 이 보호는 문서화된 단일 외부 쓰기 요구 사항 아래 최선 노력으로 제공되며, 프로세스 간 compare-and-swap 레퍼런스 변환을 보장하지 않습니다.

--git-commit을 서버 정책으로 추가하면 성공한 배치마다 커밋 하나를 만듭니다. 감지된 Git 워크트리는 커밋 전에 완전히 깨끗해야 하고 구성된 신원이 있어야 합니다. 활성 Git 필터 속성과 assume-unchanged/skip-worktree 인덱스 플래그는 작업을 차단하므로 검증이 설정된 필터를 실행하거나 숨겨진 사용자 변경을 간시할 수 없습니다. replace-objects 추적은 비활성화되어 숨은 대체 기록이 부모 트리를 바꿀 수 없습니다. 서버는 검증된 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."
  }
}

생략된 frontmatter 필드와 법문 본문은 보존됩니다. 개념 URI는 업데이트에서 변경할 수 없습니다. 각 업데이트 제안은 소스 파일 리비전을 기록하고, 수락은 파일 교체 직전에 변경을 다시 확인하므로 감지된 동시 변경은 거부됩니다.

안전 규칙:

• 개념 경로는 쓰기 가능한 번들 내의 숨김 없는 안전한 상대 .md 경로여야 함

• 개념 쓰기는 쓰기 가능한 번들 아래 심볼릭 링크를 통과할 수 없음

• 누락된 하위 디렉터리는 제안이 수락될 때만 생성됨

• index.md와 log.md는 개념으로 기록할 수 없음

• 중복 경로와 중복 okf:// ID는 거부됨

• 업데이트가 개념 신원을 변경할 수 없고, 제안 생성 후 감지된 변경을 거부함

• 잘못된 ID, 잘못된 관계 타입, 유효한 내부 OKF 관계 오류는 검증 실패

• repo://... 같은 외부 관계 대상은 허용됨

• 직접 배치는 단일 프로세스 내에서 직렬화되고 검증된 결합 미래 그래프를 게시하기 전에 확인

• 독립 프로세스는 여전히 별도의 단일 쓰기자 요구 사항을 요구함

HTTP API

두 가지 HTTP 모드가 있습니다:

• hosted: 권장 엔터프라이즈 신속 롤아웃 모드로 인증된 MCP Streamable HTTP와 불변 스냅샷 롤아웃을 한 프로세스로 결합합니다.

• serve: 아래에 설명하는 기존의 로컬 제안 중심 REST API이며, MCP 트랜스포트가 아니며 불변 롤아웃 워크플로우를 제공하지 않습니다.

HTTP 서버를 시작합니다:

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

읽기/검증 엔드포인트:

• GET /health

• GET /v1/assets

• 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는 제안 레코드만 유지합니다. 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

• path

• frontmatter

• linkedTo

• linkedFrom

• relationType

• orphanOnly

• statuses

• trustTiers

• freshness 및 결정적 asOf

• hasSources

• runtime 및 attestationReady

• generatedBy 및 verifiedBy

• detail (compact 기본, 또는 full)

• limit

• offset

list_concepts는 텍스트 query도 함께 받아들이며, 이를 리스트 필터와 함께 적용합니다. 텍스트 검색은 대소문자를 구분하지 않는 토큰화를 사용하며, 순서와 무관하게 모든 쿼리 용어를 요구합니다. BM25+는 제목, 유형, 태그, 별칭, 설명, 경로, 본문 매칭을 순위화하며, frontmatter는 정확한 구조화 필터를 통해서는 계속 사용할 수 있지만 텍스트 인덱스에는 복사되지 않습니다. 점수는 결과 집합 내에서 상대적이며, 버전 간 안정적인 척도가 아닙니다. 컴팩트 결과에는 uri, title, type, description만 포함되며, 제목, 유형, 설명에는 크기 제한이 있고 전체(full) 결과는 무손실로 유지됩니다.

쿼리는 512자와 16개 용어로 제한됩니다. 접두어 확장, 퍼지 매칭, 형태소 분석, 불용어 제거는 의도적으로 비활성화되어 있어 코드 식별자와 도메인 용어가 문자 그대로 유지됩니다. 구두점만으로 구성된 쿼리는 결과를 반환하지 않습니다. 태그와 유형은 대소문자를 구분하지 않고 매칭됩니다. 임의의 frontmatter 필터는 정확한 스칼라 매칭과 배열-포함(array-contains) 매칭을 지원합니다. relationType은 해당 유형의 나가는(outgoing) 관계를 가진 개념을 선택합니다.

SDK 회귀 테스트 스위트는 실제 직렬화된 MCP 텍스트에서 도출한 중립적인 4단계 연구 경로도 예산으로 잡습니다. UTF-8 바이트를 4로 나눈 값을 결정적 추정치로 사용하며, 정확한 모델 토크나이저나 과금 수치는 아닙니다. 절대 컴팩트 예산과 컴팩트/전체 비율을 모두 보호합니다.

예시:

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

로컬 관련성 및 성능 점검을 위해, 번들 루트와 선택적 JSON 배열의 { "query": "...", "expected": "path/or/concept-id" } 판정으로 패키징되지 않은 개발 벤치마크를 실행합니다:

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/)

• *: 경로 세그먼트 하나

• **: 중첩된 경로

검증

validate, validate_bundle, validate_project는 별도의 conformant와 validForProject 필드 plus 구조화된 진단 정보를 반환합니다. valid는 validForProject를 위한 호환 별칭으로 남습니다.

OKF 적합성은 해당 파일이 있을 때 다음을 다룹니다:

• 예약되지 않은 개념 문서에서 파싱 가능한 YAML 매핑 frontmatter

• 비어 있지 않은 type

• index.md와 log.md의 예약된 구조

알 수 없는 frontmatter 키와 알 수 없는 개념 유형 값은 적합성에 실패하지 않습니다. YAML 파서는 중첩 매핑, 배열, 블록 스칼라 및 안전한 YAML 코어 스키마가 받아들이는 기타 구조를 지원하며, 중복 키와 지원되지 않는 사용자 지정 태그는 거부됩니다.

누락된 index.md 파일과 끊어진 교차 링크는 OKF 적합성에 실패하지 않습니다. strictLinks는 OKF-MCP 작업 공간 유효성(validForProject)에만 영향을 주며, 규범적 conformant 결과에는 영향을 주지 않습니다.

프로젝트 유효성은 추가로 다음을 보고합니다:

• 중복 OKF URI

• 기본적으로 권고(advisory) 사항인 내부 Markdown 링크 끊어짐; 프로젝트 strictLinks: true로 설정하거나 --strict-links를 전달하면 프로젝트에 유효하지 않은 것으로 처리됨

• 유효하지 않은 관계 유형

• 누락된 관계 대상

• 끊긴 okf:// 관계 대상

• 중복 번들 ID

• 유효하지 않거나 경로를 이탈하는 프로젝트 경로

• 구성된 번들 루트 밖으로 확인되는 링크

• 누락된 번들 루트

서버는 일부 번들의 유효한 개념을 계속 제공합니다.

선택적 v0.2 패밀리는 signals로 정규화됩니다. 잘못된 형식의 프로비전, 생성, 검증, 라이프사이클, 신선도 또는 계산 메타데이터는 권고(advisory)를 생성하며 절대 네 번째 신뢰 등급을 만들지 않습니다. 검증은 unverified로 폐쇄 실패합니다. 상태가 없으면 기본값은 stable입니다. 신선도는 asOf가 제공되면 명시적 asOf 날짜로 평가됩니다. 작성은 소비보다 엄격하며 잘못된 형식의 알려진 v0.2 필드를 거부합니다.

Attested Computation

inspect_attested_computation은 런타임, 선언된 매개변수, 승인된 인라인 또는 파일 computation digest, executor receipt 필드, attester 참조, 인덱싱된 자산, 준비 상태 및 진단 정보를 보고합니다. prepare_attested_computation은 선언된 매개변수 이름을 확인하고 값을 반환하지 않고 digest를 반환합니다. check_computation_receipt는 값을 반환하지 않고 필드 존재 여부를 확인하며, receipt를 저장하거나 attestation을 주장하지 않습니다.

okf-mcp에는 실행 또는 attestation 어댑터가 없습니다. computation, executor 리소스, attester 리소스를 실행하지 않으며, 요청 시 외부 계약 URI를 가져오지도 않습니다.

CLI 대응은 computation inspect|prepare|check-receipt, provenance, edge-kinds, asset으로 사용할 수 있습니다. 민감한 값은 --parameters-file <path|-> 또는 --receipt-file <path|->로 공급하세요. 원시 매개변수 및 receipt JSON은 프로세스 인자에서 의도적으로 거부됩니다. -는 stdin에서 JSON 객체 하나를 읽습니다. 에셋 읽기는 인덱싱된 1 MiB 제한까지 --max-content-bytes를 받아들입니다.

기존 카탈로그를 v0.2로 마이그레이션

v0.2 사양은 두 가지 폴백을 통해 v0.1 번들을 계속 사용할 수 있게 합니다: generated가 없을 때 이전 timestamp, 그리고 sources가 없을 때 이전 본문 # Citations 목록. okf-mcp는 읽기 중 이러한 폴백을 적용하며 선택적 검토 전용 변환 워크플로를 제공합니다.

하나의 루트에 대해 마이그레이션 준비 상태를 검사하고 아무것도 쓰지 않고 제안된 네이티브 필드를 미리 보세요:

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는 하나의 최상위 H1 섹션에 안전하게 파싱 가능한 목록 항목이 최소 하나 이상 있고 구문 분석되지 않은 산문, 중첩 섹션, 모호한 항목 또는 경로 이탈이 없는 경우에만 sources가 됩니다

• 기존 필드와 인용 산문은 호환성을 위해 유지됩니다

• --generated-path, 문서 플래그 또는 generated_file/generatedFile frontmatter에 의해 표시된 개념은 생성기를 통해 변경해야 합니다; 원격 루트는 보고 전용입니다

• 신원 충돌, 잘못된 문서, 안전하지 않은 참조, 확인되지 않은 자산은 버전 선언을 차단합니다

okf_propose_v02_migration는 로컬 루트 작성을 요구합니다. 검토 매니페스트, 영향을 받은 파일당 하나의 제안, 그리고 게이팅된 루트 okf_version: "0.2" 제안을 생성합니다. 자동으로 승인되지는 않습니다. 루트 제안은 모든 하위 제안이 승인되고 전체 카탈로그가 검증된 후에만 승인할 수 있습니다.

생성기 플러그인

생성기 플러그인은 okf.project.yaml에서 구성되며 generate로 실행됩니다.

기본 제공 플러그인:

• filesystem: 매칭되는 소스 파일당 하나의 개념을 생성합니다. 기본값은 Markdown 파일입니다.

• json-spec: JSON 파일당 하나의 개념을 생성하며 대상 테이블이 있을 때 persists_to 관계를 방출할 수 있습니다.

생성된 출력은 일반 Markdown/YAML OKF이며 직접 작성한 개념과 동일한 인덱서로 검증됩니다.

제한 사항

• MCP는 stdio와 Streamable HTTP를 지원합니다. 인증된 통합 엔터프라이즈 프로필에는 hosted를 사용하세요. 독립형 mcp --http는 하위 수준 전송 모드이며 호스팅된 인증 또는 롤아웃 엔드포인트를 추가하지 않습니다.

• MCP 프로토콜 호환성은 고정된 공식 SDK v2 종속성을 따릅니다.

• 파일 감시기가 없습니다. 외부 파일 변경 후 서버를 다시 시작하세요. MCP 작성으로 승인된 개념은 MCP 서버 인덱스를 즉시 새로고칩니다.

• 호스티드 모드는 다중 프로세스가 아닌른 단일 프로세스, 단일 작가자 빨른 롤아웃 전개 서비스이지 분산 다중 테난트 제어 평면가 아. 같 은 생션 스토어에 대 해 다수 작가자를 일 시키지 마세 요.

• 구 성된 번들 루트 는 호 스티 드 모 드 에 서 최 선 노력 호 환 미 러 입 닉니 다. 불 변 생 성 물 이 제 공 원 입 닉니 다.

• OKF v0.2 계 산 지 원 은 정 적 검 사 및 사 전 검 사 만입 닉다. 계 산 이 나 attestor를 실행하지 않니 크다.