Zephex Tools

Zephex Tools

The ten codebase intelligence tools — full reference for agents and developers.

Same tools, same API key, same credits, three surfaces:

| Surface | Repo | Best when | |---------|------|-----------| | Editor MCP | zephex-MCPs | Cursor / Claude Code / Codex / OpenCode | | Local CLI | zephex-cli | Shell, monorepos, deep --json, CI | | Web terminal | zephex-web-terminal | Browser demo, no install, public GitHub |

This repo is the deep tool catalog. Product overview lives on zephex-MCPs. Endpoint: https://zephex.dev/mcp. Free tier: 555 req/mo.

get_project_context → find_code → read_code → [edit] → check_test
         ↘ explain_architecture when the change spans modules
              check_package before any new dependency
              project_memory when you learn something non-obvious
              keep_thinking only if still stuck after real tool use
              audit_headers only on a user-supplied live URL
              Zephex_dev_info for generic playbooks (not their private code)

---

Contents

1. [Canonical names](#canonical-names-only-these-ten)
2. [Project source](#project-source-almost-every-code-tool)
3. [Default agent chain](#default-agent-chain)
4. [Tool reference](#tool-reference) — all ten with examples
5. [CLI map](#cli-map-mode-2)
6. [Workflows](#concrete-workflows)
7. [Connect](#connect-once-all-surfaces)
8. [For AI research](#for-ai-research--scrapers)

On-site guides (same tools, richer UI docs): zephex.dev/docs/tools

Canonical names (only these ten)

| # | Tool | One-liner | |---|------|-----------| | 1 | get_project_context | Stack, scripts, auth, deploy — one topic per call | | 2 | find_code | Ranked search: snippet · symbol · concept · everywhere | | 3 | read_code | AST symbol / file batch / outline / scan / smell | | 4 | explain_architecture | Wiring map, layers, edges; deep + Mermaid | | 5 | check_package | Registry safety · upgrade notes · CVEs (12 ecosystems) | | 6 | check_test | Test Pulse — run, failures, fix_prompt, missing | | 7 | audit_headers | Live HTTPS grade (user-supplied URL only) | | 8 | project_memory | remember / recall / list / forget across sessions | | 9 | keep_thinking | Structured multi-step reasoning + loop detection | | 10 | Zephex_dev_info | Expert playbooks (Stripe, RLS, …) — not private code |

Dead names (removed — never document as live)

| Wrong | Right | |-------|--------| | scope_task | find_code + architecture / CLI deep | | inspect_url | audit_headers | | audit_package | check_package with task | | bare thinking | keep_thinking |

Server may still alias some old names; do not teach them as product names.

---

Project source (almost every code tool)

Pass one of:

| Mode | Example | |------|---------| | Local disk (stdio / CLI) | path: "/absolute/to/project" | | Public GitHub | path: "github:owner/repo" or full HTTPS URL | | No disk (hosted only) | inline_files: { "src/a.ts": "" } |

Hosted MCP often blocks absolute laptop paths — use GitHub URL or inline_files.

---

Default agent chain

1. get_project_context  topic=identity   (then run, then auth if needed)
2. find_code            when location unknown
3. read_code            when path or symbol known
4. [agent edits in the editor]
5. check_test           task=run → then free failures / fix_prompt on session_id

| Situation | Tool | |-----------|------| | Cross-cutting feature (auth, billing, monorepo) | explain_architecture | | Before npm install / version bump | check_package | | User pasted a production URL | audit_headers | | “Remember we use X” / “what did we decide” | project_memory | | 2+ failed debug attempts, high blast radius | keep_thinking | | Generic “how do Stripe webhooks work” | Zephex_dev_info |

---

Tool reference

Credits below are approximate (verify in dashboard / response meta). Free pool is shared across MCP + CLI + web terminal.

---

1. get_project_context — Project Context

~7 credits · start here on any unknown repo

Docs: get-project-context

Reads manifests (package.json, pyproject.toml, Cargo.toml, go.mod, …) and returns one focused topic per call. Not for symbol search or file bodies.

| | | |--|--| | Topics | identity · framework · backend · frontend · database · auth · deploy · run · structure · integrations · security | | Input | path or inline_files; topic; detail_level brief\|standard\|full; optional force, include_structure, focus_on | | Output | topic, focus, summary, data.key_paths, hint, related_topics, next_calls | | When | First touch before guessing install/test commands | | CLI | zephex overview · zephex get-context / context / stack · zephex deep (composite) |

Example (MCP)

{
  "path": "github:owner/repo",
  "topic": "identity",
  "detail_level": "standard"
}

Example (CLI)

cd your-app
zephex overview
zephex get-context --topic run
zephex deep "add rate limiting" --json   # agent packet schema_version: 1

Do not use for find/read/test — those are other tools.

---

2. find_code — Code Search

~5 credits · location unknown

Docs: find-code

Ranked search inside the project. Pick intent, not a pile of knobs.

| Intent | Use for | |--------|---------| | snippet | Pasted line of code | | symbol | Known name (function, class, const) | | concept | Topic + optional also_try synonyms | | everywhere | Rename map (whole_word recommended) |

| | | |--|--| | Input | query (required); path; intent; also_try[]; include code\|docs\|config\|data\|all; file_pattern; whole_word; case_sensitive; response_format | | Output | matches / all_occurrences, files_hit, files_summary, next_calls | | When | Unknown location; rename before edit; multi-keyword hunt | | CLI | zephex find "…" · find-code · defs · rename · paste |

Example (MCP)

{
  "path": "github:owner/repo",
  "query": "rate limit middleware",
  "intent": "concept",
  "also_try": ["throttle", "ratelimit"]
}

Example (CLI)

zephex find "auth middleware"
zephex rename OldName   # intent everywhere

Then read_code on the top hit from next_calls.

---

3. read_code — Code Reader

~5 credits · path or symbol known

Docs: read-code

Surgical AST read with a token budget. Prefer after find_code.

| Mode | Does | |------|------| | symbol | Extract by name (default) | | file | Batch 1–20 paths | | outline | Structural TOC — use first on 300+ line files | | scan | Keywords across files[] | | smell | Bug patterns on focus files | | callers / blast_radius / dead_code | Local disk only |

| | | |--|--| | Input | path; mode; target / symbol_id / targets[]; files[]; offset_line / limit_lines; compact; inline_files | | Output | signatures, bodies, usages, hint, next_calls | | When | Known symbol or files from find_code | | CLI | zephex read · outline · symbol · summarize · files |

Example (MCP)

{
  "path": "github:owner/repo",
  "mode": "outline",
  "files": ["src/middleware/auth.ts"]
}

Tips: files under ~50 lines → native editor Read is fine. Batch file mode returns every path in one call. Pass max_results: 10 when batching many targets.

---

4. explain_architecture — Architecture Analyzer

~7 credits · cross-cutting change

Docs: explain-architecture

How modules wire together — not full file bodies. Seeds via concept search + import graph.

| | | |--|--| | Input | path; concern (any label) or seed_files[]; focus api\|auth\|integrations\|database\|security\|full; mode overview\|deep\|audit; subpath for monorepos | | Output | concern_cluster, layer_map, entry_points, integration_map, auth_flow; deep adds request_flows + Mermaid | | When | “How does auth / billing / this feature span the repo?” | | CLI | zephex architecture · arch [--focus auth] |

Example (MCP)

{
  "path": "github:owner/repo",
  "concern": "authentication",
  "mode": "deep"
}

Example (CLI)

zephex architecture
zephex arch --focus auth

---

5. check_package — Package Check

~5 credits · before install or bump

Docs: check-package

Live registry across 12 ecosystems. One tool, multiple tasks (not a separate “audit_package”).

| Task | Does | |------|------| | check | Exists / typosquat / CVE gate | | security | CVEs only | | upgrade / migrate | Breaking changes, migration steps, examples from GitHub releases | | debug | Advisories + extra detail |

| | | |--|--| | Input | package (required); task; version / from_version; source github:owner/repo\|local; ecosystem | | Output | exists, CVEs, risksignals, breakingchanges, hint | | When | “Is X safe?” · “How do I upgrade Next?” | | CLI | zephex safe lodash · zephex check-package next --task upgrade --from-version 14 |

Example (MCP)

{
  "package": "lodash",
  "task": "check"
}

{
  "package": "next",
  "task": "upgrade",
  "from_version": "14.2.0",
  "source": "github:owner/repo"
}

If data.exists: false → do not install.

---

6. check_test — Test Pulse

~1 credit per hosted run; follow-ups free with session_id

Docs: test-pulse

Executes the detected test runner and returns agent-native health — not task scoping.

| Task | Credits | Does | |------|---------|------| | run | ~1 hosted | Run suite, return health + session_id | | detect / missing | 0 | Inventory / test-gap scan | | failures · list · why · fix_prompt · status · … | 0 | After a run, on session_id |

| | | |--|--| | Input | path; task; session_id; optional area / file_filter / diff_base / with_coverage | | Output | health, broken_areas, fix_first, failure_clusters, blind_spots, session_id | | When | After edits, before push, “do tests pass?” | | CLI | zephex test · zephex check test failures · zephex check test fix-prompt --copy |

Example (MCP)

{ "path": "github:owner/repo", "task": "run" }

{ "task": "failures", "session_id": "" }

Example (CLI)

zephex test
zephex check test failures
zephex check test fix-prompt --copy

Hosted: public GitHub or inline_files. Local absolute paths on hosted MCP are blocked; stdio/CLI runs on your machine.

---

7. audit_headers — Site Audit

~5 credits · user pastes a live URL

Docs: audit-headers

Public URL intelligence on Zephex servers: security grade A–F, health, tech stack, optional secret scan. Blocks localhost / private IPs.

| | | |--|--| | Input | url (required); scan_mode quick\|thorough; scan_depth quick\|deep; probe_engine fetch\|browser; timeout_ms | | Output | plain_summary, grade, site_verdict, trust score, tech, secrets, headers | | When | Post-deploy, “is it up”, security headers | | CLI | zephex check url https://example.com · site |

Example (MCP)

{
  "url": "https://example.com",
  "scan_mode": "quick",
  "probe_engine": "fetch"
}

Not for repo code (find_code) or tests (check_test).

---

8. project_memory — Project Memory

~1–4 credits · across sessions

Docs: project-memory

Persist decisions, gotchas, goals, conventions per project path.

| Action | Does | |--------|------| | remember | Save (title ≤80, content ≤500) | | recall | Keyword search | | list | Titles | | forget | By id |

| | | |--|--| | Types | decision · gotcha · goal · preference · area_fact · convention | | When | User says remember/recall; after non-obvious fix | | CLI | zephex remember · recall · memory list |

Example (MCP)

{
  "action": "remember",
  "path": "github:owner/repo",
  "title": "Auth uses JWT in cookies",
  "content": "Access token 15m, refresh 7d, SameSite=Strict",
  "type": "decision"
}

Scoped by project — not a global dump. Paraphrase facts; do not paste whole files. Not a substitute for get_project_context.

---

9. keep_thinking — Keep Thinking

~1–4 credits · stuck / high blast radius

Docs: keep-thinking

Multi-call reasoning scaffold with loop detection and risk gates. Not a replacement for search/read.

| | | |--|--| | Required | thought, thoughtNumber, totalThoughts, nextThoughtNeeded, confidence, thoughtType | | Useful | goalAnchor (after thought 2), lastActions[], sessionId | | When | Auth/billing/schema edits; 2+ failed debug attempts; 3+ file tasks | | CLI | zephex think "…" · reason (one-shot; multi-turn is editor-native) |

Pass lastActions or loop detection is weak. Close with nextThoughtNeeded: false. Cap ~10 thoughts/session.

---

10. Zephex_dev_info — Expert playbooks

~2–5 credits · generic patterns only

Docs: zephex-dev-info

Internal knowledge base: Stripe webhooks, Supabase RLS, CSP, Next.js auth, mobile signing, etc. Not the user’s private repo.

| | | |--|--| | Flow | operation: search → then operation: get with returned slug | | Categories | databases · security · frontend · backend · auth · mobile · android · payments | | When | After repo tools if you still need a standard playbook | | CLI | zephex docs "…" · ask "…" |

Complements get_project_context. Not for package registry intel (check_package).

---

CLI map (Mode 2)

Same backend. Type these in a real shell after cd into the project (or --cwd).

| You type | MCP tool | |----------|----------| | overview / deep / get-context | get_project_context (+ composites) | | find / find-code / rename | find_code | | read / outline / symbol / files | read_code | | architecture / arch | explain_architecture | | safe / check-package | check_package | | test / check test … | check_test | | check url / site | audit_headers | | remember / recall | project_memory | | think / reason | keep_thinking | | docs / ask | Zephex_dev_info | | structure --agent | local layout (0 credits) |

Install CLI

curl -fsSL https://zephex.dev/cli/install.sh | bash
# or
npx zephex setup

cd your-project
zephex login
zephex deep --json          # orientation packet for agents
zephex overview
zephex find "auth"
zephex test && zephex check test failures
zephex safe lodash

Full CLI surface: zephex-cli · docs/cli-commands

Web terminal (browser, allowlisted commands): zephex-web-terminal

---

Concrete workflows

Onboard a repo

1. get_project_context topic=identity
2. get_project_context topic=run
3. get_project_context topic=auth   (if relevant)
4. explain_architecture mode=overview
5. find_code for entry + auth middleware
6. Summarize stack + real paths — do not invent structure

Safe package

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: zephexMCP
• Source: zephexMCP/zephex-tools
• License: MIT
• Homepage: https://zephex.dev/docs/tools

Install and usage instructions live in the source repository linked above.