get_project_context
Your agent learns the repo in one shot—stack, scripts, and where to start.
Zephex is a hosted Model Context Protocol (MCP) server that gives AI coding agents a verified project snapshot through get_project_context and nine other built-in tools with one API key—without running separate local MCP servers on every machine.
When to use
- First message when you open an unfamiliar repository in Cursor, Claude Code, or VS Code with MCP.
- Before changing auth, billing, deployment, database, or API routing—you need grounded paths.
- When the agent keeps opening wrong files or running the wrong npm script.
- After cloning a GitHub repo (pass github:owner/repo or your absolute local path).
When not to use
- You need the body of a specific function—use read_code after this.
- You need to search for a string across the repo—use find_code.
- You need package CVE or upgrade migration detail—use check_package (task=upgrade or task=security).
- You already have full context from a prior get_project_context call and package.json has not changed.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| path | string | No* | Absolute project root or https://github.com/owner/repo. |
| inline_files | object | No | Map of filename → full file text when hosted cannot read disk. |
| topic | string | No | identity | framework | backend | frontend | database | auth | deploy | run | structure | integrations | security |
| force | boolean | No | Bypass .mcp-context.json cache. |
| detail_level | enum | No | Legacy: brief (default) | standard | full |
| include_structure | boolean | No | Add bounded file tree (structure topic). |
| structure_depth | number | No | 1–6 when include_structure is true. |
| focus_on | string | No | Subdirectory for file-tree scan (e.g. src/tools). |
Limits: Custom build systems may be missed. Large monorepos are best-effort at the chosen root. Writes .mcp-context.json and may update .gitignore. Rate limit applies on hosted calls.
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
- A Zephex API key from zephex.dev/install and hosted MCP configured in your editor.
- An absolute path to the project root (or github:owner/repo for remote scan).
- A real project root with package.json, pyproject.toml, Cargo.toml, go.mod, or similar—not an empty folder.
- Optional: set force: true after dependency changes to bypass .mcp-context.json cache.
Token and request cost
Most get_project_context responses land around 400–700 tokens. Manually pasting package.json, README, env examples, route files, and random folders into chat often costs 15,000–40,000 tokens—this tool is usually 1–5% of that cost for orientation. Each call counts as one request on your plan (Free: 555 requests/month).
Example
MCP tools/call
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "get_project_context", "arguments": { "path": "/path/to/project", "topic": "identity" } }}Response shape
Response shape
{ "topic": "identity", "focus": "What this project is — name, type, scale, and which topics apply next", "summary": "TypeScript Next.js SaaS application — Stripe billing", "hint": "Call this first on any new repo or GitHub URL before editing code.", "data": { "identity": { "tagline": "…", "project_type": "saas", "available_topics": ["framework", "backend", "auth"] } }, "related_topics": ["framework", "structure", "run"], "next_calls": ["get_project_context({ topic: \"framework\" })"], "meta": { "cache_hit": true, "project_root": "/path/to/project", "tokens_this_response": 274 }}Which Zephex tool when
| Task | Use this tool | Not this tool |
|---|---|---|
| Orient on a new repo | get_project_context | read_code (no file yet) |
| Find where a string lives | find_code | get_project_context |
| Read one function body | read_code | get_project_context |
| Verify a new package name | check_package | get_project_context |
What it can do in your codebase
- Detect Next.js, React, Vue, Svelte, Django, FastAPI, Flask, Go, Rust, Java, Kotlin, .NET, Ruby, PHP, Flutter, and more from real manifest files
- Return test_command, build_command, dev_command, lint_command, type_check_command when scripts exist
- List entry_points, api_routes, key_files, config_files, path_aliases so edits land correctly
- Surface env_required names (not secret values) so agents stop inventing variable names
- Report database, auth, and hosting hints from dependencies and config
- Map integrations: payments, email, monitoring, queues, LLM providers, analytics, CMS
- Describe monorepo workspaces and which package is the primary app
- Optional include_structure file tree (depth 1–6) without reading every source file
- Cache in .mcp-context.json for fast repeat calls until package.json changes
- Support inline_files when the MCP host cannot read disk (paste package.json + tsconfig)
- Work on absolute local paths or GitHub / GitLab / Bitbucket URLs
- Flag dependency health and outdated major versions on standard/full detail levels
Common response fields
Why teams use it
Built for agent orientation
Designed as step zero in Zephex’s ten-tool set—the same tools on every editor once you add one hosted MCP config.
Manifest-first, not grep-the-world
Reads package.json, pyproject.toml, Cargo.toml, go.mod, pubspec.yaml, Gradle, csproj, Gemfile, composer.json, and framework configs.
11 topic slices
topic identity first, then backend, frontend, auth, etc. Each returns different focus, summary, and key_paths. Legacy detail_level brief/standard/full still works.
Honest scope
Does not replace code search or symbol reading—chains cleanly into find_code and read_code.
What it looks at vs skips
- Package and build manifests across ecosystems
- Framework config files (Next, Vite, Django, etc.)
- npm/pnpm/yarn/bun scripts and task runners
- Route and entry-point heuristics
- Referenced environment variable names
- Bounded directory tree when include_structure is true
- node_modules, dist, and build artifact trees
- .env, keys, SSH paths (hard-blocked for safety)
- Line-by-line source semantics
- Full-repo text search
- Per-package CVE migration briefs
Manifests it reads
Detection is manifest-first—the tool scans these (and related framework configs), not every source file line by line.
package.jsonpyproject.tomlCargo.tomlgo.modpubspec.yamlGemfilecomposer.jsonbuild.gradle / pom.xmlPackage.swiftcsprojDockerfileframework configs (next.config, vite.config, django settings, …)
Topics (recommended)
How it fits your workflow
- get_project_context topic identity — then backend or frontend as needed
- find_code — locate symbol, env var, or error string
- read_code — implementation, outline, or callers
- check_package / project_memory — when touching dependencies
Troubleshooting
- Empty or generic brief → path is not the repo root; pass the folder that contains package.json or .git.
- Stale stack after npm install → set force: true or delete .mcp-context.json and call again.
- 429 rate limit → get_project_context is capped per tier (default ~300/day on free); wait for Retry-After or upgrade.
- Remote github: repo fails → confirm GitHub access for private repos; first clone can take 15–45 seconds.
How to verify it works
- Connect Zephex hosted MCP in your editor (see Quickstart) and confirm tools/list includes get_project_context.
- Ask: “Call get_project_context on this workspace—what is the test_command and one key_files entry?”
- Confirm the JSON includes stack, test_command (or scripts), and key_files—if cache_hit is true, a second call should return faster until package.json changes.
Common questions
Billing and plan limits: FAQ, usage limits.
Which MCP tool should I use first on a new codebase?
Use get_project_context first. It tells the agent your framework, how to run tests, and which files matter. Then use find_code to search and read_code for implementations. Zephex documents this flow on every tool page and in the quickstart.
How do I connect get_project_context to Cursor or Claude Code?
Add Zephex as a hosted MCP server in your editor config with one API key from zephex.dev/install. The agent calls get_project_context with your workspace path (or you omit path when the editor already provides the project root). See the Cursor and Claude Code setup guides under Documentation → Editors.
Does get_project_context read my entire repository?
No. It reads manifests, config, and optionally a bounded folder map—not every source line. For code bodies use read_code; for search use find_code. Paths are processed ephemerally to build the brief.
What is .mcp-context.json and when should I use force?
Zephex writes .mcp-context.json in your project root to cache scan results and may add it to .gitignore. If package.json changes or detection looks wrong, call get_project_context with force: true to bypass the cache. Do not commit the cache file.
When should I use detail_level brief vs full or include_structure?
Use brief (default) for everyday agent sessions. Use standard or full before large refactors or when you need dependency health and richer integration hints. Set include_structure true with structure_depth 2–4 when the agent needs a folder map without reading every source file.
Next step: find_code to search; read_code for implementations.
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 project manifests and config paths you provide; results are returned to the agent without storing your source code in a training dataset. Data use.
Reading README and package.json manually gives prose; get_project_context returns a structured brief agents can route from—library API docs are a different job (see Zephex vs Context7.
For AI agents (JSON)
{"tool":"get_project_context","topic":"identity","first_on_new_repo":true,"then_topics":["framework","backend"],"then_tools":["find_code","read_code"]}