MCP Tools Reference

Forge exposes 21 tools via the Model Context Protocol (MCP). These tools are available to any MCP-compatible AI client connected to forge serve.

Tier requirements summary:

Tier	Tools available
Community	`forge_search` (keyword only), `forge_search_symbols`, `forge_health_check` — plus 100 calls/day limit
Solo	All 21 tools (keyword + semantic search, workflow tools, all graph/AST tools)
Pro	All Solo tools plus SCIP ingestion, CI mode, cross-repo search
Team	All Pro tools plus shared configs and volume key features

Workflow Tools

These three tools are the recommended entry points for any code modification session. They require Solo tier or higher.

forge_prepare

Pre-modification intelligence report. Runs dependency tracing, health checks, coverage lookup, and git blame internally. Returns a GO / CAUTION / STOP assessment.

Always call this before modifying any file. It surfaces broken imports, stale indexes, and high-risk dependents upfront, avoiding rework.

Parameters:

Name	Type	Required	Description
`file`	string	yes	Path to the file you plan to modify, relative to the repo root.

Output: Structured report containing:

Assessment: GO, CAUTION, or STOP
Dependents list (files that import the target)
Health check findings for the file
Coverage percentage for the file’s symbols
Recent git blame (who last changed each section)
Relevant code chunks from search

Tier: Solo and above.

Example:

{ "file": "src/api/handler.ts" }

forge_validate

Post-modification verification. Triggers an incremental re-index on the modified file(s), re-runs health checks, and identifies dependents at risk. Returns PASSED or FAILED.

Always call this after modifying a file.

Parameters:

Name	Type	Required	Description
`files`	array of strings	yes	Paths to the files that were modified.

Output: Structured report containing:

Verdict: PASSED or FAILED
New health findings introduced by the change
Dependents that may now be broken
Summary of what was re-indexed

Tier: Solo and above.

Example:

{ "files": ["src/api/handler.ts", "src/models/user.ts"] }

forge_understand

Deep dossier on a file or symbol. Returns definition, imports, dependents, coverage, git history, and a risk assessment.

Parameters:

Name	Type	Required	Description
`file`	string	yes	Path to the file.
`symbol`	string	no	Name of a specific symbol within the file. When omitted, returns file-level information.

Output: Comprehensive report including:

Symbol definition with line range
All files imported by this file
All files that depend on this file
Test coverage percentage
Git commit history (most recent 10)
Risk assessment (change impact estimate)

Tier: Solo and above.

Search Tools

forge_search

Full-text keyword search across indexed code chunks. Understands camelCase and snake_case tokenization: searching payment finds processPayment, payment_handler, and PaymentService.

In Community mode: keyword-only search. Solo and above: hybrid semantic + keyword search using vector similarity.

Parameters:

Name	Type	Required	Description
`query`	string	yes	Search query. Supports AND/OR and quoted phrases.
`repo`	string	no	Repository root path. Defaults to the server’s configured repo.
`language`	string	no	Restrict to a language: `typescript`, `rust`, `python`, `go`.
`chunk_type`	string	no	Restrict to a chunk type: `function`, `class`, `interface`, `module_header`.
`limit`	integer	no	Maximum results (default: 10).

Output: Array of matching code chunks, each with:

file: relative file path
symbol: symbol name
chunk_type: type of the chunk
language: detected language
content: source code snippet
score: relevance score

Tier: Community (keyword), Solo and above (semantic).

forge_search_symbols

Search by symbol name across the indexed codebase. Faster and more precise than full-text search when you know the symbol name.

Parameters:

Name	Type	Required	Description
`query`	string	yes	Symbol name or partial name to search for.
`repo`	string	no	Repository root path.
`language`	string	no	Restrict to a language.
`limit`	integer	no	Maximum results (default: 20).

Output: Array of symbol matches, each with:

name: symbol name
kind: function, class, interface, enum, type, variable, constant
file: file path
line: line number

Tier: Community and above.

forge_pattern_search

Structural AST pattern search using ast-grep syntax. Use $VAR for single-node wildcards and $$$VAR for multi-node spreads.

Parameters:

Name	Type	Required	Description
`pattern`	string	yes	Code pattern with `$VAR` and `$$$VAR` wildcards.
`repo`	string	no	Repository root path.
`language`	string	no	Restrict to a language. Required for unambiguous patterns.
`limit`	integer	no	Maximum results (default: 20).

Output: Array of pattern matches, each with:

file: file path
line: line number of the match
match: matched source text
captures: map of wildcard name to matched text

Tier: Solo and above.

Example patterns:

console.log($$$ARGS)
async function $NAME($$$PARAMS) { $$$BODY }
fn $NAME($$$) -> Result<$$$, $$$> { $$$BODY }

AST Tools

forge_parse_file

Parse a source file and return all symbols with line numbers: functions, classes, types, imports, and exports.

Parameters:

Name	Type	Required	Description
`file`	string	yes	Path to the file to parse, relative to the repo root.
`repo`	string	no	Repository root path.

Output: Object containing:

symbols: array of symbol objects (name, kind, line, end_line)
imports: array of import statements (specifier, resolved path)
exports: array of exported symbol names
language: detected language

Tier: Solo and above.

forge_extract_symbol

Extract the full source code of a named symbol from any indexed file.

Parameters:

Name	Type	Required	Description
`file`	string	yes	Path to the file containing the symbol.
`symbol`	string	yes	Name of the symbol to extract.
`repo`	string	no	Repository root path.

Output:

name: symbol name
kind: symbol kind
source: full source code of the symbol
line: start line
end_line: end line

Tier: Solo and above.

Graph Tools

forge_trace_imports

List all modules a file imports, with resolved paths. Configurable traversal depth.

Parameters:

Name	Type	Required	Description
`file`	string	yes	File to trace imports from.
`depth`	integer	no	Traversal depth (default: 1 for direct imports only).
`repo`	string	no	Repository root path.

Output: Array of import edges, each with:

from: importing file
to: imported file (resolved path)
specifier: original import string
resolved: whether the path was resolved to an indexed file

Tier: Solo and above.

forge_trace_dependents

Find all files that import a given file. Use this before modifying a file to understand blast radius.

Parameters:

Name	Type	Required	Description
`file`	string	yes	File to find dependents of.
`repo`	string	no	Repository root path.

Output: Array of dependent files, each with:

file: path to the dependent
import_specifier: how it imports the target

Tier: Solo and above.

forge_check_wiring

Determine if a module is reachable from any registered entry point. Returns the shortest import chain or a DEAD verdict.

Parameters:

Name	Type	Required	Description
`file`	string	yes	File to check reachability for.
`repo`	string	no	Repository root path.

Output:

status: REACHABLE or DEAD
chain: shortest import chain from an entry point (when reachable)
entry_point: the entry point file the chain starts from

Tier: Solo and above.

forge_find_cycles

Find circular dependency chains in the import graph.

Parameters:

Name	Type	Required	Description
`repo`	string	no	Repository root path.
`file`	string	no	When specified, only return cycles involving this file.

Output: Array of cycle chains, each as an ordered array of file paths forming the cycle.

Tier: Solo and above.

forge_dependency_graph

Full dependency graph summary: hub files, leaf files, orphan files, and connectivity statistics.

Parameters:

Name	Type	Required	Description
`repo`	string	no	Repository root path.

Output:

total_files: total indexed files
total_edges: total import edges
hub_files: files with the most dependents (top 10)
leaf_files: files with no dependents
orphan_files: files with no imports and no dependents
average_in_degree: mean number of dependents per file

Tier: Solo and above.

Health Tools

forge_health_check

Run the full suite of health checks and return findings grouped by severity. Built-in checks: broken imports, dead exports, circular dependencies, secret scan.

Parameters:

Name	Type	Required	Description
`repo`	string	no	Repository root path.
`include_secrets`	boolean	no	Include the secret scan check (default: true).

Output:

summary: object with counts per severity (P0 critical, P1 error, P2 warning, P3 info)
findings: array of finding objects, each with:
- severity: P0, P1, P2, or P3
- check_id: the check that produced the finding
- message: human-readable description
- file: affected file (when applicable)
- line: affected line (when applicable)

Tier: Community and above.

forge_architecture_map

Generate a module-level architecture map: file counts per module, language breakdown, entry points, and dependency statistics.

Parameters:

Name	Type	Required	Description
`repo`	string	no	Repository root path.

Output: Markdown-formatted architecture summary covering:

Module hierarchy with file counts
Language distribution
Entry points
Dependency graph statistics
Health indicators (cycles, orphan files)

Tier: Solo and above.

Git Tools

forge_git_history

Commit history for the repo or filtered to a specific file.

Parameters:

Name	Type	Required	Description
`repo`	string	no	Repository root path.
`file`	string	no	Restrict history to commits that touched this file.
`limit`	integer	no	Maximum commits to return (default: 20).

Output: Array of commit objects, each with:

hash: commit SHA
author: author name
email: author email
date: ISO-8601 timestamp
message: commit message
files_changed: count of files changed in the commit

Tier: Solo and above.

forge_git_blame

Per-section blame showing which commit last modified each line range of a file.

Parameters:

Name	Type	Required	Description
`file`	string	yes	File to blame, relative to the repo root.
`repo`	string	no	Repository root path.

Output: Array of blame sections, each with:

start_line: first line of the section
end_line: last line of the section
commit_hash: hash of the last commit to touch this range
author: author name
date: ISO-8601 timestamp
message: commit message

Tier: Solo and above.

Ingest Tools

forge_ingest_scip

Ingest a SCIP (Stack-based Code Intelligence Protocol) index file. Upgrades heuristic import edges to compiler-resolved edges for higher-accuracy graph queries.

Parameters:

Name	Type	Required	Description
`path`	string	yes	Path to the SCIP index file (typically `index.scip`).
`repo`	string	no	Repository root path.

Output:

edges_imported: number of compiler-resolved edges added
files_updated: number of files with upgraded edges

Tier: Pro and above.

forge_coverage

Query test coverage data. Returns a repo-wide summary sorted by lowest coverage, or per-file detail.

Parameters:

Name	Type	Required	Description
`repo`	string	no	Repository root path.
`file`	string	no	When specified, returns line-level coverage detail for this file.
`symbol`	string	no	When specified, returns coverage for a named symbol.

Output (repo-wide): Array of file coverage records sorted by line coverage ascending, each with:

file: file path
lines_covered: count of covered lines
lines_total: total lines
coverage_pct: percentage covered

Output (per-file): Detailed line coverage map with covered/uncovered ranges.

Tier: Solo and above.

Index Tools

forge_index_status

Index statistics: file count, last index time, stale file count, and git history availability.

Parameters:

Name	Type	Required	Description
`repo`	string	no	Repository root path.

Output:

files_indexed: total files in the index
last_indexed_at: ISO-8601 timestamp of the last index run
stale_files: files modified since the last index
has_search_index: whether the Tantivy search index exists
has_git_history: whether git history has been ingested
has_embeddings: whether vector embeddings are available

Tier: Community and above (not rate-limited against Community quota).

forge_reindex

Trigger an incremental or full re-index programmatically.

Parameters:

Name	Type	Required	Description
`repo`	string	no	Repository root path.
`full`	boolean	no	Perform a full re-index (default: false for incremental).

Output:

files_indexed: count of files processed
duration_ms: time taken in milliseconds

Tier: Solo and above.