Grace
Guides

Dépannage

Choisir la prochaine action à partir du message que vous voyez.

Commencez par le message affiché. Ne réinstallez pas tous les talents pour corriger un problème de connexion.

Ce que vous observezÀ vérifierProchaine action
Grace n’apparaît pas dans l’agent IALe fichier correspond-il à l’agent IA choisi ?Reprenez la connexion, puis rechargez MCP. Avec Copilot CLI, vérifiez .github/mcp.json, lancez-le à la racine du dépôt et approuvez la confiance du dossier.
Copilot CLI refuse la configuration.github/mcp.json est-il un JSON valide ?Corrigez le JSON, puis relancez la commande de branchement : elle s’arrête sans rien modifier tant que le fichier est invalide.
Une connexion est demandéeVotre session est-elle active ?Reprenez l’étape Authentifier et vérifier Grace affichée pour votre assistant, puis autorisez l’accès dans le navigateur.
La connexion affiche invalid_scopeLe message cite-t-il offline_access, openid, profile ou email ?Suivez la reprise de connexion ci-dessous.
Copilot CLI ne termine pas la connexion interactive/mcp show grace indique-t-il toujours une authentification requise ?Suivez la reprise Copilot CLI avant d’utiliser un autre mode d’accès.
L’accès est refuséBon compte, bonne organisation, organisation approuvée ?Consultez les permissions.
La préparation refuse une sélection videL’agent IA a-t-il désigné des talents ?Faites-lui choisir les identifiants concernés dans le répertoire fourni.
Des dépendances manquentLe diagnostic du projet indique-t-il des prérequis ?Faites compléter la sélection avant de relancer la préparation.
La préparation signale un talent sans règles de revueS’agit-il d’une absence de règles ou d’une erreur signalée ?Conservez ses conventions ; l’agent consulte toujours le plan global, sans demander le détail des talents qu’il confirme sans règles. Signalez les erreurs de lecture ou de format à votre équipe ; ne concluez pas à la conformité.
Une page ne charge pasLe problème se reproduit-il après rechargement ?Réessayez, puis transmettez le message à votre équipe.

Connexion refusée avec invalid_scope

Le message indique un refus des permissions demandées. Une adresse de retour localhost ou 127.0.0.1 est normale pour un outil installé sur votre ordinateur : elle lui rend la main après la connexion à Grace. Ne la remplacez pas par l’adresse de Grace.

  1. Authentifiez-vous depuis votre outil et autorisez Grace dans le navigateur.
  2. Si le refus persiste, suivez la réinitialisation propre à cet outil ci-dessous. Une simple déconnexion peut conserver l’ancien enregistrement OAuth.
  3. Vérifiez dans l’outil que Grace est connecté et que ses outils sont disponibles.

La présence des fichiers de configuration ne prouve pas une connexion. Grace ne peut pas inspecter le cache OAuth de votre ordinateur : un ancien enregistrement est une cause possible, pas un diagnostic automatique.

Choisissez votre outil : Copilot CLI, Copilot dans VS Code, Junie ou Claude Code. Pour un autre outil, reprenez Authentifier et vérifier Grace dans le guide de connexion.

Copilot CLI

À la racine du projet, lancez copilot, acceptez la confiance du dossier si elle est demandée, puis saisissez dans la session Copilot, pas dans le terminal système :

/mcp auth grace

Terminez l’autorisation dans le navigateur, puis contrôlez :

/mcp show grace

Résultat attendu : Grace est connecté et ses outils sont disponibles. /mcp auth grace relance l’authentification ; cette commande ne garantit pas l’effacement de l’ancien client OAuth. Commandes Copilot CLI.

Dernier recours : mettre de côté le cache OAuth local

Quittez toutes les sessions Copilot CLI avant de continuer. Cette manipulation déplace le dossier OAuth entier : les autres serveurs MCP peuvent aussi demander une reconnexion. La sauvegarde contient des secrets : gardez-la sur votre ordinateur, hors du dépôt, et ne l’envoyez à personne.

GitHub documente mcp-oauth-config comme stockage de secours des jetons, de l’enregistrement et de la preuve de connexion quand le trousseau système est indisponible. Déplacer ce dossier ne réinitialise pas le trousseau et ne garantit donc pas une réparation. Si le dossier est absent ou si l’erreur persiste, arrêtez cette procédure et demandez de l’aide. Référence du dossier Copilot.

Utilisez le même dossier de configuration que Copilot, dans cet ordre : option --config-dir si vous l’utilisez, sinon COPILOT_HOME, sinon ~/.copilot. Si l’option est relative, reportez son chemin absolu depuis le dossier où vous lancez Copilot. Ne remplacez pas le dossier personnel par $USER, qui est un nom d’utilisateur. Les commandes ci-dessous n’ouvrent aucun fichier secret.

macOS ou Linux — dans le terminal système : renseignez grace_config_override seulement si vous utilisez --config-dir.

(
  grace_config_override=''
  grace_config_dir=${grace_config_override:-${COPILOT_HOME:-"$HOME/.copilot"}}
  case "$grace_config_dir" in
    /*) ;;
    *) printf '%s\n' 'Arrêt : indiquez un chemin absolu.' >&2; exit 1 ;;
  esac
  if [ -L "$grace_config_dir" ] || [ ! -d "$grace_config_dir" ]; then
    printf '%s\n' 'Arrêt : dossier de configuration absent, invalide ou symbolique.' >&2; exit 1
  fi
  grace_cache="$grace_config_dir/mcp-oauth-config"
  if [ -L "$grace_cache" ]; then
    printf '%s\n' 'Arrêt : le cache est un lien symbolique.' >&2; exit 1
  fi
  if [ ! -e "$grace_cache" ]; then
    printf '%s\n' 'Cache absent : aucun changement. Le trousseau peut être utilisé.'; exit 0
  fi
  if [ ! -d "$grace_cache" ]; then
    printf '%s\n' 'Arrêt : le cache existe mais ne désigne pas un dossier.' >&2; exit 1
  fi
  grace_backup="$grace_config_dir/mcp-oauth-backup-$(date +%Y%m%d-%H%M%S)"
  (umask 077; mkdir "$grace_backup") || {
    printf '%s\n' 'Arrêt : sauvegarde existante ou impossible à créer. Rien déplacé.' >&2; exit 1
  }
  mv "$grace_cache" "$grace_backup/mcp-oauth-config" || exit 1
  printf 'Sauvegarde : %s\n' "$grace_backup"
)

Windows — dans PowerShell : renseignez $graceConfigOverride seulement si vous utilisez --config-dir. N’utilisez pas le terminal interactif de Copilot.

& {
  $graceConfigOverride = ''
  $graceConfigDir = if ($graceConfigOverride) { $graceConfigOverride } elseif ($env:COPILOT_HOME) { $env:COPILOT_HOME } else { Join-Path $HOME '.copilot' }
  if (-not [IO.Path]::IsPathRooted($graceConfigDir) -or $graceConfigDir -match '^[A-Za-z]:(?![\\/])|^\\(?!\\)') { throw 'Arrêt : indiquez un chemin absolu.' }
  $graceDir = Get-Item -LiteralPath $graceConfigDir -Force -ErrorAction Stop
  if (-not $graceDir.PSIsContainer -or ($graceDir.Attributes -band [IO.FileAttributes]::ReparsePoint)) { throw 'Arrêt : dossier de configuration invalide ou lié.' }
  $graceCache = Join-Path $graceConfigDir 'mcp-oauth-config'
  $graceItem = Get-Item -LiteralPath $graceCache -Force -ErrorAction SilentlyContinue
  if ($null -eq $graceItem) { Write-Host 'Cache absent : aucun changement. Le trousseau peut être utilisé.'; return }
  if (-not $graceItem.PSIsContainer -or ($graceItem.Attributes -band [IO.FileAttributes]::ReparsePoint)) { throw 'Arrêt : le cache est invalide ou lié.' }
  $graceBackup = Join-Path $graceConfigDir ('mcp-oauth-backup-' + (Get-Date -Format 'yyyyMMdd-HHmmss'))
  if (Test-Path -LiteralPath $graceBackup) { throw 'Arrêt : sauvegarde déjà présente. Rien déplacé.' }
  New-Item -ItemType Directory -Path $graceBackup -ErrorAction Stop | Out-Null
  Move-Item -LiteralPath $graceCache -Destination (Join-Path $graceBackup 'mcp-oauth-config') -ErrorAction Stop
  Write-Host "Sauvegarde : $graceBackup"
}

Conservez le chemin de sauvegarde affiché. Relancez Copilot avec les mêmes options et variables, puis recommencez /mcp auth grace et /mcp show grace. Si la connexion échoue encore, ne multipliez pas les effacements : transmettez le message et la version de Copilot à votre équipe.

Pour restaurer, quittez de nouveau Copilot. Remplacez le chemin d’exemple par celui affiché. Si Copilot a recréé un cache, les commandes s’arrêtent : sauvegardez d’abord ce nouveau dossier avec la procédure précédente, puis restaurez la sauvegarde initiale. La restauration remet l’ancien état local ; elle ne renouvelle pas les jetons et ne modifie pas le trousseau.

(
  grace_backup='/chemin/absolu/mcp-oauth-backup-AAAAMMJJ-HHMMSS'
  case "$grace_backup" in /*) ;; *) printf '%s\n' 'Arrêt : chemin absolu requis.' >&2; exit 1 ;; esac
  grace_cache="$(dirname "$grace_backup")/mcp-oauth-config"
  if [ -L "$grace_backup" ] || [ -L "$grace_backup/mcp-oauth-config" ] || [ ! -d "$grace_backup/mcp-oauth-config" ]; then
    printf '%s\n' 'Arrêt : sauvegarde absente, invalide ou symbolique.' >&2; exit 1
  fi
  if [ -e "$grace_cache" ] || [ -L "$grace_cache" ]; then
    printf '%s\n' 'Arrêt : un cache existe déjà. Sauvegardez-le avant de restaurer.' >&2; exit 1
  fi
  mv "$grace_backup/mcp-oauth-config" "$grace_cache" || exit 1
  printf '%s\n' 'Ancien cache restauré.'
)
& {
  $graceBackup = 'C:\chemin\mcp-oauth-backup-AAAAMMJJ-HHMMSS'
  if (-not [IO.Path]::IsPathRooted($graceBackup) -or $graceBackup -match '^[A-Za-z]:(?![\\/])|^\\(?!\\)') { throw 'Arrêt : chemin absolu requis.' }
  $graceDir = Get-Item -LiteralPath $graceBackup -Force -ErrorAction Stop
  $graceSource = Get-Item -LiteralPath (Join-Path $graceBackup 'mcp-oauth-config') -Force -ErrorAction Stop
  if (-not $graceDir.PSIsContainer -or -not $graceSource.PSIsContainer -or ($graceDir.Attributes -band [IO.FileAttributes]::ReparsePoint) -or ($graceSource.Attributes -band [IO.FileAttributes]::ReparsePoint)) { throw 'Arrêt : sauvegarde invalide ou liée.' }
  $graceCache = Join-Path (Split-Path -Parent $graceBackup) 'mcp-oauth-config'
  if (Get-Item -LiteralPath $graceCache -Force -ErrorAction SilentlyContinue) { throw 'Arrêt : un cache existe déjà. Sauvegardez-le avant de restaurer.' }
  Move-Item -LiteralPath $graceSource.FullName -Destination $graceCache -ErrorAction Stop
  Write-Host 'Ancien cache restauré.'
}

Copilot dans VS Code

  1. Ouvrez la palette de commandes et lancez MCP: List Servers. Sélectionnez Grace, démarrez-le et terminez l’autorisation dans le navigateur.
  2. Si invalid_scope revient, lancez Authentication: Remove Dynamic Authentication Providers dans la palette, puis sélectionnez uniquement Grace. Relancez ensuite sa connexion MCP.
  3. Vérifiez que Grace est démarré dans MCP: List Servers et que ses outils sont disponibles dans Copilot Chat. Procédure VS Code.

Junie

Junie CLI, en mode interactif : lancez junie depuis votre projet, puis saisissez /mcp. Sélectionnez Grace → Authorize, terminez l’autorisation dans le navigateur et vérifiez le statut Active. Dans un client ACP, /mcp est une liste en lecture seule : utilisez le mode interactif de Junie pour ce parcours. Procédure Junie CLI.

Plugin Junie dans un IDE JetBrains : ouvrez Settings → Tools → Junie → MCP Settings, puis consultez la colonne Status de Grace et le message associé à une erreur. Réglages du plugin Junie.

Ces parcours ne garantissent pas l’effacement d’un ancien enregistrement OAuth. Si le refus persiste, transmettez le message et les versions de Junie et de l’IDE, en précisant CLI, plugin Junie ou AI Chat. Aucune commande de purge de leur cache n’est proposée ici.

Claude Code

Reprenez d’abord l’authentification indiquée dans le guide de connexion du projet. Si le refus persiste, retirez Grace avec claude mcp remove grace, puis ajoutez-le à nouveau depuis le guide de connexion. Cette suppression efface aussi l’authentification enregistrée. Vérifiez ensuite que Grace est connecté et ses outils disponibles. Procédure Claude Code.

Si votre outil ne propose pas la réinitialisation décrite, demandez de l’aide avec sa version exacte plutôt que de supprimer d’autres données locales.

Demander de l’aide

Indiquez l’action tentée, le message exact, le nom du projet et le moment de l’erreur. Ajoutez une capture cadrée si elle aide à comprendre. Masquez les données privées, les clés et les jetons. Ne transmettez ni mot de passe, ni adresse OAuth complète du navigateur, ni contenu du cache ou de sa sauvegarde.

Sur cette page