KiroGraph Core, Navigation, and Utility MCP Tools Guide

KiroGraph’s core tools are registered unconditionally — they appear in every tools/list response regardless of which feature flags are enabled. The always-on core set covers the most frequent agent workflows: building task context, searching for symbols, and inspecting symbol details. Navigation tools (kirograph_status, kirograph_files, kirograph_impact) require enableNavigation: true. Call-graph traversal tools (kirograph_callers, kirograph_callees) require trackCallSites: true. Agent utility tools (kirograph_read, kirograph_retrieve, kirograph_gain, kirograph_budget) require enableAgentUtils: true.

Core Tools (always-on)

The three always-on tools — kirograph_context, kirograph_search, and kirograph_node — are registered unconditionally and appear in every tools/list response.

`kirograph_context`

The primary entry point for every agent task. Given a natural-language task description, it extracts symbol tokens, runs exact lookup + full-text search + vector search against the active semantic engine, resolves imports to their definitions, expands the graph to related symbols, and returns entry points, related nodes, edges, and code snippets — all in a single call. This is the only tool that invokes the vector engine on every call. For most tasks, one call to kirograph_context is enough to orient the agent without any further tool calls.

task

string

required

Natural-language description of the task, bug, or feature to investigate. Supports CamelCase, snake_case, SCREAMING_SNAKE, and dot.notation symbol tokens.

maxNodes

number

default:"20"

Maximum number of symbols to include in the response.

detail

string

default:"full"

Code verbosity level. Options: full (complete source code), signatures (signature + docstring, ~70% fewer tokens than full), summary (file locations only, no code).

projectPath

string

default:"cwd"

Absolute path to the project root. Defaults to the server’s current working directory.

How it works:

Token extraction

Parses the task string for CamelCase, snake_case, SCREAMING_SNAKE, and dot.notation tokens.

Exact + FTS + vector search

Runs exact name lookup → SQLite FTS → vector search against the active semantic engine.

Import resolution

Resolves imported symbols to their definitions in the graph.

Graph expansion

BFS-expands through related edges (calls, imports, references, type_of) up to maxNodes.

Response assembly

Returns entry points, related nodes, edges, code snippets, related memory (if enableMemory), related docs (if enableDocs), and security warnings (if enableSecurity).

{
  "tool": "kirograph_context",
  "arguments": {
    "task": "Add rate limiting to the authentication endpoints",
    "detail": "signatures",
    "maxNodes": 15
  }
}

`kirograph_search`

Quick symbol search by name. Returns file locations and qualified names only — no source code. Ideal for confirming a symbol exists or discovering all symbols that match a partial name before drilling in with kirograph_node.

query

string

required

Symbol name or partial name (e.g. "auth", "signIn", "UserService").

mode

string

default:"name"

Search mode. name (default) uses FTS prefix match; similar uses fuzzy substring match for broader results.

kind

string

Filter by node kind. Options: function, method, class, interface, type_alias, variable, route, component.

limit

number

default:"10"

Maximum results to return (1–100).

projectPath

string

default:"cwd"

Project root path.

How it works: Exact name match → SQLite FTS → LIKE fallback → vector search only if all three return nothing. Pure graph database in the common case; vector engine only as a last resort.

{
  "tool": "kirograph_search",
  "arguments": {
    "query": "authenticate",
    "kind": "function",
    "limit": 5
  }
}

`kirograph_node`

Get details about a specific symbol, with configurable depth — from a quick location summary up to the full source code.

symbol

string

required

Symbol name or fully-qualified name to look up.

qualified

boolean

default:"false"

When true, treats symbol as a fully-qualified name and performs an exact match, bypassing FTS. Use when you have the qualifiedName from a prior result.

detail

string

default:"summary"

Output verbosity. Options: summary (name + location + qualified name), signatures (adds signature and docstring), full (adds complete source code).

projectPath

string

default:"cwd"

Project root path.

Call-Graph Traversal Tools (require `trackCallSites: true`)

`kirograph_callers`

Find all functions and methods that call a specific symbol. Uses BFS traversal of incoming call edges in the graph database — no vector engine involved.

symbol

string

required

Symbol name to find callers for.

limit

number

default:"20"

Maximum results to return (1–100).

projectPath

string

default:"cwd"

Project root path.

Requires trackCallSites: true in your config. Call-site edges are only written to the graph during indexing when this flag is enabled.

`kirograph_callees`

Find all functions and methods that a specific symbol calls. Uses BFS traversal of outgoing call edges — no vector engine involved.

symbol

string

required

Symbol name to find callees for.

limit

number

default:"20"

Maximum results to return (1–100).

projectPath

string

default:"cwd"

Project root path.

{
  "tool": "kirograph_callees",
  "arguments": {
    "symbol": "UserService.create",
    "limit": 10
  }
}

`kirograph_impact`

Analyze what code would be affected by changing a symbol. BFS-traverses all incoming edges (call, import, reference, and others) up to the specified depth. Use this before making changes to understand blast radius.

symbol

string

required

Symbol name to analyze impact for.

depth

number

default:"2"

BFS traversal depth. Higher values find more transitive dependents.

projectPath

string

default:"cwd"

Project root path.

{
  "tool": "kirograph_impact",
  "arguments": {
    "symbol": "validateToken",
    "depth": 3
  }
}

`kirograph_status`

Check index health and statistics. Returns files indexed, symbol count, edge count, breakdown by kind and language, detected frameworks, database size, semantic engine status, and (if enabled) docs, data, security, and pattern subsystem summaries.

projectPath

string

default:"cwd"

Project root path.

`kirograph_files`

List the indexed file structure with filtering and multiple output formats. Useful for exploring the project layout and checking which files have been indexed.

filterPath

string

Filter by directory path prefix (e.g. "src/").

pattern

string

Filter by glob pattern (e.g. "**/*.ts").

maxDepth

number

Limit directory tree depth.

format

string

default:"tree"

Output format. Options: tree (visual directory tree), flat (one path per line), grouped (grouped by directory), compact (rtk-style summary with counts).

includeMetadata

boolean

default:"true"

Include language and symbol count annotations alongside each file.

projectPath

string

default:"cwd"

Project root path.

Agent Utility Tools (require `enableAgentUtils: true`)

`kirograph_read`

Read a file with session-level caching. The first read returns full content; subsequent reads of unchanged files return a compact [cached: file unchanged] marker (~13 tokens), saving context on repeated reads. Supports multiple modes for targeted extraction.

path

string

required

File path (absolute or relative to project root).

mode

string

default:"full"

Read mode. Options: full (entire file), map (structure overview), signatures (function signatures only), diff (changes since last read), lines (line range, requires start/end), imports, exports.

start

number

Start line for lines mode.

end

number

End line for lines mode.

noCache

boolean

default:"false"

Force a fresh filesystem read, bypassing the session cache.

projectPath

string

default:"cwd"

Project root path.

`kirograph_retrieve`

Cached Content Retrieval (CCR). Returns the full content stored in the session cache, or reads and caches the file if not yet seen. Use after kirograph_read returns a [cached: file unchanged] marker to recover the actual content without a redundant filesystem read.

path

string

required

File path to retrieve (absolute or relative to project root).

projectPath

string

default:"cwd"

Project root path.

`kirograph_budget`

Show current session context budget usage: tokens consumed, remaining budget, and utilization percentage.

reset

boolean

default:"false"

Reset session budget counters.

projectPath

string

default:"cwd"

Project root path.

`kirograph_gain`

Show token savings statistics accumulated from compressed command outputs and graph tool calls in the current session (or longer periods).

period

string

default:"session"

Time window to aggregate. Options: session (since server start), today, week, all.

projectPath

string

default:"cwd"

Project root path.

Shell Execution Tool (requires `enableShellExec: true`)

`kirograph_exec`

Run a shell command with token-optimized, noise-filtered output. Automatically applies structural filters for git, test runners (Jest, Vitest, pytest), linters (ESLint, Pylint), build tools (webpack, tsc), and Docker — stripping repeated noise lines and compacting progress bars before the output reaches the model.

command

string

required

Shell command to execute.

cwd

string

default:"project root"

Working directory for the command.

level

string

default:"normal"

Compression intensity. Options: normal (balanced), aggressive (more compact), ultra (maximum compression — may drop some detail).

timeout

number

default:"60"

Timeout in seconds before the command is killed.

projectPath

string

default:"cwd"

Project root path used for configuration lookup.

When enableShellExec is false, the tool is not registered. Use kirograph_compress instead for manual compression of command output that arrived from outside KiroGraph.

{
  "tool": "kirograph_exec",
  "arguments": {
    "command": "npm test -- --reporter=verbose",
    "level": "aggressive"
  }
}

General Compression Tool (requires `enableGeneralCompression: true`)

`kirograph_compress`

On-demand compression for arbitrary text before it reaches the model. Routes to one of two engines depending on whether command is provided. Reports inline savings: [42% tokens saved | 1800→1044 | rtk:git:aggressive].

text

string

required

Text to compress.

command

string

Shell command that produced the text (e.g. "git log", "npm test"). When provided, activates rtk-style structural filters. Omit for prose — uses caveman grammar instead.

level

string

default:"full"

Compression intensity. Options: lite / normal (light), full / aggressive (medium), ultra (maximum).

Use kirograph_compress when command output arrived outside of kirograph_exec — for example, from a tool that runs commands directly. For source code, prefer detail: "signatures" on kirograph_context instead, since compressing source code may break identifiers or whitespace-sensitive syntax.

MCP Tools

CLI

KiroGraph Core, Navigation, and Utility MCP Tools Guide

Core Tools (always-on)

`kirograph_context`

`kirograph_search`

`kirograph_node`

Call-Graph Traversal Tools (require `trackCallSites: true`)

`kirograph_callers`

`kirograph_callees`

Navigation Tools (require `enableNavigation: true`)

`kirograph_impact`

`kirograph_status`

`kirograph_files`

Agent Utility Tools (require `enableAgentUtils: true`)

`kirograph_read`

`kirograph_retrieve`

`kirograph_budget`

`kirograph_gain`

Shell Execution Tool (requires `enableShellExec: true`)

`kirograph_exec`

General Compression Tool (requires `enableGeneralCompression: true`)

`kirograph_compress`

Build docs developers (and LLMs) love

MCP Tools

CLI

Documentation Index

​Core Tools (always-on)

​kirograph_context

​kirograph_search

​kirograph_node

​Call-Graph Traversal Tools (require trackCallSites: true)

​kirograph_callers

​kirograph_callees

​Navigation Tools (require enableNavigation: true)

​kirograph_impact

​kirograph_status

​kirograph_files

​Agent Utility Tools (require enableAgentUtils: true)

​kirograph_read

​kirograph_retrieve

​kirograph_budget

​kirograph_gain

​Shell Execution Tool (requires enableShellExec: true)

​kirograph_exec

​General Compression Tool (requires enableGeneralCompression: true)

​kirograph_compress

Build docs developers (and LLMs) love

Core Tools (always-on)

`kirograph_context`

`kirograph_search`

`kirograph_node`

Call-Graph Traversal Tools (require `trackCallSites: true`)

`kirograph_callers`

`kirograph_callees`

Navigation Tools (require `enableNavigation: true`)

`kirograph_impact`

`kirograph_status`

`kirograph_files`

Agent Utility Tools (require `enableAgentUtils: true`)

`kirograph_read`

`kirograph_retrieve`

`kirograph_budget`

`kirograph_gain`

Shell Execution Tool (requires `enableShellExec: true`)

`kirograph_exec`

General Compression Tool (requires `enableGeneralCompression: true`)

`kirograph_compress`