find_code
Paste a line, hunt a topic, or find every occurrence — ranked hits with the matching line in place.
Zephex is a hosted Model Context Protocol (MCP) server that gives AI coding agents fast codebase search through find_code — plus nine other developer tools and one API key — without installing ripgrep MCP servers on every laptop.
When to use
- Paste an exact line from the editor — intent snippet shows it at each file:line.
- Hunt vague topics (encrypt, messaging, storage) — intent concept + also_try synonyms.
- Locate a named function, class, or type — intent symbol.
- Map every occurrence before a rename — intent everywhere.
- Web terminal: paste a code line with no command, or use paste / locate / count / rename — pair with summarize for file overviews.
When not to use
- You already know the exact file and symbol name — use read_code directly.
- You need project stack or test commands — use get_project_context first on new repos.
- You need semantic “code similar to this” search — find_code is text-based, not embeddings.
- You need package registry safety — use check_package.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| query | string | Yes | Search text — symbol, topic, or pasted line. |
| path | string | Yes* | Search root: any absolute folder on Mac/PC or github:owner/repo. |
| intent | enum | No | snippet | symbol | concept | everywhere. Auto-detected when omitted. |
| also_try | string[] | No | Up to 4 synonym queries for concept hunts. |
| include | enum | No | all | code | docs | config | data — preset globs for messy repos. |
| file_pattern | string | No | Precise glob; overrides include. |
| whole_word | boolean | No | Whole-word match — rename Crystal without Crystalline. |
| case_sensitive | boolean | No | Crystal vs crystal (default insensitive). |
| inline_files | object | No | Path→content when hosted cannot read disk. |
| response_format | enum | No | concise | detailed (AST enclosing block). |
Limits: Text search only. Large repos may take longer (single rg thread by design). ~50 searches/hour per user on hosted rate limits when enforced.
Try it — copy a prompt
Paste into Cursor, Claude Code, Windsurf, VS Code, or any editor with a hosted MCP connection.
Before you call it
- Zephex hosted MCP with a valid API key.
- Absolute project path or github:owner/repo as path.
- A concrete query string (pasted line, symbol name, or topic keyword).
Token and request cost
Responses are envelope-shaped with concise line previews (~120 chars per hit). Follow next_calls → read_code on the top hit instead of opening guessed files.
Example
MCP tools/call
{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "find_code", "arguments": { "query": "validateApiKey", "path": "/path/to/project", "intent": "symbol", "response_format": "detailed" } }}Response shape
Response shape
intent: symbolsummary: symbol · 3/12 hits · 2 filesdata.matches[0]: src/lib/auth.ts:42 validateApiKey(apiKey: string)data.files_hit: [{ file, line_count, lines, sample_line }]next_calls: read_code({ target: "validateApiKey", mode: "symbol", path: "..." })Which Zephex tool when
| Task | Use this tool | Not this tool |
|---|---|---|
| Find file for a symbol | find_code | read_code |
| Read function implementation | read_code | find_code |
| Project stack / test command | get_project_context | find_code |
| Package exists / typosquat | check_package | find_code |
What it can do in your codebase
- Four intents: snippet, symbol, concept, everywhere — auto-detected when omitted
- snippet — paste-a-line; 1 file or 5 files, each shows that line at that line number
- concept + also_try — encrypt, cipher, E2E in one call
- symbol — definitions ranked first; detailed mode returns AST enclosing blocks
- everywhere — all file:line hits before large refactors
- Restrict with file_pattern (`src/**/*.ts`)
- BM25 ranking puts the real definition above noise
- Returns files_hit per-file line lists + next_calls → read_code
- Search github:owner/repo (first clone may take 15–45s, then cached)
- Always excludes .env, keys, node_modules — forced security excludes
Common response fields
Why teams use it
Paste-a-line that actually works
Pass the exact line as query with intent snippet — every matching file shows file:line and that line in place.
One intent, not ten knobs
Agents pick snippet / symbol / concept / everywhere instead of juggling scope, exhaustive, max_tokens, and max_results.
Editor-agnostic
Same hosted tool in Cursor, Claude Code, Windsurf, VS Code, and other MCP editors.
Pairs with read_code
find_code finds the needle; read_code pulls signature, body, and callers via next_calls.
What it looks at vs skips
- Source files under project path (honoring excludes)
- Ripgrep JSON with context lines
- AST expansion to function/class boundaries (symbol/concept detailed mode)
- Multi-query fan-out for concept + also_try
- Semantic similarity / embedding search
- Secret paths even if requested
- Full type inference or LSP-grade references
- Reading entire files when a line preview is enough
Query mode examples
snippet
const payment = await stripe.charges.create({
Paste the exact line — every file:line hit, line shown in place.
symbol
validateApiKey
Known identifier — definitions ranked first.
concept
encrypt + also_try: [cipher, E2E, sealed]
Topic hunt — parallel synonym fan-out, merged and deduped.
everywhere
oldHandlerName
Every occurrence — up to 500 file:line hits + files_summary.
Search intents
How it fits your workflow
- get_project_context on a new repo (optional but recommended)
- find_code — intent + summary + data.matches + files_hit
- read_code — follow next_calls on the best hit
Troubleshooting
- Too many noise hits → intent symbol or narrow file_pattern (src/**/*.ts).
- Empty results on a topic → intent concept with also_try synonyms.
- Paste-a-line missed → intent snippet (auto-detected for long/multi-line queries).
- Private github: repo → ensure GitHub auth; first scan may be slow, then cached.
- 429 → hosted rate limits apply; narrow query or wait for Retry-After.
How to verify it works
- Connect Zephex MCP and confirm find_code appears in tools/list.
- Ask: find_code with intent symbol for a name you know exists — show file:line.
- Response should include intent, summary, data.matches; follow next_calls → read_code.
Common questions
Billing and plan limits: FAQ, usage limits.
How is find_code different from read_code?
find_code searches text across the repository and returns ranked locations in an envelope. read_code extracts a known symbol’s implementation from a file you already identified. Use find_code when you do not know the file; use read_code when you do.
How do I search for a line I copied from the editor?
Pass the exact line as query with intent snippet (auto-detected for multi-line or long queries). You get every file:line where that line appears, with the matching line shown in place.
How do I hunt encryption or messaging across the repo?
Use intent concept with also_try for synonyms: find_code({ query: "encrypt", also_try: ["cipher", "E2E", "sealed"], intent: "concept" }). Results merge and dedupe across all terms.
Does find_code work with private GitHub repositories?
Yes on Zephex hosted MCP when the server has access via GITHUB_PAT or your linked GitHub account. Pass github:owner/repo as path. First scan may take longer; later calls use cache.
Which Zephex tool should I use to find where a function is defined?
Use find_code with intent symbol and the function name. Then follow next_calls to read_code on the top hit for the full body.
How do I find every usage before a rename?
Use intent everywhere — lists up to 500 file:line hits and files_summary. Pair with read_code on the definition hit first.
After you have a hit, read_code returns the full symbol and optional callers.
Billing: Each tool call counts as one request on your Zephex plan (Free includes 555 requests/month). See usage limits for tier details. Usage limits.
Data: Search runs on paths you authorize; .env and credential paths are blocked. Query text is validated; results are ephemeral. Data use.
Editor search and raw ripgrep return lines; find_code adds intents, BM25 ranking, files_hit summaries, and next_calls for agents — different from library documentation at Zephex vs Context7.
For AI agents (JSON)
{"tool":"find_code","when":"unknown file for name, line, or topic","then":"read_code via next_calls"}