0dust/OKFy

Que fait OKFy ?

Aperçu

Utilisez OKFy pour transformer des sites web de documentation ou des dossiers Markdown locaux en bundles Open Knowledge Format locaux, puis exposez-les aux agents via un serveur MCP en lecture seule. Privilégiez npx -y okfy-ai dans les commandes générées afin que les clients puissent lancer le package publié sans installation globale.

Référence rapide

Objectif	Commande ou action
Enregistrer un site de documentation et afficher la configuration	npx -y okfy-ai init <nom> <url> --client codex --max-pages 100 --max-depth 4
Importer du Markdown local	npx -y okfy-ai import ./docs --out ./docs-okf --source-name "Documentation du projet"
Prouver une source pour une tâche	npx -y okfy-ai activate <nom-ou-bundle> --client codex --task "<tâche>" --out okfy-activation
Aperçu de l'état et du graphe	npx -y okfy-ai map <nom-ou-bundle> --out okfy-inspector.html
Diagnostiquer la configuration	npx -y okfy-ai doctor <nom> --client codex
Servir au MCP	npx -y okfy-ai serve <nom-ou-bundle> --mcp --auto-refresh

Workflow de configuration

1. Choisissez un nom de source court comme stripe, clerk ou project-docs.
2. Pour un site web de documentation, exécutez npx -y okfy-ai init <nom> <url> --client codex --max-pages 100 --max-depth 4.
3. Pour du Markdown local, exécutez import, puis validate, puis servez le chemin du bundle généré. N'ajoutez --force qu'après que l'utilisateur ait explicitement approuvé l'écrasement du répertoire de sortie.
4. Lorsque l'utilisateur souhaite une preuve avant des modifications de configuration, exécutez activate avec --task correspondant à sa question réelle. Le paquet comprend okfy-inspector.html, okfy-setup.md et okfy-proof.json.
5. Si la configuration échoue ou si le client MCP ne peut pas voir les outils, exécutez doctor avant de modifier manuellement la configuration du client.

Utilisation MCP

Lorsqu'un serveur MCP OKFy est disponible, utilisez les outils dans cet ordre :

1. bundle_summary pour inspecter l'état de validation, la fraîcheur, les sources disponibles et les attentes des outils.
2. search_concepts avec les termes de la tâche de l'utilisateur. Utilisez des filtres source dans les espaces de travail multi-sources lorsque la source de documentation pertinente est connue.
3. read_concept pour les concepts les plus pertinents, en gardant les lectures petites avant de les étendre.
4. get_neighbors lorsque la réponse dépend de concepts liés, de liens retour, de prérequis ou de pages API/référence à proximité.
5. Citez les URL source ou les champs de ressource révélés par les résultats de concept.

Commencez par des recherches étroites, puis élargissez uniquement lorsque les résultats sont maigres. Dans les espaces de travail, transmettez à la fois source et id à read_concept lorsque les identifiants de concept sont ambigus.

Espaces de travail

Servez plusieurs sources enregistrées via un seul serveur MCP lorsqu'une tâche couvre une pile :

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

Filtrez ensuite les recherches :

{ "query": "sessions de paiement", "source": "stripe", "limit": 5 }

Utilisez les filtres source chaque fois que l'utilisateur nomme le produit, l'API, le framework ou la source de documentation. Si l'utilisateur pose une question sur l'ensemble de la pile, recherchez d'abord l'espace de travail sans filtre, puis utilisez des lectures par source pour plus de précision.

Règles de sécurité

• Les outils MCP sont en lecture seule. L'auto-rafraîchissement est une maintenance côté serveur pour les sources enregistrées, et non un outil d'écriture appelable par un agent.
• N'utilisez pas npx okfy ; utilisez npx -y okfy-ai pour les commandes sans installation.
• N'exécutez pas serve --mcp comme une session de terminal bavarde normale. Les clients MCP le lancent en tant que sous-processus stdio.
• Ne contournez pas les valeurs par défaut de sécurité du crawler, les protections de réseau privé ou les gardes --force dangereuses, sauf si l'utilisateur accepte explicitement le risque.
• Ne modifiez pas manuellement la configuration du client en premier lorsque init, activate ou doctor peuvent produire ou vérifier la commande/configuration exacte.

Erreurs courantes

Erreur	Correction
Traiter OKFy comme un index hébergé	Gardez le workflow local : les fichiers bundle, le MCP stdio et les URL source restent inspectables.
Lire chaque concept après une recherche	Lisez d'abord les meilleures correspondances, puis utilisez les voisins pour vous étendre uniquement là où c'est nécessaire.
Ignorer les noms de source d'espace de travail	Utilisez les filtres source et les lectures qualifiées par source pour les bundles multi-sources.
Sauter la preuve	Utilisez activate --task lorsque l'utilisateur a besoin de confiance avant de câbler le MCP.
Déboguer la configuration à l'aveugle	Exécutez doctor <nom> --client codex et suivez sa prochaine commande de réparation.