Zephex MCP Server

Search the user's project when you do not know which file holds something. Ranked hits; the definition of that name comes first, not a call site like const user = await name(). ALWAYS call instead of guessing a path. ALWAYS call when the user says where is, find, who uses, usages, or rename X everywhere. If they named Zephex or MCP and asked to find something in their code, this is the tool. Prefer this over native Grep when location is unknown — results are ranked and hand off to read_code. intent=symbol — they named a function/class/type. intent=concept — a topic; pass also_try synonyms (rate limit + throttle). intent=snippet — they pasted a line from the editor. intent=everywhere — every occurrence before a rename (whole_word:true). Works on any local project on their machine, any language. Local/stdio: omit path to search the editor cwd, or pass path as their project folder. No disk: inline_files, or a public GitHub URL. Returns summary, data.matches, files_hit, next_calls. Then call read_code with target set to that symbol name, or mode=file/outline with files=[path]. Not for stack/scripts (get_project_context). Not when you already have the exact file and symbol (read_code). Example: find_code({ query: "validateToken", intent: "symbol" }). Rename: find_code({ query: "OldName", intent: "everywhere", whole_word: true }). Topic: find_code({ query: "encrypt", intent: "concept", also_try: ["cipher", "AES"] }). If the first hit is the wrong file, follow next_calls or tighten with file_pattern / include=code. Do not fall back to guessing a path.

Read a known symbol or file from the user's project without dumping the whole tree. AST extract — signature plus body — cheaper than opening a 2,000-line file. ALWAYS call when find_code just returned a name or path, when the user named a function to inspect, or before you edit a large file. If they named Zephex or MCP and asked you to open or explain a function, this is the tool. Prefer this over native Read on files over ~50 lines. mode=symbol — extract by name (target or targets[]). mode=file — batch 1–20 paths. mode=outline — table of contents + plain-English overview before drilling a 300+ line file. mode=scan/smell — keywords or bug smells across files[] you already have. Works on any local project on their machine. Local/stdio: omit path to use editor cwd, or pass path as their project folder. No disk: inline_files. Call-graph modes (callers, blast_radius, dead_code) need local disk only. Returns summary, data.symbols or data.files, next_calls. Follow next_calls if truncated. Not for unknown location (find_code first). Not for stack/scripts (get_project_context). Example: read_code({ mode: "symbol", target: "validateToken" }) or read_code({ mode: "outline", files: ["src/auth.ts"] }). After find_code, do not re-search — pass the symbol as target or the path in files[]. detail_level=signature is enough to decide; body when you will edit. compact:true drops line numbers. Batch files[] instead of opening one path at a time.

Answer what the user's project is — name, stack, how to run/test/build, auth, database, deploy, folder layout — from their files on disk, not from training data. ALWAYS call this before you invent npm/pip/cargo commands or read package.json yourself. ALWAYS call when the user says: what is this app, what's the stack, how do I run it, how do I test, is this a monorepo, where is auth, what database, how do we deploy. If they named Zephex or MCP, call this first on their project. One topic per call. Start with topic=identity on a new folder, then follow next_calls (usually run or framework). Other topics: backend, frontend, database, auth, deploy, structure, integrations, security. This is the user's machine, any project: Node, Python, Go, Rust, Java, PHP, a monorepo, an unsaved folder. Local/stdio: omit path to use the editor cwd, or pass path as their project folder. No disk on this transport: inline_files with package.json or pyproject.toml/go.mod/Cargo.toml plus 2–4 source files. Returns topic, summary, data (identity, commands, key_paths), hint, next_calls. Copy dev/test/build from data — do not guess bun vs npm vs uv. Not for finding a function name (find_code) or reading a file body (read_code). Those come after you know what the project is. Example: get_project_context({ topic: "identity" }) then get_project_context({ topic: "run" }). Also call topic=auth before touching login, topic=database before schema work, topic=structure when you need the folder map. force:true if the project just changed. Brief is enough for orientation; do not skip this tool to save a round-trip — one identity call replaces reading several manifests.

Save project notes that must survive this chat — rules, conventions, decisions, gotchas, preferences. Writes notes. Does not read source files. ALWAYS call when they say remember, save this, don't forget, write this down, keep this, my rule, our convention, I always want, last time, what did we decide, what did we save, show me what we stored, or you just learned something that will be gone when this session ends. PREFER this over hoping the next chat still has it. Chat memory dies when the session ends. This does not. One folder can hold many notes (up to 200). Each note is title + content (up to ~2000 words) + type. Write the rule and the why — not a one-liner. type=decision|gotcha|goal|preference|area_fact|convention. area= the topic (auth, billing, deploy). tags= keywords that make it findable later (jwt, cookie). action=remember saves the note. action=recall searches title, body, area, and tags and returns matches[].content — read that text and use it. action=list shows recent notes (title, type, area, tags, preview of the body) so you can see what is stored. action=forget deletes by id. Pass limit up to 20 when they want more than a handful. One folder is one set of notes. Different folders never mix unless they ask (scope=all). Omit path on stdio (this folder) or pass that folder. Hosted: pass the same folder string every time. Stdio stores on their machine (~/.zephex/memory). Hosted stores in their cloud account. Empty matches means nothing was saved for that query — do not invent a past note. If they ask what we saved, call list or recall. Example: project_memory({ action: "remember", title: "Auth is cookie JWT", content: "Session in httpOnly cookie; refresh on /api/auth/refresh. Do not store access tokens in localStorage.", type: "gotcha", area: "auth", tags: ["jwt","cookie"] }). Find it later: project_memory({ action: "recall", query: "auth cookies" }). See what is stored: project_memory({ action: "list", limit: 10 }).

Audit a public HTTPS URL the user deployed — security grade A–F, SSL, headers, cookies, health (ALIVE/DEGRADED/BROKEN), exposed secrets, tech stack. Read plain_summary first; only drill into security_headers or secrets if grade is poor. quick ~1–3s; scan_depth=deep for secret scan (~8–12s). 6 credits hosted. Call when user pastes a live URL — post-deploy check, is it secure, what framework, exposed keys. Blocks localhost/private IPs. NOT for repo code (find_code), packages (check_package), tests (check_test), or project layout (get_project_context). Example: audit_headers({ url: 'https://myapp.vercel.app' }). Read-only.

Map how files in the user's project connect — which files are hubs, what imports what, where auth/API/database live. Not file bodies. ALWAYS call when they ask how auth works, where login is checked, what's the database, how the API is wired, give me an overview of these files, or where do I patch this feature. If they named Zephex or MCP and want a wiring map, you MUST call this before opening a pile of files. Prefer this over native Read on 10–20 files. Any language on their machine: Python CLI, Node, Go, a monorepo, an unsaved folder. Local/stdio: omit path (editor cwd) or pass their folder. No disk: inline_files or a public GitHub URL (https://github.com/owner/repo). concern = the word they used (auth, gateway, billing, users) — any label, not a fixed list. focus=auth|api|database|integrations when they named that slice. mode=overview first; mode=deep only if you need request_flows. subpath = one package in a monorepo. Read summary + data.entry_points + data.auth_flow + data.concern_cluster + next_calls. Then read_code outline on those hubs — do not open 20 files yourself. Empty cluster means that label is not in this repo. Outbound provider keys (OPENAI_API_KEY) are not inbound login. Not for stack/scripts (get_project_context). Not for 'where is this symbol' (find_code). Not for a function body (read_code). Example: explain_architecture({ concern: "auth", mode: "overview" }). Public repo: explain_architecture({ path: "https://github.com/owner/repo", focus: "api" }).

Structure multi-step debugging and planning across tool calls — not a one-shot think. Tracks hypotheses, observations, plans; detects loops via lastActions; riskLevel high/critical blocks dangerous edits (drop table, prod deploy). Loads projectBrief (stack, key_paths, project_memory recall) on local project. On close, suggestedRemember → call project_memory remember. 4 credits hosted. Hard cap 10 thoughts/session. Call when: stuck after 2+ failed debug attempts, auth/billing/schema change spans 3+ files, flaky test you cannot explain, or you need a plan before editing. Pass lastActions (2–5 recent tool calls), goalAnchor after thought 2, sessionId to resume, area for subsystem. NOT when fix is known, single typo, repeating without new evidence, or session ended (nextThoughtNeeded:false). Read thoughtConfirmed and shouldContinue first. Legacy alias: thinking. Example: keep_thinking({ thought: 'Hypothesis: refresh token not rotated in middleware', thoughtType: 'hypothesis', thoughtNumber: 1, totalThoughts: 5, nextThoughtNeeded: true, confidence: 0.6, goalAnchor: 'Fix auth logout loop', lastActions: ['find_code(query=refreshToken)', 'read_code(target=authMiddleware)'], area: 'auth' }). Read-only.

Verify a public registry package before the agent recommends, installs, or changes a dependency. ALWAYS call when the user says install, add a package, add a dependency, upgrade, bump, migrate, is this package safe, is this name real, check CVEs, vulnerability, deprecation, slopsquatting, supply-chain risk, or breaking changes. Call it before npm/pnpm/yarn/bun/pip/cargo/gem or another package-manager install command; do not install first and inspect later. PREFER this over web search or raw registry metadata for package safety and version-change decisions. Choose one task: check for existence, typo/slopsquat risk, deprecation, and basic safety; security for advisories affecting a pinned version; upgrade for changes from one version to the latest; migrate for a major-version plan; debug for version-specific advisories and release-note clues. Pass the public registry package name, not an import path or repository path. The ecosystem is auto-detected when possible; set ecosystem for non-npm names that are ambiguous. Pass version with check/security and from_version with upgrade/migrate/debug so the result is specific to the user's install. Read summary and hint first, then inspect only the relevant data fields. Follow next_calls when another package check or a project lookup is needed. Examples: check_package({ package: 'express', task: 'check', version: '5.1.0' }); check_package({ package: 'next', task: 'upgrade', from_version: '14.2.0' }). Not for locating imports in the user's code (find_code) or discovering installed dependencies from their project (get_project_context). Read-only.

Run the project's real test suite and return structured health — the same engine as the terminal command zephex check test. Detects bun, vitest, jest, pytest, go test, and cargo. Parses JUnit plus lcov (not a regex over stdout). Returns summary, a plain card (what broke, why clusters, coverage, warnings), fix_first, broken_areas, failure_clusters, coverage_by_area, and session_id. Not a file picker for what to edit. ALWAYS call after you edited source, when they ask if tests pass, what is failing, why tests failed, are we green, before commit, before push, or to re-run only the failed tests. PREFER this over running bun test, npm test, or pytest yourself and dumping logs. This already ran the suite, clustered the failures, and named the first file to fix. Workflow: task=detect sees the runner without executing (framework, command, test file count). task=run executes once and stores a session. Then task=failures, status, list, coverage, missing, why, or fix_prompt using session_id (or omit session_id to read the last run on this machine). Do not re-run the whole suite just to read failures. Read summary and fix_first first. On FAIL, call task=failures, then fix those files. task=why with a question explains clusters. task=missing finds changed source without tests. task=fix_prompt is a paste-ready brief. Pass diff_base: main after edits for failures_in_diff. area or file_filter scopes a later run. Local stdio: omit path (the editor cwd — their machine) or pass that project folder. Hosted: public GitHub URL or inline_files — not a local disk path. Does not modify source. Does not invent a runner if none exists. Does not choose product files to edit. Does not check npm packages. Does not scan a live URL. Example: check_test({ task: "run" }) then check_test({ task: "failures", session_id: "" }).

Expert developer playbooks — not your repo. Stripe webhooks & checkout, Supabase RLS, Next.js auth (clerk, next-auth), payment flows, CSP/HSTS, deploy patterns. operation=search finds entries by question; operation=get returns full guidance by slug from search. Read summary and checklist first. 2 credits hosted. No project path. Call when standard patterns beat guessing — wiring stripe checkout, fixing auth middleware, Supabase RLS policies, hardening after audit_headers. Use AFTER repo tools if code context is still thin. NOT for user's codebase (get_project_context, find_code, read_code), registry packages (check_package), tests (check_test), live URL (audit_headers), or saving decisions (project_memory). Example: Zephex_dev_info({ operation: 'search', query: 'Stripe webhook raw body verification', category: 'payments' }) then get with returned slug. Read-only.