# AGENTS.md donne vos règles à OpenCode. Maguyva lui montre le code.

Canonical source: https://maguyva.ai/fr/for-opencode

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

OpenCode lit dans AGENTS.md comment travailler et appelle des serveurs MCP pour tout le reste. Maguyva est un serveur MCP distant qui donne à OpenCode une carte interrogeable de votre dépôt, avec chemins de fichiers et numéros de ligne.

> Une entrée distante sous mcp. Rien ne tourne en local.

## Ce qu’il faut savoir sur OpenCode

Quatre faits propres à OpenCode.

### opencode.json

Ajoutez le serveur sous `mcp` dans le `opencode.json` de votre projet, ou dans `~/.config/opencode/opencode.json` pour tous vos projets.

### type: remote

OpenCode se connecte en HTTP au point de terminaison de Maguyva. Rien ne tourne en local et Node.js n’est pas nécessaire.

### Une référence à une variable d’environnement

OpenCode substitue les variables d’environnement dans sa configuration : l’en-tête s’écrit `Bearer {env:MAGUYVA_API_KEY}` et la clé reste hors du fichier que vous commitez.

### Le limiter par agent

Chaque serveur MCP ajoute des définitions d’outils au contexte. OpenCode peut désactiver globalement les outils d’un serveur avec un glob comme `"maguyva*": false` et les réactiver pour les seuls agents qui en ont besoin.

## AGENTS.md est un accord de travail. Utilisez-le.

```text
> /init
# analyse le dépôt et écrit AGENTS.md
```

OpenCode lit `AGENTS.md` à la racine du projet et `~/.config/opencode/AGENTS.md` pour les règles personnelles. Sans `AGENTS.md`, il se rabat sur `CLAUDE.md`. Réservez-le à :

- Les commandes de build, de test et de lint.
- Les conventions et les limites que l’agent doit respecter.
- Des renvois vers la documentation qui compte.

Une analyse au moment de `/init` est un résumé, pas un index. Elle ne dira pas à OpenCode qui appelle une fonction ajoutée hier.

## Là où AGENTS.md ne suffit plus

Trois lacunes qu’OpenCode comble avec grep et de la patience.

### // un résumé n’est pas un index

AGENTS.md peut nommer les paquets importants. Il ne peut pas lister chaque symbole et chaque site d’appel, et ne devrait pas essayer.

### // grep trouve des chaînes, pas des appelants

Une correspondance textuelle ne distingue pas un vrai appel d’un commentaire, d’un mock ou d’une méthode homonyme d’une autre classe.

### // le fichier dérive

AGENTS.md est juste le jour où on l’écrit. Le code continue de bouger ; le fichier change quand quelqu’un pense à le mettre à jour.

## Maguyva comme serveur MCP distant dans OpenCode

Une entrée sous mcp donne à OpenCode :

- **11 outils sur votre dépôt indexé**: recherche sémantique, structurelle (AST), par graphe et textuelle, plus recherche de symboles, dépendants et récupération de fichiers.
- **Des réponses avec chemins de fichiers et numéros de ligne**: sur plus de 285 langages.
- **Les mêmes réponses pour chaque modèle**: OpenCode fonctionne avec de nombreux fournisseurs de modèles. Maguyva renvoie la même carte, quel que soit le modèle qui interroge.

> AGENTS.md dit à OpenCode *comment travailler*.
> Maguyva donne à OpenCode *de quoi travailler*.

## Deux flux de travail

Interrogez la carte depuis le même terminal.

### 01. Renommer un type partagé entre paquets

```text
opencode> renomme OrderStatus en FulfillmentStatus

dependency_search("OrderStatus", dependents)
  23 références dans 8 paquets
structural_search(switch_statement, "OrderStatus")
  4 switch exhaustifs

→ OpenCode modifie la liste complète, switch compris.
[exit 0]
```

Les switch exhaustifs sont justement ceux qu’une recherche textuelle rate et que le compilateur attrape tard.

### 02. Distinguer le code de la documentation

```text
opencode> où FEATURE_BULK_EXPORT est-il lu ?

text_pattern_search("FEATURE_BULK_EXPORT")
  src/config/flags.ts:17
  src/export/bulk.ts:5
  docs/flags.md:40   ← doc uniquement

→ Deux chemins de code, une doc périmée.
[exit 0]
```

Les correspondances exactes reviennent avec leurs chemins, pour qu’OpenCode distingue le code de la documentation avant de modifier l’un ou l’autre.

## Configuration dans OpenCode

Trois étapes. Palier Free : 3 dépôts, Jusqu'à 50 000 lignes de dépôt indexées, sans carte bancaire.

### 01. Indexez un dépôt sur maguyva.ai

Choisissez-en un que vous connaissez déjà, pour pouvoir évaluer les réponses.

### 02. Ajoutez Maguyva sous mcp dans opencode.json

`opencode.json`

```json
{
  "mcp": {
    "maguyva": {
      "type": "remote",
      "url": "https://maguyva.tools/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:MAGUYVA_API_KEY}"
      }
    }
  }
}
```

### 03. Exportez votre clé et vérifiez la connexion

Définissez `MAGUYVA_API_KEY` dans le shell qui lance OpenCode. `opencode mcp list` affiche chaque serveur configuré ; posez ensuite une question dont vous connaissez déjà la réponse.

La [documentation MCP](https://opencode.ai/docs/mcp-servers/) d’OpenCode couvre les délais d’expiration, OAuth et l’accès aux outils par agent.

## Indexez un dépôt que vous connaissez déjà.

Connectez OpenCode via MCP, puis posez une question que vous pouvez vérifier.