Practical Usage Guide
Here's how to get the most out of Semantiq's 4 MCP tools. Skip the theory - let's see what they actually do.
semantiq_search
The main workhorse. Finds code by meaning, not just keywords.
Parameters
| Param | Type | Default | What it does |
|---|---|---|---|
query | string | — | What you're looking for |
limit | number | 20 | Max results |
min_score | float | 0.35 | Threshold (0.0-1.0) |
file_type | string | — | e.g. ts,tsx,py |
symbol_kind | string | — | function, class, interface... |
In practice
Search for a 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): booleanNotice: it found verifyToken even though "authentication" isn't in the name. That's the semantic part.
Narrow it down:
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; ... }When you need precision:
Set min_score: 0.7 or higher. You'll get fewer results, but they'll be spot on.
semantiq_explain
Quick way to understand what a symbol does without reading the whole file.
Parameters
| Param | Type | What it does |
|---|---|---|
symbol | string | The thing you want explained |
In practice
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)Saves you from hunting through the file. You get the signature, the docs if any, and what's connected to it.
semantiq_deps
Shows you the import/export web around a file. Essential before touching shared code.
Parameters
| Param | Type | What it does |
|---|---|---|
file_path | string | File to analyze |
In practice
1→ semantiq_deps("src/auth/handler.ts")23IMPORTS (what it uses):4 src/types/user.ts → User, UserRole5 src/utils/token.ts → verifyToken, generateToken6 src/config/auth.ts → authConfig7 src/db/users.ts → findUserByEmail89DEPENDENTS (what uses it):10 src/middleware/auth.ts → handleAuth11 src/routes/api.ts → handleAuth12 src/tests/auth.test.ts → handleAuthFor core utilities:
1→ semantiq_deps("src/utils/token.ts")23IMPORTS: 2 files4DEPENDENTS: 8 files56⚠ High-impact fileIf you see lots of dependents, tread carefully.
semantiq_find_refs
Find everywhere a symbol is used. Use this before refactoring.
Parameters
| Param | Type | Default | What it does |
|---|---|---|---|
symbol | string | — | What to find |
limit | number | 50 | Max refs |
In practice
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();Unlike grep, this distinguishes definitions from usages. No noise.
Speed
| Tool | Typical | Large codebase |
|---|---|---|
semantiq_search | ~45ms | ~120ms |
semantiq_explain | ~30ms | ~60ms |
semantiq_deps | ~25ms | ~80ms |
semantiq_find_refs | ~40ms | ~100ms |
All tools respond in under 120ms, even on large codebases.
Tips
On queries:
- "authentication handler" beats "auth" — be specific
- Natural language works: "function that validates user input"
- Stack filters:
file_type: "ts"+symbol_kind: "function"
On min_score:
- 0.3 → exploring, cast a wide net
- 0.5-0.6 → looking for something specific
- 0.7+ → need exact matches
Workflow pattern:
semantiq_searchto find candidatessemantiq_explainon promising hitssemantiq_depsbefore modifying anythingsemantiq_find_refsbefore renaming
See Also
- CLI Reference - Complete command documentation
- Optimal Workflow - Combine Semantiq with native tools
- Semantiq vs grep/find - Detailed tool comparison