| name | navigation-mcp |
| description | MCP navigation, code discovery, symbol lookup, trace_flow, trace_callers, endpoints. Use navigation-agent MCP before reading workspace code. |
| license | Apache-2.0 |
| compatibility | opencode |
| metadata | {"author":"j0k3r-dev-rgl","version":"1.7.0"} |
Activation Contract
Use this skill for workspace-only code discovery: locating files, symbols, routes, endpoints, text matches, caller impact, or downstream flow before editing.
Do not use it for web search, external repositories, parent directories, arbitrary filesystem access, or reading full file contents.
Hard Rules
- If discovery is needed, use navigation first; do not open multiple files cold.
- If the exact file is already known and no discovery is needed,
read is allowed.
- Canonical tools are
code.inspect_tree, code.find_symbol, code.list_endpoints, code.search_text, code.trace_flow, and code.trace_callers.
- Clients may expose aliases such as
navigation-agent_code_find_symbol; use the available alias but preserve canonical code.* semantics.
- Supported language filters:
typescript, javascript, go, java, php, python, rust, csharp.
- Supported framework filters:
react-router, spring.
- Use
snake_case parameters: max_depth, include_hidden, file_pattern, recursive.
- Treat navigation output as a scope reducer, not file content. Read only returned files that matter.
- Use
glob, bash grep, or bash find only when navigation is unavailable, unsupported, or returned no useful result after narrowing.
- Do not use text search when a symbol trace would answer better.
- Do not call
trace_flow to find callers or trace_callers to follow behavior.
- Do not treat a zero-result navigation response as proof without a scoped fallback.
Decision Gates
| Need | Use first | Then |
|---|
| Understand an unknown module | code.inspect_tree | Read selected paths only |
| Find a class/function/method/type | code.find_symbol | Trace or read returned path |
| Audit REST/GraphQL/routes | code.list_endpoints | Trace or read entrypoints |
| Find imports/decorators/text | code.search_text | Prioritize topFiles, then read |
| Know what a symbol calls | code.find_symbol | code.trace_flow with items[].path |
| Know who calls a symbol | code.find_symbol | code.trace_callers with recursive: true for shared APIs |
Execution Steps
- Identify the narrowest known scope:
path, language, and framework when available.
- Start with the most specific navigation tool from the decision table.
- Chain tool outputs: pass
find_symbol.items[].path as path to trace_flow or trace_callers.
- Remember direction:
trace_flow is downstream behavior; trace_callers is upstream impact.
- If
find_symbol misses constants, config keys, decorators, imports, or generated names, use code.search_text scoped by path, include, and language.
- If trace output is too broad, narrow
path, language, framework, or symbol; for trace_callers, lower max_depth.
- If endpoint discovery returns zero, retry with narrower
path and the most specific framework or kind before concluding there is no public surface.
- If results are empty or
truncated: true, narrow before reading files or increasing limit.
- Read only the small set of files needed to answer or edit safely.
Output Contract
Return:
- Navigation path used and why.
- Important resolved files, symbols, endpoints, or callers.
- Any fallback used after navigation failed or was unsupported.
- Limitations such as unsupported framework detection, truncation, or zero endpoint results.
- Files that still need direct
read before editing.
References
README.md — public contract, compatibility matrix, and agent usage guide.
