OKFy은(는) 무엇을 하나요?
개요
OKFy를 사용하여 문서 웹사이트나 로컬 Markdown 폴더를 로컬 Open Knowledge Format 번들로 변환한 후, 읽기 전용 MCP 서버를 통해 에이전트에 노출하세요. 생성된 명령어에서는 npx -y okfy-ai를 선호하여 클라이언트가 전역 설치 없이 게시된 패키지를 실행할 수 있도록 합니다.
빠른 참조
| 목표 | 명령어 또는 동작 |
|---|---|
| 문서 사이트 등록 및 설정 출력 | npx -y okfy-ai init <name> <url> --client codex --max-pages 100 --max-depth 4 |
| 로컬 Markdown 가져오기 | npx -y okfy-ai import ./docs --out ./docs-okf --source-name "프로젝트 문서" |
| 태스크에 대한 소스 증명 | npx -y okfy-ai activate <name-or-bundle> --client codex --task "<task>" --out okfy-activation |
| 준비 상태 및 그래프 미리보기 | npx -y okfy-ai map <name-or-bundle> --out okfy-inspector.html |
| 설정 진단 | npx -y okfy-ai doctor <name> --client codex |
| MCP에 서빙 | npx -y okfy-ai serve <name-or-bundle> --mcp --auto-refresh |
설정 워크플로우
stripe,clerk,project-docs와 같은 짧은 소스 이름을 선택합니다.- 문서 웹사이트의 경우
npx -y okfy-ai init <name> <url> --client codex --max-pages 100 --max-depth 4를 실행합니다. - 로컬 Markdown의 경우
import를 실행한 다음validate를 실행하고 생성된 번들 경로를 서빙합니다. 사용자가 출력 디렉토리 덮어쓰기를 명시적으로 승인한 경우에만--force를 추가합니다. - 사용자가 설정 변경 전에 증명을 원할 경우, 실제 질문과 일치하는
--task와 함께activate를 실행합니다. 패킷에는okfy-inspector.html,okfy-setup.md,okfy-proof.json이 포함됩니다. - 설정이 실패하거나 MCP 클라이언트가 도구를 볼 수 없는 경우, 클라이언트 구성을 수동으로 편집하기 전에
doctor를 실행합니다.
MCP 사용
OKFy MCP 서버를 사용할 수 있는 경우 다음 순서로 도구를 사용하세요:
bundle_summary를 사용하여 검증 상태, 최신 상태, 사용 가능한 소스 및 도구 기대치를 검사합니다.- 사용자의 태스크 용어로
search_concepts를 사용합니다. 관련 문서 소스를 알고 있는 경우 다중 소스 워크스페이스에서source필터를 사용합니다. - 가장 관련성 높은 개념에 대해
read_concept를 사용하되, 확장하기 전에 읽기를 작게 유지합니다. - 답변이 연결된 개념, 역링크, 전제 조건 또는 인접한 API/참조 페이지에 의존하는 경우
get_neighbors를 사용합니다. - 개념 결과에서 제공된 소스 URL 또는 리소스 필드를 인용합니다.
좁은 검색으로 시작하고 결과가 부족할 때만 범위를 넓힙니다. 워크스페이스에서 개념 ID가 모호한 경우 read_concept에 source와 id를 모두 전달합니다.
워크스페이스
태스크가 스택에 걸쳐 있는 경우 하나의 MCP 서버를 통해 여러 등록된 소스를 서빙합니다:
npx -y okfy-ai serve stripe clerk --mcp --auto-refresh
그런 다음 검색을 필터링합니다:
{ "query": "checkout sessions", "source": "stripe", "limit": 5 }
사용자가 제품, API, 프레임워크 또는 문서 소스를 언급할 때마다 source 필터를 사용하세요. 사용자가 스택 전반에 걸쳐 질문하는 경우, 먼저 필터 없이 워크스페이스를 검색한 다음, 정밀도를 위해 소스별 읽기를 사용합니다.
안전 규칙
- MCP 도구는 읽기 전용입니다. 자동 새로고침은 등록된 소스에 대한 서버 측 유지 관리이며, 에이전트가 호출 가능한 쓰기 도구가 아닙니다.
npx okfy를 사용하지 말고, 설치 없는 명령어를 위해npx -y okfy-ai를 사용하세요.- 일반적인 채팅 터미널 세션으로
serve --mcp를 실행하지 마세요. MCP 클라이언트는 이를 stdio 서브프로세스로 시작합니다. - 사용자가 명시적으로 위험을 수락하지 않는 한, 크롤러 안전 기본값, 개인 네트워크 보호 또는 안전하지 않은
--force가드를 우회하지 마세요. init,activate,doctor가 정확한 명령어/구성을 생성하거나 확인할 수 있는 경우, 먼저 클라이언트 구성을 수동으로 편집하지 마세요.
일반적인 실수
| 실수 | 해결 방법 |
|---|---|
| OKFy를 호스팅된 인덱스로 취급 | 워크플로우를 로컬로 유지: 번들 파일, MCP stdio, 소스 URL은 검사 가능한 상태로 남습니다. |
| 검색 후 모든 개념 읽기 | 먼저 상위 일치 항목을 읽고, 필요한 경우에만 이웃을 사용하여 확장합니다. |
| 워크스페이스 소스 이름 무시 | 다중 소스 번들의 경우 source 필터와 소스 한정 읽기를 사용합니다. |
| 증명 건너뛰기 | 사용자가 MCP를 연결하기 전에 확신이 필요할 때 activate --task를 사용합니다. |
| 설정을 맹목적으로 디버깅 | doctor <name> --client codex를 실행하고 다음 수리 명령어를 따릅니다. |