0dust/OKFy

O que OKFy faz?

Visão Geral

Use o OKFy para transformar sites de documentação ou pastas Markdown locais em pacotes locais do Open Knowledge Format (OKF) e, em seguida, exponha-os a agentes por meio de um servidor MCP somente leitura. Prefira usar npx -y okfy-ai nos comandos gerados para que os clientes possam executar o pacote publicado sem uma instalação global.

Referência Rápida

Objetivo	Comando ou ação
Registrar um site de docs e imprimir setup	npx -y okfy-ai init <nome> <url> --client codex --max-pages 100 --max-depth 4
Importar Markdown local	npx -y okfy-ai import ./docs --out ./docs-okf --source-name "Project docs"
Comprovar fonte para uma tarefa	npx -y okfy-ai activate <nome-ou-bundle> --client codex --task "<tarefa>" --out okfy-activation
Visualizar prontidão e grafo	npx -y okfy-ai map <nome-ou-bundle> --out okfy-inspector.html
Diagnosticar configuração	npx -y okfy-ai doctor <nome> --client codex
Servir para MCP	npx -y okfy-ai serve <nome-ou-bundle> --mcp --auto-refresh

Fluxo de Trabalho de Configuração

1. Escolha um nome de fonte curto, como stripe, clerk ou project-docs.
2. Para um site de documentação, execute npx -y okfy-ai init <nome> <url> --client codex --max-pages 100 --max-depth 4.
3. Para Markdown local, execute import, depois validate, e então sirva o caminho do pacote gerado. Adicione --force somente após o usuário aprovar explicitamente a sobrescrita do diretório de saída.
4. Quando o usuário quiser prova antes de alterações de configuração, execute activate com --task correspondendo à pergunta real dele. O pacote inclui okfy-inspector.html, okfy-setup.md e okfy-proof.json.
5. Se a configuração falhar ou o cliente MCP não conseguir ver as ferramentas, execute doctor antes de editar a configuração do cliente manualmente.

Uso MCP

Quando um servidor MCP do OKFy estiver disponível, use as ferramentas nesta ordem:

1. bundle_summary para inspecionar status de validação, frescor, fontes disponíveis e expectativas das ferramentas.
2. search_concepts com os termos da tarefa do usuário. Use filtros source em workspaces multi-fontes quando a fonte de documentação relevante for conhecida.
3. read_concept para os conceitos mais relevantes, mantendo as leituras pequenas antes de expandir.
4. get_neighbors quando a resposta depender de conceitos vinculados, backlinks, pré-requisitos ou páginas de API/referência próximas.
5. Cite as URLs de origem ou campos de recurso trazidos à tona pelos resultados dos conceitos.

Comece com buscas restritas e amplie apenas quando os resultados forem escassos. Em workspaces, passe source e id para read_concept quando os IDs dos conceitos forem ambíguos.

Workspaces

Sirva várias fontes registradas por meio de um servidor MCP quando uma tarefa abranger uma pilha de tecnologias:

npx -y okfy-ai serve stripe clerk --mcp --auto-refresh

Em seguida, filtre as buscas:

{ "query": "sessões de checkout", "source": "stripe", "limit": 5 }

Use filtros source sempre que o usuário nomear o produto, API, framework ou fonte de documentação. Se o usuário perguntar sobre toda a pilha, pesquise o workspace sem filtro primeiro e, em seguida, use leituras por fonte para precisão.

Regras de Segurança

• As ferramentas MCP são somente leitura. A atualização automática (auto-refresh) é uma manutenção no lado do servidor para fontes registradas, não uma ferramenta de escrita acionável pelo agente.
• Não use npx okfy; use npx -y okfy-ai para comandos sem instalação.
• Não execute serve --mcp como uma sessão de terminal normal e interativa. Clientes MCP o iniciam como um subprocesso stdio.
• Não ignore os padrões de segurança do crawler, proteções de rede privada ou proteções inseguras de --force a menos que o usuário aceite explicitamente o risco.
• Não edite a configuração do cliente manualmente primeiro quando init, activate ou doctor puderem produzir ou verificar o comando/configuração exato.

Erros Comuns

Erro	Correção
Tratar OKFy como um índice hospedado	Mantenha o fluxo de trabalho local: arquivos de pacote, stdio MCP e URLs de fonte permanecem inspecionáveis.
Ler todo conceito após a busca	Leia os primeiros resultados mais relevantes primeiro e, em seguida, use vizinhos para expandir apenas onde necessário.
Ignorar nomes de fonte do workspace	Use filtros source e leituras qualificadas por fonte para pacotes multi-fontes.
Pular a prova	Use activate --task quando o usuário precisar de confiança antes de conectar o MCP.
Depurar configuração às cegas	Execute doctor <nome> --client codex e siga o próximo comando de reparo.