fxbin/star-knowledge-base

Que fait star-knowledge-base ?

Transformez vos GitHub Stars en une boîte à outils de code personnelle interrogeable par un agent | MCP + Agent Skill + GitHub Pages

Présentation

star-knowledge-base est une compétence d'agent qui convertit vos étoiles GitHub en une base de connaissances sémantique, accessible à n'importe quel agent d'IA (Claude Code, Cursor, Codex, etc.). Au lieu de parcourir manuellement vos centaines de Stars, vous pouvez désormais laisser votre agent rechercher des projets pertinents, des extraits de code ou des concepts directement à partir de vos marque-pages.

Fonctionnalités principales

• Indexation automatique des Stars : synchronisez vos GitHub Stars et indexez leurs READMEs, descriptions et métadonnées
• Recherche sémantique vectorielle : utilisez des embeddings pour trouver les projets les plus pertinents par similarité de sens
• MCP (Model Context Protocol) : exposez la base de connaissances comme un outil MCP que tout agent compatible peut invoquer
• Déploiement GitHub Pages : hébergez la base de connaissances sous forme de site statique consultable par les agents
• Portabilité : fonctionne avec tous les agents prenant en charge les outils MCP (Claude Code, Cursor, Codex, etc.)

Utilisation

Prérequis

• Node.js 18+
• Un jeton d'accès GitHub avec le scope repo ou public_repo
• npx pour exécuter les scripts sans installation

Installation rapide

# Cloner le dépôt
git clone https://github.com/fxbin/star-knowledge-base.git
cd star-knowledge-base

# Installer les dépendances
npm install

# Configurer vos variables d'environnement
cp .env.example .env
# Éditez .env : ajoutez votre GITHUB_TOKEN

Configuration

Éditez le fichier .env :

GITHUB_TOKEN=ghp_votre_token_ici
GITHUB_USERNAME=votre_nom_utilisateur
# Optionnel : filtrer par étoiles minimales
MIN_STARS=10
OUTPUT_DIR=./knowledge-base

Synchronisation et indexation

# Récupérer toutes vos Stars et les indexer dans une base vectorielle locale
npm run sync

# Lancer le serveur MCP pour que votre agent puisse interroger
npm run serve

Utilisation avec Claude Code

Dans votre projet Claude Code, ajoutez une entrée MCP :

{
  "mcpServers": {
    "star-knowledge-base": {
      "command": "npx",
      "args": ["-y", "@fxbin/star-knowledge-base"]
    }
  }
}

Puis dans votre conversation avec Claude Code :

"Recherche dans ma base Stars des projets liés aux agents d'IA" "Trouve une bibliothèque React pour la gestion d'état dans mes Stars"

Utilisation avec Cursor

Dans les paramètres de Cursor (.cursor/mcp.json), ajoutez :

{
  "mcpServers": {
    "star-knowledge-base": {
      "command": "npx",
      "args": ["-y", "@fxbin/star-knowledge-base"]
    }
  }
}

Utilisation avec Codex

Codex prend en charge MCP nativement. Référez-vous à la documentation Codex pour l'intégration.

Déploiement GitHub Pages

Si vous souhaitez exposer votre base de connaissances via une API REST publique (utile pour les agents distants) :

npm run build:pages
# Le répertoire `dist/` contient les fichiers statiques
# Poussez-le vers la branche `gh-pages` de votre dépôt

La base de connaissances sera alors disponible à l'adresse : https://votreusername.github.io/star-knowledge-base/knowledge

Architecture

Graphique :
[GitHub API] -> [Script de synchronisation] -> [Base vectorielle (FAISS/LanceDB)] -> [Serveur MCP] -> [Agent (Claude/Cursor/Codex)]

Le flux de données est le suivant :

1. Le script de synchronisation interroge l'API GitHub pour récupérer vos Stars
2. Chaque projet est nettoyé et son README est extrait
3. Les textes sont transformés en embeddings via un modèle léger (par défaut all-MiniLM-L6-v2)
4. Les embeddings sont stockés dans une base vectorielle locale (LanceDB ou FAISS)
5. Le serveur MCP expose une interface search et get_project aux agents
6. L'agent interroge la base sémantiquement et reçoit les résultats pertinents

Dépannage

Problème : Error: GITHUB_TOKEN non défini Solution : Assurez-vous que votre fichier .env est présent et contient une ligne GITHUB_TOKEN=... valide.

Problème : Aucune Star trouvée Solution : Vérifiez que votre GITHUB_USERNAME est correct et que vous avez bien des dépôts marqués d'une étoile.

Problème : Le serveur MCP ne démarre pas Solution : Vérifiez que le port 3000 n'est pas déjà utilisé. Vous pouvez définir un port personnalisé via la variable d'environnement MCP_PORT.

Licence

MIT. Voir le fichier LICENSE pour plus de détails.

Contribution

Les contributions sont les bienvenues ! Ouvrez une issue ou une pull request sur GitHub.