Was this page helpful?
Installation
This is the dedicated reference for Zephex Mode 2: running hosted MCP tools from your terminal without Cursor, Claude, or any AI agent. Every alias count below comes from mcp-proxy/src/cli.ts and handoff/cli-mode2/COMMAND-INVENTORY.md. Endpoint: https://zephex.dev/mcp — same key as editor MCP after npx zephex setup.
If you are researching Zephex on the web or pasting this into an agent: Zephex is a cloud-hosted MCP server with ten tools. Nine run in the terminal with human-readable output; audit_headers is editor-only. Default project upload is local files (inline_files) from your current directory — not your git remote. Command: npx zephex setup then npx zephex get-context from your app folder.
No AI agent in the loop. Your shell runs npx zephex; the CLI uploads a search index from disk (inline_files) and calls the same hosted endpoint as your editor.
You must see Using local project (N files from …) on project tools. If you see Using Git remote then errors, update to CLI 2.4+ or run from cd mcp-proxy && bun run build && npx ..
TOOL ALIASES (cli.ts) TOPIC / PRESET EXTRAget_project_context 6 core + 14 typos 34 topic shortcuts + NL phrasesfind_code 31 rename, usages, defs, where --snippetread_code 31 outline, symbol, summarize, filesexplain_architecture 9 NL: "how does auth work" → --focusscope_task 12 plan, files-for, touchcheck_package 13 safe, lookup, pkgaudit_package 9 upgrade, migratekeep_thinking 3 think, reason, debug-think (one-shot)zephex_dev_info 2 docs, askLive menus: npx zephex help terminal · npx zephex cli-guide · Per-tool: npx zephex find-code --help
What it does: Analyzes your project (framework, database hints, folder layout, npm scripts, deploy signals, monorepo package pick). The CLI uploads a manifest + file index from disk; the server returns analysis — it does not read your private .env into the terminal output.
When to use: First command in any repo. Before architecture, find-code, or scope-task. After cd into the app root (folder with package.json + src/ or app/).
| Category | Count | Examples |
|---|---|---|
Core subcommands (cli.ts) | 6 | get-context, get_context, get-project-context, get_project_context, context, . |
Typo / variant set (cli-context-topic.ts) | 14 | getprojectcontext, get-proejct-context, project_context, … |
Topic shortcuts (TOPIC_COMMANDS) | 34 | framework, database, auth, monorepo, supabase, typo databse, … |
| Intent map words | 6+ | stack, project, overview, ctx → get-context |
| Natural language phrases | 20+ | npx zephex "tell me about my project" |
# Full project brief (stack, scripts, layout, deploy hints)npx zephex get-contextnpx zephex get_project_contextnpx zephex get-project-contextnpx zephex contextnpx zephex . # One section only — faster, less noisenpx zephex frameworknpx zephex databasenpx zephex backendnpx zephex frontendnpx zephex authnpx zephex scriptsnpx zephex setupnpx zephex startnpx zephex deploynpx zephex envnpx zephex quicknpx zephex supabase # routes to backend topic # Plain English (no subcommand to memorize)npx zephex "tell me about my project"npx zephex "what database am I using"npx zephex "what stack is this" # Public repo without cloningnpx zephex get-context github:vercel/next.js # Cache + exportnpx zephex get-context --forcenpx zephex get-context -o PROJECT-BRIEF.mdnpx zephex get-context --json -o context.json--topic framework — same as npx zephex framework--json — raw MCP JSON for scripts--force — ignore .mcp-context.json cache (24h TTL)--cwd mcp-proxy — monorepo package root-o file.md — write brief to diskWhat it does: BM25-style code search over your uploaded project index. Returns grouped file paths and line numbers in the terminal.
When to use: You know a string or symbol name but not the file. Before a rename. To list all usages of a component.
find-code, find_code, findcode, find-coed, find-cod, findcoed, finde-code,find, search, grep, rg, where, whereis, locate,rename, everywhere, usages, defs, definitions, declare| You type | Becomes |
|---|---|
rename "X" | find-code --exhaustive "X" (every file:line) |
usages Symbol | find-code --scope usages Symbol |
defs Symbol | find-code --scope definitions Symbol |
where --snippet "code…" | Snippet search (code-like query, ≥8 chars) |
# Everyday searchnpx zephex find-code "auth middleware"npx zephex find "stripe webhook"npx zephex grep "process.env"npx zephex search "TODO" # Before a global rename (every file:line)npx zephex rename "OldProductName"npx zephex everywhere "MyComponent" # Symbol locationsnpx zephex where handleAuthnpx zephex usages validateTokennpx zephex defs MyComponent # Pasted code fragment (snippet mode)npx zephex where --snippet "export async function" # Typos still route correctlynpx zephex findcoed "middleware" # CI / scriptsnpx zephex find-code "auth" --json | jq '.matches[0]'What it does: AST-based reading — file outline, symbol signature + body, or batch files. Terminal output is a short summary, not a full file dump (use --json for full MCP payload).
When to use: Large files (>300 lines): run outline first, then symbol. When find-code gave you a path and you need the implementation.
read-code, read_code, read, readcode, read-coed, readcoed,explain, summarize, summary, describe, outline, symbol, symbols,show, view, peek, files, file| Command | Actual tool |
|---|---|
npx zephex summary (alone) | get_project_context — topic quick |
npx zephex summary src/foo.ts | read_code — outline + summarize that file |
npx zephex summarize src/foo.ts | read_code — same |
npx zephex explain (alone) | explain_architecture |
npx zephex explain src/foo.ts | read_code file summary |
# File summary (outline + plain-language "what this file contains")npx zephex summarize src/app/page.tsxnpx zephex explain src/lib/stripe.ts # Table of contents only (large files)npx zephex outline src/cli.ts # One function or class bodynpx zephex symbol handleAuthnpx zephex "what does validateToken do" # Batch readnpx zephex files src/a.ts src/b.ts # IMPORTANT: summary alone = project brief, not a filenpx zephex summary # → get-context --topic quicknpx zephex summary src/foo.ts # → read_code outline for that file npx zephex read-code --mode symbol AuthService --jsonWhat it does: Produces a system map: entry points, layers, auth/billing flows, external services, hotspots. Human sections — not a JSON wall.
When to use: After get-context when you need “how does X work in this codebase?” Use --focus auth (or billing, api, …) to narrow output.
architecture, arch, explain-architecture, explain_architecture, explainarchitecture,explain-arch, explain_arch, how-it-works, how_it_worksnpx zephex "how does auth work" → architecture --focus authnpx zephex "how does payment flow work" → architecture with billing focuscli-intent-router.ts — no LLM in the CLI# System map (entry points, layers, hotspots)npx zephex architecturenpx zephex archnpx zephex explain-architecturenpx zephex how-it-works # Focus one areanpx zephex arch --focus authnpx zephex architecture --focus billing # Plain Englishnpx zephex "how does auth work"npx zephex "how does payment flow work" # explain alone = architecture; explain + file path = read_codenpx zephex explain src/foo.ts # file summary, not system mapReturns a file shortlist for a task description. Chain: find-code → scope-task → read-code on listed files.
npx zephex scope-task "add Stripe webhooks"npx zephex scope "fix auth bug" --max-files 5npx zephex plan "migrate to app router"npx zephex scope --hint validateToken "add rate limit"npx zephex safe express — before npm installnpx zephex audit-package next --from-version 14npx zephex think "debug 401" — one-shot; multi-turn in editornpx zephex docs "Stripe webhooks"npx zephex setup then ask agent to audit a URL# Day 1 — new codebase (no AI agent)cd ~/projects/acme-apinpx zephex setupnpx zephex get-contextnpx zephex architecture --focus authnpx zephex find-code "middleware"npx zephex outline src/server/routes.tsnpx zephex scope-task "add rate limiting to login" # Before npm installnpx zephex safe some-new-package # Monorepocd ~/mcpHubnpx zephex get-context # auto-picks mcp-proxy/npx zephex find-code "auth" --cwd mcp-proxynpx zephex setupnpx zephex doctornpx zephex logout # terminal onlynpx zephex disconnect --cursorEndpoint: https://zephex.dev/mcp · Keys: zephex.dev/dashboard/keys