Guide : CodeGraph MCP sur Cloud Mac en 5 minutes

Un gros codegraph init fait souvent tourner le ventilateur du portable en premier. Mieux : CodeGraph + MCP sur Cloud Mac — quelques commandes SSH ; Claude Code et Cursor locaux sans CLI ni index local.

Chemin minimal : ssh root@zavcloud → brew install → codegraph init. Déjà lu CodeGraph & agents AI coding ? Ici : quelle machine et mise en ligne en cinq minutes.

Pourquoi CodeGraph MCP sur Cloud Mac ?

CodeGraph crée .codegraph/ ; le premier init -i charge CPU/NVMe. Sur Cloud Mac ZavCloud :

• Même macOS que xcodebuild et le runner GitHub Actions ;
• SSH seul pour les devs ;
• Index nocturne, requêtes read-only le jour.

Prérequis

• Cloud Mac actif ;
• Terminal local ;
• Code cloné sur l'instance ;
• Optionnel : Claude Code / Cursor.

Étape 1 : SSH

Copiez l'adresse console, connectez-vous en root :

# Example: replace zavcloud with your instance IP or hostname
ssh root@zavcloud

# Key-based login (recommended)
ssh -i ~/.ssh/id_ed25519 root@203.0.113.10

Première fois : yes pour l'empreinte. Le prompt doit être un macOS distant.

Étape 2 : brew install

macOS natif + Homebrew — Node et CLI :

# Confirm Homebrew
brew --version

# Install Node if needed
brew install node

# Install CodeGraph CLI
npm install -g @colbymchenry/codegraph
codegraph --version

install.sh officiel dans la même session SSH :

curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

Étape 3 : codegraph init

À la racine du dépôt, init + index complet :

cd ~/workspace/your-monorepo
git pull

# Init + index (first run may take 10–40 min)
codegraph init -i

# Confirm database
codegraph status
ls -la .codegraph/

Utilisez tmux. .codegraph/codegraph.db reste sur Cloud Mac.

Étape 4 : MCP

Config MCP (codegraph serve --mcp) :

codegraph install --target=claude,cursor --yes

# Foreground MCP (debug)
codegraph serve --mcp

Pas de double install local.

• Remote sur Cloud Mac : même .codegraph ;
• Agent local + graphe cloud via ssh -L — pas d'init local.

Checklist 5 minutes

FAQ & dépannage terrain

Par fréquence support. SSH OK, repo sous ~/workspace/your-repo.

Échec SSH : ssh root@zavcloud timeout ou Permission denied

Symptôme: Connection timed out, Permission denied (publickey), ou échec après l'empreinte hôte.

Étapes:

1. Remplacez zavcloud par l'IP publique de la console (ex. ssh root@203.0.113.10). Nom non résolu → timeout fréquent.
2. Vérifiez les droits de clé en local :
   Local

   chmod 600 ~/.ssh/id_ed25519
   ssh -v -i ~/.ssh/id_ed25519 root@YOUR_IP

   Dans -v : Offering public key vs no mutual signature — clé non liée à l'instance.
3. IP joignable mais mot de passe refusé : Cloud Mac = auth par clé. Reset SSH dans le panel ou VNC + Connexion à distance.
4. Port 22 bloqué en entreprise : testez en partage de connexion ; IPv4 statique utile pour whitelist.

C'est bon quand: Shell stable ; uname -a affiche Darwin (macOS).

brew install ou codegraph : command not found

Symptôme: brew: command not found, ou npm i -g OK mais pas de codegraph --version.

Étapes:

1. Chemin Homebrew (Apple Silicon) :
   Cloud Mac

   test -x /opt/homebrew/bin/brew && eval "$(/opt/homebrew/bin/brew shellenv)"
   brew --version

   Sans brew : installer Homebrew ou install.sh.
2. Bin npm global dans le PATH :
   Cloud Mac

   npm config get prefix
   export PATH="$(npm config get prefix)/bin:$PATH"
   which codegraph
   codegraph --version

   Persistez export PATH=... dans ~/.zshrc.
3. Secours :
   Alternative

   curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
   exec $SHELL -l

C'est bon quand: which codegraph renvoie un chemin ; codegraph --version s'affiche.

codegraph init -i bloqué ou index cassé après coupure SSH

Symptôme: Pas de sortie longtemps ; après déconnexion codegraph status non indexé ou DB corrompue.

Étapes:

1. Toujours indexer dans tmux :
   Cloud Mac · recommandé

   brew install tmux
   tmux new -s codegraph
   cd ~/workspace/your-repo && codegraph init -i
   # After reconnect:
   tmux attach -t codegraph

2. Espace disque :

   df -h .
   du -sh .codegraph 2>/dev/null

3. DB suspecte : sauvegarder, supprimer .codegraph/ à la racine, relancer codegraph init -i (ne pas supprimer pendant l'exécution).
4. Gros monorepo : .codegraphignore — trop d'exclusions → impact incomplet.

C'est bon quand: codegraph status fichiers > 0 ; .codegraph/codegraph.db présent.

Claude Code / Cursor : pas d'outils CodeGraph MCP

Symptôme: Pas de codegraph dans la liste MCP ; l'agent ne appelle pas codegraph_impact.

Étapes:

1. Sur le Cloud Mac, réécrire MCP :

   codegraph install --target=claude,cursor --yes
   grep -A6 codegraph ~/.claude.json 2>/dev/null || cat ~/.claude.json

   Vérifier "command": "codegraph" et serve --mcp.
2. Quitter complètement Claude Code / Cursor et rouvrir.
3. Agent local + graphe cloud :
   Local ~/.claude.json

   {
     "mcpServers": {
       "codegraph": {
         "type": "stdio",
         "command": "ssh",
         "args": ["root@YOUR_IP", "codegraph", "serve", "--mcp"]
       }
     }
   }

   Tester d'abord ssh root@YOUR_IP codegraph serve --mcp à la main.
4. Approbation outils : autoriser mcp__codegraph__* ou règle CLAUDE.md pour impact avant APIs publiques.

C'est bon quand: Nouveau chat : outils codegraph ou impact renvoie des chemins — pas vide / grep seul.

codegraph impact renvoie une liste vide

Symptôme: Des appelants existent mais codegraph impact "Foo.bar" = 0 ligne.

Étapes:

1. Racine indexée :

   pwd
   codegraph status

2. Symboles adaptés au langage (Swift : TypeName.method). codegraph_callers pour l'orthographe.
3. Index obsolète : sur Cloud Mac git pull && codegraph init -i.
4. Vérifier que .gitignore n'exclut pas des dossiers avec appelants.

C'est bon quand: Impact ≥1 chemin pour un symbole connu ; résultat ≥ grep manuel (appels indirects).

Plusieurs dépôts sur un Cloud Mac / mauvais dossier

Symptôme: Init sur A, code sur B ; un seul .codegraph/ sous ~/workspace.

Étapes:

• codegraph init -i à chaque racine — pas de dossier parent partagé.
• cd à la bonne racine avant l'agent, ou ouvrir ce dossier en Remote-SSH.
• Disque serré : index complet seulement sur le monorepo principal ; cron nocturne + tmux.

C'est bon quand: Racine workspace agent = dossier avec .codegraph/codegraph.db.

Interroger le graphe en local sans init sur le portable

Symptôme: MCP local souhaité, pas 30 min d'init local.

Étapes:

1. Index sur Cloud Mac ; sync .codegraph/ seulement :
   Local

   rsync -avz --progress root@YOUR_IP:~/workspace/your-repo/.codegraph/ ./your-repo/.codegraph/

2. codegraph status en local ; codegraph install pour MCP — pas de second init -i.

C'est bon quand: codegraph status OK en local ; MCP lit la DB sync.

Les équipes rsyncent souvent un « index doré » la nuit depuis le même Cloud Mac.

Cloud Mac lent à l'index — conflit avec Xcode

Symptôme: CPU saturé ; build et index sur le même hôte.

Étapes:

• caffeinate -dims dans tmux pour éviter le sleep.
• codegraph init -i la nuit ou hors pic ; décaler de xcodebuild — voir ../openclaw-cloud-automation/openclaw-cloud-automation.html runner.
• CPU plein par codegraph = normal ; simulateur + index → second Cloud Mac dédié.

C'est bon quand: Index terminé, DB saine ; dev/build diurne utilisable.

Que gagne-t-on vs install local ?

Pas de graphe « lite » — où tourne le CPU. Pas de Node local ni ventilateur. SSH + MCP restent. CodeGraph & AI coding ; Guide gros dépôt (2026).

• Concept— Edits manqués Claude Code
• CI même machine— Runner Cloud Mac
• Instance— Offres Cloud Mac