Install
pipx install awesome-okf누구에게 맞나
- AI agent가 OKF(Open Knowledge Format) 리소스 카탈로그를 직접 조회하길 원하는 개발자 또는 agent 사용자: 카탈로그에는 OKF 관련 도구, 플러그인, skills, 제안, 문서가 들어 있습니다.
- 이미 MCP를 지원하는 클라이언트를 쓰며
search_catalog,get_catalog_entry같은 도구로 프로그래밍 방식 검색을 원하는 사람. - 자신의 콘텐츠를 OKF 카탈로그(Markdown 파일 + YAML frontmatter)로 바꾸고
myokf validate로 검증하려는 사람.
맞지 않는 경우:
- OKF 리소스 발견이나 변환이 필요 없고 다른 분야 데이터만 조회하려는 상황.
- README를 직접 편집하는 사람 — 공식은 README*.md가 생성물이라 손으로 고치면 안 되고,
data/catalog.yaml을 바꾼 뒤 다시 생성해야 한다고 명시합니다. - 공식이 설명하지 않은 부분(지원 클라이언트 목록, 변환 입력 언어 범위, 구체적 시스템 요구사항)은 이 페이지에서 추측하지 않으며 모두 미확인으로 표시합니다.
3분 만에 첫 시도
전제: 로컬에 Python 환경이 있고 pipx가 설치되어 있어야 합니다(공식 설치 방법). Python으로 구현된 CLI + MCP meta-server입니다.
-
설치: 터미널에서 실행
pipx install awesome-okf -
agent 연결: MCP server를 명령
awesome-okf-server로 MCP 클라이언트에 등록합니다(공식 설명은 "Connect it to your MCP client". 클라이언트별 구체 등록 경로는 증거에 없으므로 사용 중인 클라이언트 문서를 따르세요). -
낮은 위험의 읽기 전용 작업 실행: agent에게 「search_catalog로 카탈로그의 OKF 도구를 검색하고 앞의 몇 건을 반환해」라고 말합니다. 이 도구는 query/kind/limit 파라미터를 받으며 카탈로그 조회이고 쓰기를 만들지 않습니다.
성공 신호: agent가 카탈로그 항목을 반환하거나(get_catalog_entry / list_catalog 데이터 기반) catalog_stats 통계를 주면 meta-server가 연결된 것입니다.
주의: 첫 시도는 조회만 하세요. convert_to_okf와 scripts/convert-to-okf.py는 OKF 카탈로그 파일을 만드는 쓰기 동작입니다. 대상 경로를 확인하고 Markdown + YAML frontmatter 파일이 생긴다는 점을 안 뒤에 실행하세요.
사용 사례
사례 1: agent에게 OKF 리소스를 찾게 하기. 상황: OKF 생태계에 어떤 도구나 스킬이 있는지 알고 싶을 때. 연결된 agent에게 「search_catalog를 쓰고, query에 찾을 키워드를 넣고, kind로 유형을 거르고, limit으로 건수를 제어」라고 요청합니다. agent는 meta-server 검색 도구를 호출해 일치하는 도구/플러그인/skills/제안/문서 항목을 반환합니다. 통계는 catalog_stats로 볼 수 있습니다. 순수 조회이며 결과는 카탈로그 항목 자체입니다.
사례 2: 기존 콘텐츠를 OKF 카탈로그로 변환. 상황: 구조화된 텍스트(목록, JSON, 키-값, URL 목록)를 agent에 맞는 지식 형식으로 바꾸고 싶을 때. scripts/convert-to-okf.py를 사용하고, --format anything 모드는 파싱 체인(list → JSON → key-value → URLs → line-per-row)을 차례로 시도해 한 파서가 성공할 때까지 진행합니다. 확인할 수 있는 결과: YAML frontmatter가 있는 Markdown 파일 카탈로그가 생성되며 이후 myokf validate로 검증할 수 있습니다. 부작용: 이 단계는 디스크에 파일을 쓰고, 변환은 로컬 엔진이 수행합니다. 먼저 출력 디렉터리 위치를 확인하세요. 증거가 다루지 않은 점: convert_to_okf MCP 도구를 직접 호출해 같은 변환을 할 수 있는지, 변환 실패 시 구체 오류 동작.
사용 경계
- README*.md를 직접 편집하지 마세요: 생성물입니다. 항목을 바꾸려면
data/catalog.yaml을 편집한 뒤 다시 생성하세요. 공식은 보내기 전에awesome-okf validate와 pytest를 통과하라고 요구합니다. - 네트워크/파일 접근: 변환은 로컬 엔진(extraction done by local engines only)을 쓰며 외부 수집을 하지 않습니다. meta-server 자체의 네트워크 동작은 공식 설명이 없어 알 수 없음으로 표시합니다.
- 확인 포인트: 파일을 쓰는 동작(변환, 생성)은 먼저 대상 경로를 확인해야 합니다. 조회 도구(search_catalog, list_catalog, get_catalog_entry, catalog_stats)는 카탈로그 읽기이지만, 「파일을 쓰지 않고 명령을 실행하지 않는다」는 절대적 안전 결론을 뒷받침할 증거는 부족하므로 단정하지 않습니다.
- 실행 환경: pipx로 설치하는 Python 구현 CLI와 MCP meta-server이며 MCP 지원 클라이언트가 필요합니다. 공식은 어떤 MCP 클라이언트를 지원하는지 명시하지 않았습니다.
- 미확인 정보: 지원 자연어 범위, 각 MCP 클라이언트의 등록 세부사항, 시스템 의존성 버전은 공식 원문에 없습니다. 사용 전에 저장소의 최신 문서를 확인하세요.