De v0.1 à v0.5 : comment Semantiq est devenu un serveur MCP production-ready

En bref : En seulement 4 semaines, Semantiq est passé d'un proof-of-concept MCP avec 9 langages et une recherche FTS5 basique à un outil production-ready avec recherche sémantique ONNX, support de 19 langages, seuils ML adaptatifs et plusieurs passes de renforcement sécurité. Voici l'histoire complète.

Le commencement : v0.1.0 — Un proof of concept#

Le 17 janvier 2026, la première version de Semantiq a été publiée. Elle était simple : un serveur MCP avec 4 outils (search, find_refs, deps, explain), le support de 9 langages via tree-sitter et un backend SQLite avec recherche FTS5.

1# La toute première expérience Semantiq
2npm install -g semantiq-mcp
3semantiq index .
4semantiq search "authentication handler"

L'idée centrale était déjà là — donner aux assistants IA une compréhension sémantique des bases de code via le protocole MCP. Mais l'implémentation était basique : une recherche textuelle sans véritable compréhension sémantique.

Architecture initiale#

La v0.1.0 reposait sur une architecture simple mais fonctionnelle :

1┌─────────────────┐     ┌──────────────┐     ┌─────────────┐
2│  Client MCP     │────▶│  Serveur     │────▶│  SQLite +   │
3│  (Claude Code)  │     │  Semantiq    │     │  FTS5       │
4└─────────────────┘     └──────────────┘     └─────────────┘
5                              │
6                              ▼
7                        ┌──────────────┐
8                        │  Tree-sitter │
9                        │  (9 langages)│
10                        └──────────────┘

Les 9 langages initiaux étaient : TypeScript, JavaScript, Python, Rust, Go, Java, C, C++ et Ruby. Le choix de ces langages reflétait les besoins les plus courants de la communauté développeur.

Le même jour, trois nouvelles versions ont suivi rapidement :

• v0.1.1 a corrigé la documentation npm et les métadonnées du package
• v0.1.2 a ajouté l'auto-indexation avec surveillance de fichiers via notify — plus de ré-indexation manuelle nécessaire
• v0.1.3 a introduit la commande semantiq init pour une configuration Claude Code en une étape, générant automatiquement le fichier mcp_config.json

Le rythme était donné : livrer vite, itérer encore plus vite.

La révolution de la recherche sémantique : v0.2.x#

v0.2.1 — Le réveil sécurité#

Avant d'ajouter des fonctionnalités, l'équipe a résolu des problèmes de fondation critiques. La v0.2.1 était une release qualité :

Corrections de sécurité :

• Prévention d'injection SQL via l'échappement LIKE avec escape_like_pattern()
• Sécurité UTF-8 dans l'extraction tree-sitter pour éviter les panics sur les caractères invalides
• Validation des entrées utilisateur avant traitement

Optimisations de performance :

• Correction d'une requête N+1 qui a réduit 4 requêtes base de données en 1, améliorant les temps de réponse de 60%
• Mise en cache des résultats de parsing tree-sitter

Stabilité :

• Gestion correcte des erreurs de mutex avec RwLock pour éviter les deadlocks
• Timeouts configurables sur les opérations de base de données

Cette attention précoce à la sécurité allait devenir un thème récurrent tout au long du développement.

v0.2.3 — Les embeddings ONNX changent tout#

Ce fut une release charnière. Semantiq a intégré les modèles d'embedding ONNX pour une vraie recherche sémantique. Au lieu de simplement faire correspondre du texte, Semantiq générait maintenant des embeddings vectoriels pour les blocs de code et utilisait la similarité cosinus pour trouver du code sémantiquement lié.

Cela a fait une grande différence pratique. Avant la v0.2.3, chercher "authentication handler" ne trouvait que du code contenant ces mots exacts. Après la v0.2.3, il pouvait trouver verifyCredentials(), checkJWT() et loginUser() — du code qui signifie la même chose mais utilise une terminologie complètement différente.

1# Avant : recherche textuelle uniquement
2semantiq search "auth"  # Ne trouve que les correspondances littérales "auth"
3
4# Après : recherche sémantique
5semantiq search "flux d'authentification utilisateur"
6# Trouve : verifyCredentials, checkJWT, loginUser, validateSession

Détails techniques de l'implémentation :

L'implémentation utilise MiniLM-L6-v2, un modèle d'embedding compact qui s'exécute localement via ONNX Runtime. Le modèle génère des vecteurs de 384 dimensions pour chaque bloc de code.

1// Pipeline d'embedding simplifié
21. Extraction du code source via tree-sitter
32. Tokenization avec le tokenizer HuggingFace
43. Inférence ONNX pour générer le vecteur 384-dim
54. Stockage dans sqlite-vec pour recherche rapide
65. Calcul de similarité cosinus lors des requêtes

Le choix de MiniLM-L6-v2 était un compromis entre qualité et performance :

• Taille du modèle : 90 Mo (vs 400+ Mo pour les modèles plus grands)
• Latence d'inférence : ~15 ms par bloc de code
• Qualité : 95% de la performance de modèles 4x plus grands sur les benchmarks de similarité sémantique

Pas d'API cloud, aucune donnée ne quitte la machine du développeur.

v0.2.4 — Corriger ce qu'ONNX a cassé#

Le déploiement réel a exposé des problèmes que les tests unitaires n'avaient pas révélés :

Problème 1 : Conflit Tokio/blocking

1// AVANT : causait des deadlocks
2let response = reqwest::blocking::get(url)?;
3
4// APRÈS : compatible async
5let response = ureq::get(url).call()?;

Le téléchargement du modèle ONNX échouait dans les contextes async Tokio. La solution a été de remplacer reqwest::blocking par ureq, une librairie HTTP synchrone sans dépendance async.

Problème 2 : Limite de téléchargement La limite de taille de téléchargement par défaut (10 Mo) était trop petite pour le modèle de 90 Mo. Corrigé en ajustant la configuration du client HTTP.

Problème 3 : Input ONNX manquant L'inférence ONNX plantait silencieusement à cause d'un input token_type_ids manquant. Le modèle MiniLM attend trois inputs : input_ids, attention_mask et token_type_ids. L'omission du dernier causait des résultats incorrects sans erreur explicite.

Cette release a enseigné une leçon importante : intégrer des modèles ML dans un outil système nécessite une attention particulière à la compatibilité runtime et une validation exhaustive des inputs/outputs.

v0.2.6 — Ré-indexation intelligente#

Un point de douleur développeur résolu : quand la logique du parser changeait entre les versions, les utilisateurs devaient manuellement exécuter semantiq index --force. La v0.2.6 a introduit une constante PARSER_VERSION qui déclenche une ré-indexation automatique quand elle change. Mises à jour transparentes, aucune action utilisateur requise.

Cette version a aussi amélioré le support TypeScript/JavaScript en extrayant les déclarations de variables const/let.

v0.2.8 — La grande passe sécurité#

Ce fut la première release majeure de renforcement sécurité :

• Vérification de checksum SHA-256 pour les téléchargements de modèles ONNX (modèle TOFU)
• Protection contre le path traversal avec canonicalisation
• Limites de récursion AST (profondeur max 500) pour prévenir les attaques de stack overflow
• Prévention d'épuisement mémoire via la pagination des requêtes d'embeddings
• Permissions de fichiers restrictives (0600 sur Unix) pour la base de données et les modèles
• Gestion des symlinks pour empêcher l'évasion de la racine du projet

Chaque correction adressait un vecteur d'attaque réel. La philosophie : un outil qui manipule du code source doit être digne de confiance.

La maturité : v0.3.x#

v0.3.0 — La refonte architecturale#

Ce fut la plus grande release à ce jour. Trois changements majeurs :

1. Intégration sqlite-vec a remplacé la recherche vectorielle custom par une vraie recherche par similarité vectorielle utilisant des embeddings MiniLM-L6-v2 en 384 dimensions
2. Indexation initiale automatique au démarrage du serveur MCP — plus besoin de l'étape manuelle semantiq index
3. 6 nouveaux langages : HTML, JSON, YAML, TOML, Bash et Elixir (portant le total à 15)

Plus l'intégration de ripgrep pour la recherche textuelle rapide, créant le moteur de recherche hybride à 4 stratégies qui définit Semantiq aujourd'hui :

v0.3.1 — Support Cursor#

La commande init-cursor a apporté un support Cursor/VS Code de première classe. Elle génère .cursor/mcp.json, crée les fichiers de règles Cursor, configure VS Code et gère .cursorignore. Une commande, intégration IDE complète.

v0.3.3 — Filtrage de recherche#

Les utilisateurs avancés avaient besoin de plus de contrôle. La v0.3.3 a ajouté les paramètres min_score, file_type et symbol_kind à semantiq_search. Vous pouviez maintenant dire "trouver les fonctions liées à l'authentification dans les fichiers TypeScript avec au moins 50% de pertinence" :

semantiq search "authentication" --min-score 0.5 --file-type ts --symbol-kind function

v0.3.4 — Parité des plateformes#

Le support macOS Intel a été restauré en rendant ONNX optionnel. Les Mac Intel utilisent un modèle d'embedding stub (recherche sémantique désactivée), mais toutes les autres fonctionnalités marchent. Aucune plateforme laissée pour compte.

Production ready : v0.4.0 et v0.5.x#

v0.4.0 — Logging structuré et tests#

Le passage d'outil de développement à logiciel de production. Logging JSON dans toute la base de code, couverture de tests MCP complète et workflows CI/sécurité. La commande serve produit maintenant des logs JSON structurés par défaut pour l'intégration avec les agrégateurs de logs.

v0.5.0 — Seuils ML adaptatifs#

La release la plus techniquement complexe. Semantiq calibre maintenant automatiquement les seuils de recherche sémantique par langage de programmation :

1. Mode bootstrap : collecte 100% des observations de distance jusqu'à 500 échantillons
2. Mode production : passe à 10% d'échantillonnage après le bootstrap
3. Auto-calibration : utilise les percentiles p90/p10 pour définir les seuils optimaux
4. Réglage par langage : le code Rust a des caractéristiques d'embedding différentes du Python — Semantiq s'adapte

Cela signifie que la qualité de recherche s'améliore automatiquement à mesure que vous utilisez l'outil. Aucun réglage manuel requis.

La release incluait aussi un effort de refactoring massif : store.rs (2 108 lignes) a été découpé en 8 modules, et engine.rs (1 049 lignes) en 5 modules.

v0.5.2 — Renforcement sécurité, round 2#

La dernière release s'est concentrée entièrement sur la sécurité :

• Prévention ReDoS : input utilisateur échappé avec regex::escape()
• Mise à jour de dépendance : crate bytes patchée pour un integer overflow (RUSTSEC-2026-0007)
• Protection des fichiers sensibles : le walker de recherche textuelle exclut maintenant .env, .git/
• Corrections de path traversal : canonicalisation dans read_file_lines()
• Validation d'input : limites de longueur, vérifications de vide sur tous les handlers MCP
• Prévention d'amplification de requêtes : expansion limitée à 10 termes
• Sanitisation des messages d'erreur : aucun chemin interne divulgué aux clients

En chiffres#

Leçons apprises#

Le développement de Semantiq sur ces 4 semaines intensives a été riche en enseignements. Voici les leçons que nous retenons.

1. La sécurité doit être intégrée dès le départ#

Nous avons effectué deux passes de renforcement sécurité majeures (v0.2.8 et v0.5.2). Si la sécurité avait été une priorité dès v0.1.0, beaucoup de ces corrections auraient été évitées. Les vecteurs d'attaque identifiés (injection SQL, path traversal, ReDoS) sont classiques mais faciles à négliger dans la course aux fonctionnalités.

Règle adoptée : chaque nouveau handler MCP passe maintenant par une checklist sécurité avant merge.

2. L'intégration ML demande de l'humilité#

Intégrer ONNX semblait simple sur le papier. En pratique, nous avons rencontré des incompatibilités runtime (Tokio vs blocking), des inputs manquants, des problèmes de téléchargement, et des edge cases sur différentes architectures (Intel vs ARM).

Leçon : les modèles ML ne sont pas des boîtes noires plug-and-play. Comprendre leur fonctionnement interne est essentiel pour les intégrer correctement.

3. L'auto-calibration vaut l'investissement#

Les seuils ML adaptatifs de v0.5.0 ont demandé un effort de développement significatif. Mais le résultat — une qualité de recherche qui s'améliore automatiquement — justifie largement cet investissement. Les utilisateurs n'ont pas à comprendre les paramètres pour obtenir de bons résultats.

4. La modularité facilite l'évolution#

Le refactoring de v0.5.0 (découpage de store.rs en 8 modules et engine.rs en 5 modules) a rendu le code beaucoup plus maintenable. Ajouter de nouveaux langages ou de nouvelles stratégies de recherche est maintenant trivial.

5. Le support multi-plateforme est critique#

La décision de rendre ONNX optionnel pour les Mac Intel (v0.3.4) a permis de garder une base d'utilisateurs qui aurait autrement été exclue. Aucune plateforme ne devrait être laissée pour compte.

Prochaines étapes : roadmap v0.6+#

Semantiq est maintenant un serveur MCP mature et production-ready. Mais la roadmap continue avec des fonctionnalités à venir.

v0.6.0 — Compréhension inter-fichiers (Q1 2026)#

La prochaine évolution majeure : comprendre comment les données et le contrôle circulent entre les fichiers.

Fonctionnalités prévues :

• Analyse du graphe d'appels complet
• Traçage des flux de données (data flow analysis)
• Détection des chemins d'exécution critiques
• Visualisation des dépendances inter-modules

# Prévu pour v0.6
semantiq trace "getUserById" --full-callgraph
semantiq dataflow "UserInput" --sinks

v0.7.0 — Langages supplémentaires (Q2 2026)#

Expansion du support de langages pour couvrir les besoins de plus de développeurs :

v0.8.0 — Fonctionnalités équipe (Q2 2026)#

Pour les équipes de développement, nous prévoyons :

• Index partagés : synchronisation des index entre membres de l'équipe
• Serveur Semantiq centralisé : un serveur MCP partagé pour toute l'équipe
• Intégration CI/CD : vérification de la qualité sémantique dans les pipelines
• Métriques de base de code : tableaux de bord de complexité et de cohésion

v1.0.0 — Stabilité API (Q3 2026)#

La version 1.0 marquera la stabilisation de l'API MCP et des formats d'index. Les garanties de compatibilité ascendante permettront aux équipes d'adopter Semantiq avec confiance.

Engagements v1.0 :

• API MCP stable et documentée
• Format d'index versionné avec migration automatique
• Support long-terme (LTS) de 2 ans
• Certification sécurité indépendante

Et au-delà...#

Des idées exploratoires pour le futur :

• Embeddings spécialisés par langage : fine-tuning de modèles pour chaque langage
• Recherche multimodale : intégration documentation + code + tests
• Suggestions proactives : l'IA qui suggère des refactorings basés sur l'analyse sémantique
• Plugin IDE natif : intégration directe dans VS Code sans passer par MCP

Et maintenant ?#

La fondation est solide. Chaque release construit sur les principes établis dès le premier jour : vitesse (Rust), intelligence (embeddings ONNX), confidentialité (100% local) et universalité (protocole MCP).

Le chemin parcouru en 4 semaines et 21 releases démontre qu'un outil peut évoluer rapidement tout en maintenant des standards de qualité élevés. La clé : des releases fréquentes, une écoute active de la communauté et une volonté constante d'amélioration.

Vous voulez essayer Semantiq ? Ça prend 30 secondes :

npm install -g semantiq-mcp
semantiq init

Votre assistant IA vous remerciera.