Notes pratiques : Serena MCP : Fournir à vos outils de codage IA un cerveau d’IDE
Guide pas à pas des notes pratiques : Serena MCP : Fournir à vos outils de codage IA un cerveau d’IDE : contrats, vérifications et emplacements pour du code à insérer destinés aux équipes utilisant ce modèle.
Utilisez ceci comme une version révisée destinée aux opérateurs des idées présentées dans « Serena MCP : Donner à vos outils de codage IA un cerveau d’IDE » : étapes claires, emplacements de code ordonnés et notes de récupération qui survivent au transfert. L’étape « Aperçu » fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un enregistrement exemplaire, un cas d’échec et la note de réversion avant d’élargir le périmètre. Documentez ensemble le parcours optimal et le parcours de récupération. Les tentatives répétées, les contrôles humains et la gestion des messages non livrés font partie du produit, et non d’une mise en forme ultérieure.
Qu’est-ce que Serena MCP ?
Pour l’étape « Qu’est-ce que Serena MCP ? », il convient de définir les entrées, le responsable de l’étape et les critères d’arrêt avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu, sans avoir à deviner l’état caché. Préférez des unités petites et testables aux scripts complexes. Lorsqu’une étape échoue, l’échec doit indiquer une seule responsabilité plutôt qu’un processus embrouillé. Authentifiez au niveau du gateway et réautorisez au niveau du plan de données. Un token porteur seul ne constitue pas une frontière entre les tenants.
Le problème : comment les outils d’IA naviguent-ils dans le code aujourd’hui ?
Pour l’étape « Le Problème : Comment l’IA fonctionne », il convient de définir les entrées, le responsable de chaque étape ainsi que les critères d’achèvement avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu, sans avoir à deviner l’état caché. Considérez cette étape comme un contrat entre les entrées et les sorties validées. Donnez des noms aux artefacts, définites des vérifications de succès et refusez toute exécution partielle silencieuse. Authentifiez-vous au niveau du gateway et réautorisez-vous au niveau du plan de données. Un simple token porteur ne constitue pas une frontière entre les tenants.
+----------------------------+-------------------------------------+--------------------------------------------+
| Task | Without Serena | With Serena |
+============================+=====================================+============================================+
| **Semantic search** | Text match on "auth" - returns | Returns `authenticateUser()`, |
| "find auth functions" | false positives, misses functions | `login()`, `verifyCredentials()` |
| | named `verifyCredentials` | with file locations and line numbers |
+----------------------------+-------------------------------------+--------------------------------------------+
| **Go to definition** | Searches files for "User" and | Jumps directly to the `User` |
| "show me the User schema" | "schema" - returns every reference | class/interface definition with |
| | | full import tree |
+----------------------------+-------------------------------------+--------------------------------------------+
| **Find references** | Text search for "PaymentProcessor" | Returns all usages with context: |
| "where is | - misses dynamic usages | imports, instantiations, method calls |
| PaymentProcessor used?" | | |
+----------------------------+-------------------------------------+--------------------------------------------+
| **Cross-file refactoring** | Text search and replace - misses | Semantic rename via LSP - updates |
| "rename UserService | string interpolations or aliased | every reference correctly across |
| to AccountService" | imports, breaks things | the entire codebase |
+----------------------------+-------------------------------------+--------------------------------------------+
Comment Serena change les règles du jeu
Pour « Comment Serena change le cadre », définissez les entrées, le responsable de l’étape et les critères de sortie avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Enregistrez les temps d’exécution ainsi que le coût des jetons ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce du coût évite les factures inattendues lorsque le parcours passe d’un environnement de démonstration à des environnements partagés. Authentifiez-vous au niveau du gateway et réautorisez-vous au niveau du plan de données. Un simple jeton porteur ne constitue pas une frontière entre les tenants. Pour « Comment Serena change le cadre », définissez les entrées, le responsable de l’étape et les critères de sortie avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Documentez conjointement le parcours optimal et le parcours de récupération. Les tentatives de réessai, les contrôles humains et la gestion des messages non livrés font partie intégrante du produit, et non d’une mise en forme ultérieure.
Le système de mémoire
Lorsque vous travaillez sur l’étape du système de mémoire, notez d’abord le contrat : les entrées requises, le signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Préférez des unités petites et testables à des scripts complexes. Lorsqu’une étape échoue, l’échec doit indiquer une seule responsabilité plutôt qu’un processus embrouillé. Enregistrez le nom de l’outil, le hash des arguments, la latence et le résultat de chaque appel. Sans cette trace, les boucles d’analyse débogage gaspillent des heures.
Le tableau de bord administratif
Lors de la phase du Panneau d’administration, notez d’abord les conditions du contrat : les données requises, le signal de succès, ainsi que ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Considérez cette phase comme un contrat entre les données d’entrée et les résultats validés. Donnez des noms aux éléments générés, définites des vérifications de succès, et refusez toute exécution partielle silencieuse. Enregistrez le nom de l’outil, le hash des arguments, la latence et le résultat de chaque appel. Sans ce suivi, les boucles d’analyse des erreurs perdent des heures précieuses.
Contextes : Choisir le mode adapté à votre client
Lors de l’étape « Sélection du contexte approprié », notez d’abord les conditions du contrat : entrées requises, signal de succès et conséquences en cas d’échec partiel. Cette liste de contrôle permet de garantir l’intégrité des modifications ultérieures du code. Enregistrez les temps d’exécution ainsi que le coût en tokens ou en requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le processus passe de l’environnement de démonstration à des environnements partagés. Conservez un journal avec le nom de l’outil, son hash des arguments, la latence et le résultat de chaque appel. Sans ce suivi, le débogage de boucles d’agent peut prendre des heures. Lors de l’étape « Sélection du contexte approprié », notez d’abord les conditions du contrat : entrées requises, signal de succès et conséquences en cas d’échec partiel. Cette liste de contrôle permet de garantir l’intégrité des modifications ultérieures du code. Documentez en même temps le parcours normal et les scénarios de récupération. Les tentatives de réessai, les contrôles humains et la gestion des messages non livrés font partie intégrante du produit, et non d’améliorations ultérieures.
+---------------------+------------------------------+------------------------------------------------+
| Context | Designed for | What it does |
+=====================+==============================+================================================+
| `desktop-app` | Claude Desktop, general use | **Full toolset** - everything Serena offers. |
| | | Use this when the client has no built-in |
| | | coding capabilities. This is also the right |
| | | choice for a shared Docker instance serving |
| | | multiple different clients. |
+---------------------+------------------------------+------------------------------------------------+
| `claude-code` | Claude Code | Disables tools that overlap with Claude |
| | | Code's built-in capabilities (file edits, |
| | | shell commands, etc.) to avoid conflicts. |
| | | Single-project context. |
+---------------------+------------------------------+------------------------------------------------+
| `ide` | VS Code, Cursor, Cline, Kilo | Generic IDE augmentation - focuses on |
| | | semantic tools, assumes the IDE already |
| | | handles basic file operations. |
| | | Single-project context. |
+---------------------+------------------------------+------------------------------------------------+
| `agent` | Agno, autonomous agents | Broader autonomy for agents that drive the |
| | | full workflow independently. |
+---------------------+------------------------------+------------------------------------------------+
| `codex` | OpenAI Codex | Optimized for Codex's tool calling format. |
+---------------------+------------------------------+------------------------------------------------+
| NOTE: The `claude-code` and `ide` contexts are **single-project**: when you pass a project |
| path at startup, those contexts lock down to only the tools relevant to that project and |
| disable the project-switching tool entirely (since you won't need it). |
+---------------------+------------------------------+------------------------------------------------+
Installation
La phase d’installation fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un transcript parfait, un cas d’échec et la note de réversion avant d’élargir le périmètre. Préférez des unités petites et testables aux scripts complexes. Lorsqu’une étape échoue, l’échec doit pointer vers une seule responsabilité plutôt que vers un processus embrouillé. Exposez des outils dotés de schémas restreints et de labels explicites indiquant les effets secondaires. Les hôtes doivent savoir quels appels modifient l’état avant d’approuver automatiquement.
Installation standard
La phase d’installation standard fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un transcript parfait, un cas d’échec et la note de réversion avant d’élargir le périmètre. Considérez cette phase comme un contrat entre les entrées et les sorties validées. Nommez les artefacts, définez des vérifications de succès, et refusez toute mise en œuvre partielle silencieuse. Exposez des outils dotés de schémas restreints et de labels explicites indiquant leurs effets secondaires. Les hôtes doivent savoir quels appels modifient l’état avant d’approuver automatiquement.
uv tool install -p 3.13 serena-agent@latest --prerelease=allow
serena init
claude mcp add --scope user serena -- serena start-mcp-server \
--context claude-code --project-from-cwdlaude mcp add serena -- serena start-mcp-server --context claude-code --project "$(pwd)"
claude mcp add serena -- serena start-mcp-server --context claude-code --project "$(pwd)"
{
"servers": {
"serena": {
"type": "stdio",
"command": "serena",
"args": [
"start-mcp-server",
"--context", "ide",
"--project", "${workspaceFolder}"
]
}
}
}
{
"mcpServers": {
"serena": {
"command": "serena",
"args": ["start-mcp-server", "--context", "desktop-app"]
}
}
}
Installation de Docker
La phase d’installation de Docker fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un exemple idéal, un cas d’échec et des notes de réversion avant d’élargir le périmètre. Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le processus passe de la démonstration aux environnements partagés. Exposez des outils dotés de schémas restreints et de labels explicites indiquant les effets secondaires. Les hôtes doivent savoir quels appels modifient l’état avant d’approuver automatiquement. La phase d’installation de Docker fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un exemple idéal, un cas d’échec et des notes de réversion avant d’élargir le périmètre. Documentez ensemble le parcours réussi et le parcours de récupération. Les tentatives répétées, les contrôles humains et la gestion des messages non livrés font partie intégrante du produit, et non d’une mise en forme ultérieure.
services:
serena:
image: ghcr.io/oraios/serena:latest
container_name: myproject-serena
restart: unless-stopped
environment:
- SERENA_DOCKER=1
ports:
- "10121:9121" # SSE endpoint
- "34282:24282" # Web dashboard
volumes:
- .:/workspace/myproject
command: >
serena start-mcp-server
--transport sse
--port 9121
--host 0.0.0.0
--context desktop-app
--project /workspace/myproject
gui_log_window: false
web_dashboard_listen_address: "0.0.0.0"
web_dashboard_open_on_launch: false
docker compose up -d serena
Connexion de vos outils d’IA
Pour l’étape « Connecter vos outils d’IA », définissez les entrées, le responsable de l’étape et les critères de fin avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Préférez des unités petites et testables à des scripts complexes. Lorsqu’une étape échoue, l’échec doit indiquer une seule responsabilité plutôt qu’un pipeline embrouillé. Authentifiez-vous au niveau du gateway et réautorisez-vous au niveau du plan de données. Un token porteur seul ne constitue pas une frontière entre les tenants.
Claude Code
Pour l’étape Claude Code, définissez les entrées, le responsable de l’étape et les critères de fin avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Considérez cette étape comme un contrat entre les entrées et les sorties validées. Nommez les artefacts, définissez des vérifications de succès et refusez toute exécution partielle silencieuse. Authentifiez-vous au niveau du gateway et réautorisez-vous au niveau du plan de données. Un token porteur seul ne constitue pas une frontière entre les tenants.
claude mcp add serena --transport sse --url http://localhost:10121/sse
{
"mcpServers": {
"serena": {
"type": "sse",
"url": "http://localhost:10121/sse"
}
}
}
VS Code / Cursor / Windsurf
Pour l’étape VS Code Cursor Windsurf, définissez les entrées, le responsable de l’étape et les critères d’arrêt avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Enregistrez les temps d’exécution ainsi que le coût des jetons ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite des factures inattendues lorsque le processus passe d’un environnement de démonstration à des environnements partagés. Authentifiez-vous au niveau du gateway et réautorisez-vous au niveau du plan de données. Un simple jeton porteur ne constitue pas une frontière entre les tenants. Pour l’étape VS Code Cursor Windsurf, définissez les entrées, le responsable de l’étape et les critères d’arrêt avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Documentez conjointement le parcours normal et les scénarios de récupération. Les tentatives de répétition, les contrôles humains et la gestion des messages non livrés font partie intégrante du produit, et non d’améliorations ultérieures.
{
"servers": {
"serena": {
"type": "sse",
"url": "http://localhost:10121/sse"
}
}
}
OpenCode
Lors de la phase OpenCode, notez d’abord le contrat : les entrées requises, le signal de succès, ainsi que ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Préférez des unités petites et testables plutôt que des scripts volumineux. Lorsqu’une étape échoue, l’échec doit indiquer une seule responsabilité et non un processus complexe et embrouillé. Enregistrez le nom de l’outil, le hash des arguments, la latence et le résultat de chaque appel. Sans cette trace, le débogage de boucles prend des heures inutilement.
{
"mcp": {
"serena": {
"type": "remote",
"url": "http://localhost:10121/sse",
"enabled": true
}
}
}
Configuration du projet
Lors de la phase de configuration du projet, notez d’abord les conditions prévues : les entrées requises, le signal de succès, ainsi que ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de garantir l’honnêteté des modifications ultérieures du code. Considérez cette phase comme un contrat entre les entrées et les sorties validées. Donnez des noms aux artefacts, définez des vérifications de succès, et refusez toute exécution partielle silencieuse. Enregistrez le nom de l’outil, le hash des arguments, la latence et le résultat de chaque appel. Sans ce suivi, les boucles d’analyse des erreurs perdent des heures précieuses.
project_name: "myproject"
languages:
- typescript # uses typescript-language-serverencoding: "utf-8"
ignore_all_files_in_gitignore: trueignored_paths:
- "node_modules"
- "dist"
- "build"
- "coverage"
- ".next"
- "out"
- ".cache"
.serena/project.yml ← commit this (shared config)
.serena/memories/ ← commit this (AI-generated project notes, useful for everyone)
.serena/cache/ ← gitignore (rebuilt per machine)
.serena/project.local.yml ← gitignore (per-developer overrides)
L’expérience
Lors de la phase d’expérimentation, notez d’abord les conditions du contrat : les entrées requises, le signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le processus passe de la démonstration aux environnements partagés. Conservez un journal avec le nom de l’outil, son hash des arguments, la latence et le résultat de chaque appel. Sans ces traces, le débogage de boucles d’agent prend des heures. Lors de la phase d’expérimentation, notez d’abord les conditions du contrat : les entrées requises, le signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Documentez ensemble le parcours normal et les scénarios de récupération. Les tentatives de réessai, les contrôles humains et la gestion des messages non livrés font partie intégrante du produit, et non d’améliorations ultérieures.
make serena-up # Start the Serena container
make serena-stop # Stop it
make serena-logs # Tail logs
make serena-index # Force re-index after big changes
make serena-health # Health check the workspace
Pensées finales
La phase des Réflexions finales fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un transcript parfait, un cas d’échec et la note de rollback avant d’élargir le périmètre. Préférez des unités petites et testables aux scripts complexes. Lorsqu’une étape échoue, l’échec doit pointer vers une seule responsabilité plutôt qu’un processus embrouillé. Exposez des outils dotés de schémas restreints et de labels explicites indiquant les effets secondaires. Les administrateurs doivent savoir quels appels modifient l’état avant d’approuver automatiquement.
Liste de contrôle opérationnelle
Lorsque vous travaillez sur la phase de la Liste de contrôle opérationnelle, écrivez d’abord le contrat : les entrées requises, le signal de succès et ce qui se passe en cas d’échec partiel. Cette liste garantit que les modifications ultérieures du code restent transparentes.
Gardez la configuration en dehors du code de l’application. Les fichiers d’environnement, les bases de données secrètes et les flags fonctionnels doivent être regroupés en un seul endroit que les administrateurs peuvent auditer sans devoir lire l’ensemble du système.
Enregistrez le nom de l’outil, le hash des arguments, la latence et le résultat de chaque appel. Sans cette trace, les boucles du agent de débogage font perdre des heures.
Fixez les versions des dépendances et enregistrez le digest de l’image ayant exécuté la démonstration. La reproductibilité vaut mieux que les connaissances internes au groupe.
Dokumentez à la fois le parcours normal et celui de récupération. Les tentatives répétées, les contrôles humains et la gestion des messages échoués font partie intégrante du produit, et non d’une amélioration ultérieure.
Enregistrez le nom de l’outil, le hash des arguments, la latence et le résultat de chaque appel. Sans cette trace, les boucles du agent de débogage font perdre des heures.
Au préalable de promouvoir l’ensemble technologique, figez les versions, capturez une transcription exemplaire pour le parcours critique et confirmez les étapes de rollback. Les environnements partagés nécessitent des limites de fréquence, des vérifications de location et un responsable clair pour la rotation des secrets. Préférez une fiabilité banale à de brillantes démonstrations ponctuelles.
Remarque de lot pour 1c6261938c06 : ne pas inclure les clés du fournisseur dans le répertoire, fixer une limite pour les tokens par session, et stocker les transcriptions à côté des fichiers d’évaluation afin que les remplacements ultérieurs de modèles restent comparables.