GZOO Cortex MCP Server

GZOO Cortex

Graphe de connaissances local-first pour les développeurs. Surveille les fichiers de vos projets, extrait les entités et les relations à l'aide de LLM, et vous permet d'interroger tous vos projets en langage naturel.

« Quelles décisions d'architecture ai-je prises à travers mes projets ? »

Cortex trouve les décisions dans vos README, fichiers TypeScript, fichiers de configuration et exports de conversations — puis synthétise une réponse avec des citations sources.

Pourquoi

Vous travaillez sur plusieurs projets. Les décisions, les motifs et le contexte sont dispersés dans des centaines de fichiers. Vous oubliez ce que vous avez décidé il y a trois mois. Vous résolvez à nouveau des problèmes que vous avez déjà résolus dans un autre dépôt.

Cortex surveille les répertoires de vos projets, extrait automatiquement les connaissances et vous les restitue lorsque vous en avez besoin.

Ce qu'il fait

• Surveille les fichiers de vos projets (md, ts, js, py, json, yaml) pour détecter les changements
• Extrait les entités : décisions, motifs, composants, dépendances, contraintes, actions à mener
• Infère les relations entre les entités à travers les projets
• Détecte les contradictions lorsque des décisions entrent en conflit
• Interroge en langage naturel avec des citations sources
• Recherche sémantiquement — combine la similarité par mots-clés et vectorielle (embedding) pour que les requêtes correspondent par le sens, pas seulement par les mots-clés (optionnel ; voir Recherche Sémantique)
• Route intelligemment entre les LLM cloud et locaux
• Respecte la vie privée — les projets restreints ne quittent jamais votre machine
• Tableau de bord web avec visualisation du graphe de connaissances, flux en direct et explorateur de requêtes
• Serveur MCP pour une intégration directe avec Claude Code

Démarrage Rapide

1. Installer

npm install -g @gzoo/cortex

Si l'installation globale échoue avec EACCES, utilisez plutôt un préfixe utilisateur :

mkdir -p ~/.local
npm config set prefix ~/.local
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g @gzoo/cortex

Ou installez depuis la source :

git clone https://github.com/gzoonet/cortex.git
cd cortex
npm install && npm run build && npm link

Vérifier : cortex --version (version actuelle : 0.8.1)

2. Configuration

Lancez l'assistant interactif :

cortex init
cortex doctor                              # verify config, providers, and DB

Celui-ci vous guide à travers :

• Fournisseur LLM — Anthropic, Google Gemini, DeepSeek, Groq, OpenRouter ou Ollama (local)
• Clé API — enregistrée de manière sécurisée dans ~/.cortex/.env
• Mode de routage — cloud-first, hybride, local-first ou local uniquement
• Répertoires surveillés — quels répertoires Cortex doit surveiller
• Limite budgétaire — plafond mensuel des dépenses LLM

cortex init écrit la configuration globale dans ~/.cortex/cortex.config.json. Les clés API vont dans ~/.cortex/.env.

3. Enregistrer les Projets

cortex projects add my-app ~/projects/app
cortex projects add api ~/projects/api
cortex projects list                       # verify

4. Ingérer, Surveiller et Interroger

Remplissez d'abord les fichiers existants — le surveillant ne détecte que les nouveaux changements :

cortex ingest "~/projects/app/src/**/*.ts"   # one-shot backfill
cortex serve                                 # dashboard + API + file watcher (recommended)

Commande	Ce qu'elle fait
cortex serve	Tableau de bord web + API + surveillant de fichiers (ignoreInitial — pas de ré-ingestion au démarrage)
cortex watch	Surveillant de fichiers CLI uniquement (pas de tableau de bord)
cortex ingest	Ingestion unique ; les événements n'apparaissent pas dans le Flux en Direct

N'exécutez pas watch et serve ensemble — ils sont en concurrence pour les changements de fichiers. Le Flux en Direct affiche les événements en temps réel provenant uniquement de cortex serve (sauvegardes de fichiers pendant que le serveur est en cours d'exécution).

cortex query "what caching strategies am I using?"
cortex query "what decisions have I made about authentication?"
cortex find "PostgreSQL" --expand 2
cortex contradictions

5. Tableau de Bord Web

cortex serve                               # open http://localhost:3710

Accès à distance :

cortex serve --host 0.0.0.0

L'authentification est automatiquement appliquée sur les hôtes non-localhost. Un jeton porteur est auto-généré et enregistré dans ~/.cortex/.env (lisez-le avec grep CORTEX_SERVER_AUTH_TOKEN ~/.cortex/.env). Ouvrez le tableau de bord une fois avec http://<host>:3710/?token=<token> — le jeton n'est intégré que pour les requêtes qui prouvent déjà sa possession et est ensuite conservé pour l'onglet du navigateur (ainsi, les visiteurs anonymes ne le reçoivent jamais). Les appels API/WebSocket derrière un proxy inverse utilisent Authorization: Bearer <token>.

Exclusion de Fichiers et Répertoires

Cortex ignore node_modules, dist, .git et d'autres répertoires courants par défaut. Pour en ajouter d'autres :

cortex config exclude add docs             # exclude a directory
cortex config exclude add "*.log"          # exclude by pattern
cortex config exclude list                 # see all excludes
cortex config exclude remove docs          # remove an exclude

Comment ça Marche

Cortex exécute un pipeline à chaque changement de fichier :

1. Analyser — le contenu du fichier est découpé par un analyseur sensible au langage (tree-sitter pour le code, remark pour le markdown)
2. Extraire — le LLM identifie les entités (décisions, composants, motifs, etc.)
3. Relier — le LLM infère les relations entre les entités nouvelles et existantes
4. Détecter — les contradictions et les doublons sont signalés automatiquement
5. Stocker — les entités, les relations et les vecteurs vont dans SQLite + LanceDB
6. Interroger — les requêtes en langage naturel recherchent dans le graphe et synthétisent les réponses

Toutes les données restent en local dans ~/.cortex/. Seuls les appels API LLM quittent votre machine (et jamais pour les projets restreints).

Fournisseurs LLM

Cortex est agnostique vis-à-vis du fournisseur. Il prend en charge :

• Anthropic Claude (Sonnet, Haiku) — via l'API Anthropic native
• Google Gemini — via l'API compatible OpenAI
• DeepSeek (Reasoner, Chat) — raisonnement fort, très abordable
• Groq — inférence rapide avec niveau gratuit
• Toute API compatible OpenAI — OpenRouter, proxys locaux, etc.
• Ollama (Mistral, Llama, etc.) — entièrement local, aucun cloud requis

Le suivi des coûts utilise des tarifs spécifiques au fournisseur pour les modèles DeepSeek, Gemini, Groq et OpenRouter — pas un recours générique à Anthropic.

Les embeddings (pour la recherche sémantique) sont configurés comme un fournisseur séparé — indépendant de votre modèle de chat — vous pouvez donc exécuter le chat sur DeepSeek et les embeddings sur OpenAI. Voir Recherche Sémantique.

Modes de Routage

Mode	Coût Cloud	Qualité	Ollama Requis
cloud-first	Varie selon le fournisseur	La plus élevée	Non
hybrid	Réduit	Élevée	Oui
local-first	Minimal	Bonne	Oui
local-only	0 $	Bonne	Oui

En mode cloud-first, toutes les tâches sont routées vers votre fournisseur cloud. Ollama n'est pas requis et n'est utilisé que si le recours budgétaire est activé. Le mode hybride route les tâches à haut volume (extraction d'entités, classement) vers Ollama et les tâches lourdes en raisonnement (inférence de relations, requêtes) vers votre fournisseur cloud.

Prérequis

• Node.js 20+
• Clé API LLM pour les modes cloud — Anthropic, Google Gemini, DeepSeek, Groq ou tout fournisseur compatible OpenAI
• Ollama — uniquement pour les modes hybrid, local-first ou local-only (installer)

Configuration

La configuration est en couches — les sources ultérieures remplacent les précédentes :

Priorité	Emplacement	Portée
1	Valeurs par défaut intégrées	Globale
2	~/.cortex/cortex.config.json	Globale (créé par cortex init)
3	./cortex.config.json	Remplacements de projet (optionnel)
4	Variables d'env CORTEX_*	Session

Les clés API sont stockées séparément dans ~/.cortex/.env (jamais dans le JSON de configuration).

cortex config list                       # see all non-default settings
cortex config set llm.mode hybrid        # switch routing mode
cortex config set llm.budget.monthlyLimitUsd 10  # set budget
cortex config exclude add vendor         # exclude a directory from watching
cortex privacy set ~/clients restricted  # mark directory as restricted
cortex doctor                            # validate setup

Référence complète de la configuration : docs/configuration.md

Recherche Sémantique (Embeddings)

Cortex combine la recherche par mots-clés (texte intégral) avec la similarité vectorielle, de sorte que les requêtes correspondent par le sens plutôt que par les mots exacts. Les embeddings sont optionnels et désactivés par défaut — activez-les avec un fournisseur d'embeddings cloud (pas de GPU local ni d'Ollama requis) :

cortex config set llm.embeddings.enabled true
cortex config set llm.embeddings.baseUrl https://api.openai.com/v1
cortex config set llm.embeddings.model text-embedding-3-small
cortex config set llm.embeddings.apiKeySource env:OPENAI_API_KEY
cortex config set llm.embeddings.dimensions 1536
# then add the key to ~/.cortex/.env:
echo 'OPENAI_API_KEY=sk-...' >> ~/.cortex/.env

Le fournisseur d'embeddings est indépendant de votre fournisseur de chat — exécutez le chat sur DeepSeek (ou Anthropic, Groq, …) et les embeddings sur OpenAI. Tout point de terminaison d'embeddings compatible OpenAI fonctionne.

Les nouveaux fichiers sont automatiquement intégrés lors de leur ingestion. Pour construire l'index d'un graphe que vous avez déjà ingéré, exécutez une réindexation unique :

cortex reindex                 # all projects
cortex reindex my-app          # a single project

Commandes

Commande	Description
cortex init	Assistant de configuration interactif
cortex doctor	Valider la configuration, les fournisseurs, les projets, les secrets et la base de données
cortex projects add/list/remove/show	Gérer les projets enregistrés
cortex serve	Tableau de bord web + API + surveillant de fichiers (port 3710)
cortex watch [project]	Surveillant de fichiers CLI uniquement
cortex ingest <file-or-glob>	Ingestion de fichiers unique (séparée du Flux en Direct)
cortex reindex [project]	Reconstruire l'index de recherche sémantique (embedding) pour les entités existantes
cortex query <question>	Requête en langage naturel avec citations
cortex find <term>	Trouver des entités par nom
cortex status	Statistiques du graphe, coûts, statut du fournisseur
cortex costs	Décomposition détaillée des coûts
cortex contradictions	Lister les contradictions actives
cortex resolve <id>	Résoudre une contradiction
cortex models list/pull/test/info	Gérer les modèles Ollama
cortex mcp	Démarrer le serveur MCP pour Claude Code
cortex report	Résumé post-ingestion
cortex privacy set/list	Définir la confidentialité du répertoire
cortex config list/get/set/validate	Lire/écrire la configuration
cortex config exclude add/remove/list	Gérer les exclusions de fichiers/répertoires
cortex stop / cortex restart	Gérer les processus de surveillance/serveur en cours d'exécution
cortex db	Opérations de base de données

Référence complète de la CLI : docs/cli-reference.md

Tableau de Bord Web

Exécutez cortex serve pour ouvrir un tableau de bord web complet à l'adresse http://localhost:3710 avec :

• Accueil du Tableau de Bord — statistiques du graphe, activité récente, répartition par type d'entité
• Graphe de Connaissances — graphe interactif à force D3 avec clustering, cliquez pour explorer
• Flux en Direct — événements de changement de fichier et d'extraction d'entités en temps réel via WebSocket (provenant uniquement de cortex serve)
• Explorateur de Requêtes — requêtes en langage naturel avec réponses en streaming
• Résolveur de Contradictions — examiner et résoudre les décisions conflictuelles

Déploiement à Distance

Pour un accès au-delà de localhost, liez à toutes les interfaces et placez Cortex derrière un proxy inverse :

cortex serve --host 0.0.0.0

Exemple de configuration nginx — protégez /api/ et /ws avec une authentification basique ; servez les actifs statiques sans authentification (le tableau de bord injecte le jeton porteur dans le HTML) :

location /api/ {
    auth_basic "Cortex";
    auth_basic_user_file /etc/nginx/.htpasswd;
    proxy_pass http://127.0.0.1:3710;
    proxy_set_header Authorization "Bearer $CORTEX_TOKEN";
}

location /ws {
    auth_basic "Cortex";
    auth_basic_user_file /etc/nginx/.htpasswd;
    proxy_pass http://127.0.0.1:3710;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

location / {
    auth_basic off;
    proxy_pass http://127.0.0.1:3710;
}

Définissez CORTEX_SERVER_AUTH_TOKEN ou server.auth.token dans la configuration. Lorsque l'authentification est activée, Cortex injecte le jeton dans le HTML du tableau de bord afin que les appels API et WebSocket s'authentifient automatiquement.

Serveur MCP (Intégration Claude Code)

Cortex inclut un serveur MCP pour que Claude Code puisse interroger directement votre graphe de connaissances :

claude mcp add cortex --scope user -- npx @gzoo/cortex mcp

Cela donne à Claude Code 12 outils :

Outil	Description
cortex_ask	Questions en langage naturel sur vos projets
get_status	Statut du système et statistiques du graphe
list_projects	Lister les projets enregistrés
find_entity	Rechercher des entités par nom
query_cortex	Requêtes structurées sur le graphe de connaissances
get_contradictions	Lister les contradictions détectées
resolve_contradiction	Résoudre une contradiction
search_entities	Rechercher des entités avec des filtres
ingest_file	Déclencher l'ingestion de fichiers
add_project	Enregistrer un nouveau projet
remove_project	Désenregistrer un projet
session_brief	Résumé du contexte pour la session en cours

Architecture

Monorepo avec huit paquets :

• @cortex/core — types, EventBus, chargeur de configuration, classes d'erreur
• @cortex/ingest — analyseurs de fichiers (tree-sitter + remark), découpeur, surveillant, pipeline
• @cortex/graph — stockage SQLite, vecteurs LanceDB, moteur de requêtes
• @cortex/llm — fournisseurs Anthropic/Gemini/compatible OpenAI/Ollama, routeur, invites, cache
• @cortex/cli — CLI Commander.js
• @cortex/mcp — serveur Model Context Protocol (transport stdio, 12 outils)
• @cortex/server — API REST Express + relais WebSocket
• @cortex/web — tableau de bord web React + Vite + D3

Documents d'architecture : docs/

Confidentialité et Sécurité

• Les fichiers classés comme restricted ne sont jamais envoyés aux LLM cloud
• Les fichiers sensibles (.env, .pem, .key) sont automatiquement détectés et bloqués
• Les secrets de clé API sont scannés et expurgés avant toute transmission cloud
• Toutes les données sont stockées localement dans ~/.cortex/ — rien ne communique vers l'extérieur

Architecture de sécurité complète : docs/security.md

Construit Avec

• SQLite via better-sqlite3 — stockage des entités et des relations
• LanceDB — embeddings vectoriels pour la recherche sémantique
• Anthropic Claude — fournisseur de LLM cloud
• Google Gemini — fournisseur de LLM cloud (via une API compatible OpenAI)
• DeepSeek — fournisseur de LLM cloud (raisonnement + chat)
• Groq — inférence cloud rapide
• Ollama — inférence LLM locale
• tree-sitter — analyse syntaxique de fichiers tenant compte du langage
• Chokidar — surveillance de fichiers multiplateforme
• Commander.js — framework CLI
• React + Vite — tableau de bord web
• D3 — visualisation de graphes de connaissances

Contribuer

Consultez CONTRIBUTING.md pour les directives.

Licence

MIT — voir LICENSE

À propos

Conçu par GZOO — une plateforme d'automatisation métier propulsée par l'IA.

Cortex a débuté comme un outil interne pour maintenir le contexte à travers plusieurs projets clients. Nous l'avons rendu open source parce que chaque développeur qui travaille sur plus d'un projet perd le contexte, et nous pensons que cette approche — surveillance automatique des fichiers + graphe de connaissances + requêtes en langage naturel — est la bonne façon de résoudre ce problème.