docs · mcp tools

MCP tools reference

11 read-only tools, served over MCP and callable from the CLI. Most take a symbol id — get one from find_symbol, file_overview or list_entrypoints.

find_symbol#

Find functions, methods and module-level values by name. Start here to get a symbol's id for the other tools.

ParameterTypeDescription
queryrequiredstringName to look for; matches anywhere in a function, method or value name, or its type, case-insensitive.
kindstringOnly 'function' or only 'value'; omit for both.
limitintegerMaximum results (default 25, at most 100).

Returns — Matching symbols with id, name, kind, file, line, how the framework invokes it, and how many call sites reach it.

shell
codemarrow call find_symbol '{"query":"login"}'

read_symbol#

Read the source code of one function or value, with line numbers.

ParameterTypeDescription
idrequiredintegerSymbol id from another tool's result.

Returns — The symbol and its declaration, each line prefixed with its line number.

shell
codemarrow call read_symbol '{"id":42}'

read_file#

Read a range of lines from any file in the project, with line numbers.

ParameterTypeDescription
pathrequiredstringFile path relative to the project root.
start_lineintegerFirst line to read (1-based; default 1).
end_lineintegerLast line to read (default: start_line + 199).

Returns — The requested lines with line numbers, and the file’s total line count.

shell
codemarrow call read_file '{"path":"src/auth/login.ts"}'

file_overview#

What a source file defines, every place that uses it (function, file and line), the project code it uses, and the library packages it calls into.

ParameterTypeDescription
pathrequiredstringIndexed source file, relative to the project root.

Returns — Definitions, incoming uses, outgoing uses and package calls for the file.

shell
codemarrow call file_overview '{"path":"src/auth/login.ts"}'

get_callers#

Everything that directly reaches a symbol, each at its call site — including framework wiring such as middleware that intercepts a route or a layout that wraps a page.

ParameterTypeDescription
idrequiredintegerSymbol id from another tool's result.

Returns — Each caller with file, line, the call as written, link kind and confidence.

shell
codemarrow call get_callers '{"id":42}'

get_callees#

Everything a symbol directly reaches: project functions and values it calls or uses, each at its call site, plus the library packages it calls into.

ParameterTypeDescription
idrequiredintegerSymbol id from another tool's result.

Returns — Each callee with its call site, link kind and confidence, plus library package calls.

shell
codemarrow call get_callees '{"id":42}'

trace#

Follow callers or callees several hops at once, returned as nodes and edges. Use get_callers or get_callees for one hop with call sites.

ParameterTypeDescription
idrequiredintegerSymbol id to start from.
directionrequiredstring'callers' walks what reaches it; 'callees' walks what it reaches.
depthintegerHops to follow (default 2 unless configured otherwise, at most 4).

Returns — The root symbol, every symbol reached, and edges from the reaching symbol to the reached one.

shell
codemarrow call trace '{"id":42,"direction":"callers"}'

impact#

What a change to a symbol could affect: callers transitively, plus everything it intercepts, wraps or catches errors for. Nearest first.

ParameterTypeDescription
idrequiredintegerSymbol id of what would change.
depthintegerHops to follow (default 3, at most 6).

Returns — Affected symbols with their distance in hops, nearest first, and the number of files touched.

shell
codemarrow call impact '{"id":42}'

list_entrypoints#

Functions the framework invokes itself — HTTP routes, pages, middleware — i.e. where requests enter the code.

ParameterTypeDescription
filterstringOnly entry points whose route or name contains this, e.g. '/api' or 'POST'.
limitintegerMaximum results (default 50, at most 200).

Returns — Entry points, each with how the framework invokes it: a route, page or middleware.

shell
codemarrow call list_entrypoints

package_usage#

Where the project calls into third-party packages: a summary of all packages, or every call site into one package.

ParameterTypeDescription
packagestringPackage to list call sites for, e.g. 'winston' or 'next'; omit for a summary of every package used.
limitintegerMaximum call sites (default 50, at most 200).

Returns — A per-package summary, or every call site into the given package.

shell
codemarrow call package_usage

search_text#

Search the text of indexed source files, for anything the graph doesn't link — a value passed as an argument, a config key, a string.

ParameterTypeDescription
patternrequiredstringText to find; a Go regular expression when regex is true.
regexbooleanTreat pattern as a regular expression.
pathstringOnly search files under this project-relative directory or file.
limitintegerMaximum matching lines (default 50, at most 200).

Returns — Matching lines with file and line number.

shell
codemarrow call search_text '{"pattern":"SESSION_TTL"}'