read_code
Pull the exact function or class—not the whole 600-line file.
Zephex is a hosted Model Context Protocol (MCP) server that gives AI coding agents surgical code reading through read_code—Tree-sitter symbol extraction plus nine other tools and one API key—without pasting entire files into chat.
When to use
- You know (or just found) the file and need the real implementation.
- You want signature + body + imports for one function or class.
- A file is hundreds of lines—outline first, then symbol mode.
- You need callers, blast radius, or dead-code hints on a local repo.
When not to use
- You do not know which file contains the code—use find_code first.
- You need stack detection or npm scripts—use get_project_context.
- The file is tiny (<50 lines)—native editor read may be faster.
- You need callers on a remote github: URL only—use find_code scope usages.
Use from the terminal (no editor)
Seven short terminal commands — same read_code MCP as the editor. Run from your project root after npx zephex setup. Legacy names (files, outline, callers, dead-code) still work but are not listed here.
Terminal commands
npx zephex symbol handleAuthnpx zephex read src/a.ts src/b.tsnpx zephex summarize src/big.tsnpx zephex scan TODO,FIXME src/a.tsnpx zephex smell src/a.tsnpx zephex who validateTokennpx zephex who validateToken --blastnpx zephex dead # paginate a huge filenpx zephex read src/big.ts --from 401 --lines 200 # natural languagenpx zephex "what does validateToken do"Say it in plain English
npx zephex "what does handleAuth do"npx zephex summary src/middleware.ts
symbol --detail-level context · read --from/--lines · who --blast (local repo only). Full MCP: npx zephex symbol --help or --json.
More: Terminal CLI reference, complete terminal guide — packages. Run npx zephex cli-guide packages or npx zephex help terminal.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| path | string | Yes* | Absolute or github:owner/repo. |
| mode | enum | No | symbol | file | outline | callers | blast_radius | dead_code |
| target | string | No | Symbol name. |
| targets | string[] | No | Up to 8 symbols. |
| files | string[] | No | For file/outline. |
| detail_level | enum | No | signature | body | context |
| max_tokens | number | No | Default 2000, max 8000. |
| compact | boolean | No | Smaller output. |
Limits: Call-graph modes need local absolute path and warmed index. Remote scans may cap file count. ~100 calls/hour when rate-limited on hosted.
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 API key and hosted MCP in your editor.
- Absolute path or github:owner/repo (call-graph modes need a local absolute path).
- Known file path (from find_code or get_project_context key_files) or symbol name for fuzzy match.
Token and request cost
Focused symbol reads are usually 300–900 tokens. Dumping a whole 500-line file plus neighbors is often 1,500–8,000 tokens—read_code typically lands at 10–35% of that. Responses may include tokens_saved_vs_full_files.
Example
MCP tools/call
{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "read_code", "arguments": { "path": "/path/to/project", "mode": "file", "files": ["src/lib/auth.ts", "src/middleware/rate-limit.ts", "src/handlers/login.ts"] } }}Response shape
Response shape
{ "mode": "file", "summary": "file · 3/3 paths · 4200/4800 tokens", "data": { "files": [ { "file": "src/lib/auth.ts", "returned_lines": 120, "truncated": false }, { "file": "src/middleware/rate-limit.ts", "returned_lines": 85, "truncated": false }, { "file": "src/handlers/login.ts", "returned_lines": 64, "truncated": false } ], "files_returned": 3 }, "next_calls": []}Which Zephex tool when
| Task | Use this tool | Not this tool |
|---|---|---|
| Known file + symbol | read_code | find_code |
| Unknown which file | find_code | read_code |
| Large file TOC first | read_code outline | read_code file (whole) |
| Callers on remote repo | find_code usages | read_code callers |
What it can do in your codebase
- Extract functions, classes, methods, types, hooks, components across 20+ languages
- Fuzzy match symbols with confidence scores; filter by kind
- Batch up to 8 targets in one MCP call
- outline mode — table of contents before editing large files
- file mode — paginate 1–20 files with offset_line / limit_lines inside max_tokens
- detail_level signature | body | context (imports + usages)
- See usages and related test files when available
- callers, blast_radius, dead_code via local SQLite call-graph index
- Rank real exports above jest mocks and .d.ts stubs
- compact mode strips line numbers to save tokens
- session_id stubs symbols already returned in the thread
- Read github:owner/repo or inline_files when disk is unavailable
- Report tokens_saved_vs_full_files in the response
Common response fields
Why teams use it
Token discipline by design
Built for long agent sessions where every thousand tokens matters—common reason teams pick hosted Zephex over raw file attachments.
symbol_id direct lookup
Skip fuzzy search when you have a stable id like src/auth.ts::hashApiKey#function.
Remote + inline
GitHub/GitLab/Bitbucket URLs; inline_files map when the transport has no filesystem.
Honest fallbacks
Unsupported languages may return ripgrep snippets with fallback flags—still better than guessing.
What it looks at vs skips
- Ripgrep prefilter for files containing the symbol
- Tree-sitter WASM parse per supported language
- Usage snippets via ripgrep
- Call-graph index (local) for callers / blast radius / dead code
- Whole-repo text search
- Project manifest orientation
- Call-graph on remote URLs without local index
- Guaranteed perfect callers under heavy metaprogramming
Modes
How it fits your workflow
- get_project_context — key_files and stack
- find_code — locate file:line
- read_code — body + callers on the symbol you will change
Troubleshooting
- Symbol not found → lower confidence_threshold or use fuzzy target; confirm file path with find_code first.
- callers / blast_radius empty → requires local absolute path and warmed call-graph index.
- Truncated body → raise max_tokens or read a smaller symbol batch (max 8 targets).
- Wrong match → pass files[] to narrow; use outline on 300+ line files before symbol mode.
How to verify it works
- Connect Zephex MCP; confirm read_code in tools/list.
- After find_code locates a symbol, ask: “read_code validateApiKey with detail_level context.”
- Confirm response has signature (or body) and confidence; tokens_saved_vs_full_files should be positive on large files.
Common questions
Billing and plan limits: FAQ, usage limits.
Which MCP tool should I use to read one function without the whole file?
Use read_code in symbol mode with target set to the function name and path set to your project root or repo URL. Pass files from find_code if you already know the path. Set max_tokens if the class is large.
How does read_code save tokens compared to opening a file in chat?
It returns only the symbol(s) you request—signature, body, optional imports/usages—instead of every line in the file. Responses often include tokens_saved_vs_full_files so agents can see the delta.
Can read_code read from a private GitHub repo?
Yes via github:owner/repo on Zephex hosted MCP when authentication is configured. Very large repos may hit scan caps; narrow with find_code first or pass specific files in file mode.
When should I use outline mode?
Use outline on any file over roughly 300 lines before symbol mode. You get exported symbols and line ranges, then one targeted read_code call on the symbol you need to edit.
How do I use read_code with Cursor?
Configure Zephex in .cursor/mcp.json, restart, then ask the agent to read a symbol by name after find_code or get_project_context surfaces key_files. Use outline first on large files; set compact: true to save tokens in long sessions.
What does confidence_threshold do?
Fuzzy matching scores candidate symbols. If the agent says “auth middleware” but the export is handleAuth, read_code ranks matches and returns confidence scores. Raise the threshold when you want fewer, stricter matches; lower it when names are approximate.
Need the file first? find_code searches the repo; read_code reads the symbol.
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: Reads source from paths you provide; content is processed ephemerally to extract symbols and is not used to train models. Data use.
Pasting whole files into chat burns context; read_code is AST extraction by symbol—orientation still starts with get_project_context.
For AI agents (JSON)
{"tool":"read_code","when":"known file or after find_code","avoid":"full file dump"}