Guide d'Utilisation
Voilà comment tirer le max des 4 outils MCP de Semantiq. On passe direct aux exemples.
semantiq_search
L'outil principal. Trouve du code par le sens, pas juste les mots-clés.
Paramètres
| Param | Type | Défaut | Ce que ça fait |
|---|---|---|---|
query | string | — | Ce que tu cherches |
limit | number | 20 | Nombre max de résultats |
min_score | float | 0.35 | Seuil (0.0-1.0) |
file_type | string | — | ex: ts,tsx,py |
symbol_kind | string | — | function, class, interface... |
En pratique
Chercher un concept :
1→ semantiq_search("authentication handler")23src/auth/handler.ts:23 [0.89]4 function handleAuth(req: Request): Promise<User>56src/middleware/auth.ts:45 [0.76]7 export const authMiddleware = async (ctx) => {...}89src/utils/token.ts:12 [0.71]10 function verifyToken(token: string): booleanIl a trouvé verifyToken alors que "authentication" n'est pas dans le nom. C'est ça le côté sémantique.
Affiner les résultats :
1→ semantiq_search("User", symbol_kind: "interface")23src/types/user.ts:5 [0.95]4 interface User { id: string; email: string; ... }56src/types/auth.ts:12 [0.82]7 interface UserCredentials { email: string; ... }Quand tu veux de la précision :
Mets min_score: 0.7 ou plus. Moins de résultats, mais pile ce qu'il faut.
semantiq_explain
Pour comprendre ce que fait un symbole sans lire tout le fichier.
Paramètres
| Param | Type | Ce que ça fait |
|---|---|---|
symbol | string | Le truc à expliquer |
En pratique
1→ semantiq_explain("handleAuth")23FUNCTION: handleAuth4Location: src/auth/handler.ts:23-4556async function handleAuth(7 req: Request,8 options?: AuthOptions9): Promise<User>1011Doc: Handles user authentication by verifying12credentials and returning the authenticated user.1314Related:15 → User (return type)16 → AuthOptions (param)17 → verifyToken (called inside)18 → authMiddleware (caller)Tu récupères la signature, la doc s'il y en a, et ce qui est connecté. Sans fouiller dans le fichier.
semantiq_deps
Montre le réseau d'imports/exports autour d'un fichier. Indispensable avant de toucher à du code partagé.
Paramètres
| Param | Type | Ce que ça fait |
|---|---|---|
file_path | string | Fichier à analyser |
En pratique
1→ semantiq_deps("src/auth/handler.ts")23IMPORTS (ce qu'il utilise):4 src/types/user.ts → User, UserRole5 src/utils/token.ts → verifyToken, generateToken6 src/config/auth.ts → authConfig7 src/db/users.ts → findUserByEmail89DEPENDENTS (ce qui l'utilise):10 src/middleware/auth.ts → handleAuth11 src/routes/api.ts → handleAuth12 src/tests/auth.test.ts → handleAuthPour les utilitaires centraux :
1→ semantiq_deps("src/utils/token.ts")23IMPORTS: 2 fichiers4DEPENDENTS: 8 fichiers56⚠ Fichier à fort impactBeaucoup de dépendants = prudence.
semantiq_find_refs
Trouve tous les endroits où un symbole est utilisé. À utiliser avant le refactoring.
Paramètres
| Param | Type | Défaut | Ce que ça fait |
|---|---|---|---|
symbol | string | — | Ce qu'on cherche |
limit | number | 50 | Max de refs |
En pratique
1→ semantiq_find_refs("handleAuth")23DEFINITION4 src/auth/handler.ts:235 export async function handleAuth(req: Request)67USAGES8 src/middleware/auth.ts:129 const user = await handleAuth(ctx.request);1011 src/routes/api.ts:4512 router.post('/login', (req) => handleAuth(req));1314 src/tests/auth.test.ts:2315 const result = await handleAuth(mockRequest);1617 src/tests/auth.test.ts:5618 expect(handleAuth(invalidReq)).rejects.toThrow();Contrairement à grep, ça distingue les définitions des utilisations. Zéro bruit.
Vitesse
| Outil | Typique | Gros projet |
|---|---|---|
semantiq_search | ~45ms | ~120ms |
semantiq_explain | ~30ms | ~60ms |
semantiq_deps | ~25ms | ~80ms |
semantiq_find_refs | ~40ms | ~100ms |
Tous les outils répondent en moins de 120ms, même sur de gros projets.
Conseils
Sur les requêtes :
- "authentication handler" > "auth" — sois spécifique
- Le langage naturel marche : "function that validates user input"
- Combine les filtres :
file_type: "ts"+symbol_kind: "function"
Sur min_score :
- 0.3 → exploration, large filet
- 0.5-0.6 → tu cherches un truc précis
- 0.7+ → il te faut exactement ça
Pattern de travail :
semantiq_searchpour trouver des candidatssemantiq_explainsur les résultats intéressantssemantiq_depsavant de modifier quoi que ce soitsemantiq_find_refsavant de renommer
Voir aussi
- Référence CLI - Documentation complète des commandes
- Workflow optimal - Combiner Semantiq avec les outils natifs
- Semantiq vs grep/find - Comparaison détaillée des outils