0dust/OKFy

¿Qué hace OKFy?

Descripción general

Usa OKFy para convertir sitios web de documentación o carpetas locales de Markdown en paquetes locales del Open Knowledge Format (OKF) y luego exponerlos a agentes a través de un servidor MCP de solo lectura. Prefiere npx -y okfy-ai en los comandos generados para que los clientes puedan ejecutar el paquete publicado sin una instalación global.

Referencia rápida

Objetivo	Comando o acción
Registrar un sitio de docs e imprimir configuración	npx -y okfy-ai init <nombre> <url> --client codex --max-pages 100 --max-depth 4
Importar Markdown local	npx -y okfy-ai import ./docs --out ./docs-okf --source-name "Documentación del proyecto"
Probar una fuente para una tarea	npx -y okfy-ai activate <nombre-o-paquete> --client codex --task "<tarea>" --out okfy-activation
Previsualizar estado y grafo	npx -y okfy-ai map <nombre-o-paquete> --out okfy-inspector.html
Diagnosticar configuración	npx -y okfy-ai doctor <nombre> --client codex
Servir a MCP	npx -y okfy-ai serve <nombre-o-paquete> --mcp --auto-refresh

Flujo de trabajo de configuración

1. Elige un nombre corto para la fuente, como stripe, clerk o project-docs.
2. Para un sitio web de documentación, ejecuta npx -y okfy-ai init <nombre> <url> --client codex --max-pages 100 --max-depth 4.
3. Para Markdown local, ejecuta import, luego validate, y luego sirve la ruta del paquete generado. Solo añade --force después de que el usuario apruebe explícitamente sobrescribir el directorio de salida.
4. Cuando el usuario quiera una prueba antes de realizar cambios en la configuración, ejecuta activate con --task que coincida con su pregunta real. El paquete incluye okfy-inspector.html, okfy-setup.md y okfy-proof.json.
5. Si la configuración falla o el cliente MCP no puede ver las herramientas, ejecuta doctor antes de editar manualmente la configuración del cliente.

Uso de MCP

Cuando un servidor MCP de OKFy esté disponible, usa las herramientas en este orden:

1. bundle_summary para inspeccionar el estado de validación, frescura, fuentes disponibles y expectativas de herramientas.
2. search_concepts con los términos de la tarea del usuario. Usa filtros source en espacios de trabajo con múltiples fuentes cuando se conozca la fuente de documentación relevante.
3. read_concept para los conceptos más relevantes, manteniendo las lecturas pequeñas antes de expandir.
4. get_neighbors cuando la respuesta dependa de conceptos enlazados, enlaces inversos, prerrequisitos o páginas cercanas de API/referencia.
5. Cita las URLs de origen o los campos de recurso que muestren los resultados del concepto.

Comienza con búsquedas estrechas y solo amplía cuando los resultados sean escasos. En espacios de trabajo, pasa tanto source como id a read_concept cuando los ids de concepto sean ambiguos.

Espacios de trabajo

Sirve múltiples fuentes registradas a través de un solo servidor MCP cuando una tarea abarca un stack:

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

Luego filtra las búsquedas:

{ "query": "checkout sessions", "source": "stripe", "limit": 5 }

Usa filtros source siempre que el usuario nombre el producto, API, framework o fuente de documentación. Si el usuario pregunta sobre el stack completo, busca primero en el espacio de trabajo sin filtro, luego usa lecturas por fuente para precisión.

Reglas de seguridad

• Las herramientas MCP son de solo lectura. La actualización automática es mantenimiento del lado del servidor para fuentes registradas, no una herramienta de escritura invocable por un agente.
• No uses npx okfy; usa npx -y okfy-ai para comandos sin instalación.
• No ejecutes serve --mcp como una sesión de terminal normal y conversacional. Los clientes MCP lo inician como un subproceso stdio.
• No omitas las opciones de seguridad predeterminadas del rastreador, las protecciones de red privada ni las protecciones inseguras de --force a menos que el usuario acepte explícitamente el riesgo.
• No edites manualmente la configuración del cliente primero cuando init, activate o doctor puedan producir o verificar el comando/configuración exactos.

Errores comunes

Error	Solución
Tratar OKFy como un índice alojado	Mantén el flujo de trabajo local: los archivos del paquete, MCP stdio y las URLs de origen permanecen inspeccionables.
Leer cada concepto después de una búsqueda	Lee primero las coincidencias principales, luego usa los vecinos para expandir solo donde sea necesario.
Ignorar nombres de fuente en espacios de trabajo	Usa filtros source y lecturas calificadas por fuente para paquetes con múltiples fuentes.
Omitir la prueba	Usa activate --task cuando el usuario necesite confianza antes de conectar MCP.
Depurar la configuración a ciegas	Ejecuta doctor <nombre> --client codex y sigue su siguiente comando de reparación.