MCP_TOOLS.md

Forge MCP Tools Reference

Forge ships a Model Context Protocol server whose live counts are recorded in ../forge_metrics.json and whose canonical tool/recipe ledger lives in ../surface.json. The per-tool table below lists the primary dispatch key for each tool; compatibility routes still live in the canonical surface ledger. All legacy tool names redirect automatically — existing callers keep working.

• Local: forge mcp serve --project /path/to/repo
• Deployed Worker: forge.atomadic.tech/mcp
• MCP Registry: registry.modelcontextprotocol.io

First call: always call welcome at the start of a session to orient the agent and get a scored snapshot of the repo.

---

Tool Summary

Tool	Dispatch	Purpose
welcome	none	Session onboarding: scan, score, narrative, capability tour
explore	action=	Analyze and understand a codebase — recon, call graphs, smells, harvest, discovery, agent plans
audit	action=	Quality gates, change safety, trust verification
plan	action=	Dev orientation and utilities — context packs, recipes, commit messages, steersman packs
transmute	action=	FLAGSHIP spaghetti-to-certified pipeline
loop	action=	LLM iteration and self-improvement loops
hive	action=	Multi-agent coordination — consensus, handoffs, enhancements
wisdom	action=	Institutional memory — record and query cross-session knowledge
nexus	op=	AAAA-Nexus auth primitives
inspect	action=	Low-level AST inspection — body extraction, symbol reads, repo classification
create	none	Intent + seed repos → shippable pip package

---

welcome

RECOMMENDED FIRST CALL. No action parameter — just call it.

Runs scout + certify + wire on the current repo and returns a single structured response: real numbers (score, violations, symbol count), top 3 strengths, top 3 priorities, and the single most-useful next call for the session.

{ "tool": "welcome", "project_root": "/path/to/repo" }

---

explore

Action-dispatch tool. Use when you need to analyze, understand, or discover patterns in a codebase. No LLM is invoked — all analysis is deterministic.

Action	What it does
recon	Tier map — classify every public symbol, tier/effect distributions
explain	Narrative orientation — humane operational summary of the repo
call_graph	Symbol-level dependency graph
call_graph_summary	Package-level portfolio graph (lighter than full call_graph)
smell_scan	Code smell detection (complexity, duplication, anti-patterns)
churn	Git file churn — surfaces hot files that change most often
lineage	Symbol-level provenance and surface history
harvest	Trust-gated cross-repo capability grafting
synergy	Feature-pair detection and adapter auto-generation
scan	Emergent composition scan — surfaces cross-domain patterns
swarm	Multi-repo portfolio emergent scan (N ≤ 23 repos)
surface_gaps	Capability gap finder across repos
capability_scout	Scout for specific capability presence
dead_code	Identify unreachable or unused symbols
maintainability	Maintainability index per file/module
concept_bridge	Cross-domain concept linkage detection
agent_plan	Generate a ranked agent execution plan with risk + rollback

explore and audit share several actions: dead_code, maintainability, concept_bridge, and surface_gaps are accepted by both tools.

---

audit

Action-dispatch tool. Use when you need to check correctness, apply fixes, or gate a change.

Action	What it does
certify	0-100 quality score (docs, tests, tier layout, import discipline). emit_receipt=true produces Forge Receipt v1.
wire	Find every upward-import violation. suggest_repairs=true adds fix hints.
enforce	Apply mechanical fixes for wire violations. apply=false is dry-run.
validate	Validate a .forge sidecar TOML — required fields and types.
guard	Install four enforcement layers: pre-commit hook, GHA workflow, pyproject contract, CONTRIBUTING block.
composite	Single go/no-go verdict — wire + certify always; score_patch + preflight when diff/intent supplied. Returns PASS/REFINE/FAIL.
gate	Deterministic hallucination detector for LLM responses — catches unresolved imports, stubs, false capability claims.
health	Repo health overview combining multiple signals.
check	Lightweight pre-edit guardrail — returns tier, forbidden imports, affected tests, scope warnings.
score	Patch risk scorer — rates a diff for structural risk.
tests	Test selection — returns the minimal test set impacted by a change.
cna	CNA (Compose-Not-Add) check — rejects new symbols that duplicate existing ones.
rollback	Generate a rollback plan for a proposed change.
diff	Structured diff analysis between two states.
ast_scope	Build multi-repo AST blueprints plus deterministic Nexus-attestable edit locks.
surface_gaps	Surface capability gaps in the current repo.
wire_stubs	Generate stub implementations to satisfy wire constraints.
dead_code	Identify unreachable or unused symbols.
maintainability	Maintainability index per file/module.
concept_bridge	Cross-domain concept linkage detection.
auto_wire	Deterministically wire generated surface stubs. CLI stubs produced by auto-wire coerce list[float]/list[int]/list[str] arguments from comma-separated strings (v0.81).
doc_update	Regenerate public docs from metrics.
doc_drift	Detect public-doc metric drift.

---

plan

Action-dispatch tool for orientation, workflow recipes, commit hygiene, and tiny-model routing.

Action	What it does
context	First-call context bundle — symbols, tier map, blockers, next action
compose	Match a goal keyword to a named workflow recipe
policy	Return the raw agent policy dict without full orientation
recipes	List the full recipe catalogue or fetch one named recipe
generate	Run scout + wire + certify and emit a ranked agent_plan/v1
apply	Execute a saved plan (plan_id required). apply=false dry-runs.
locate	Return insertion-point line range + preview (~1000-token saving)
commit	Assemble a structured commit message (~10k-token saving)
scaffold	Scaffold a new module or feature at the correct tier
steersman	Build AST-lock decision packs tiny enough for a 1B semantic router

---

transmute

FLAGSHIP pipeline. Takes unstructured spaghetti and emits a tier-organized, certify-100/100 package. No LLM required for the structural work.

Action	What it does
auto	Full pipeline: recon → cherry-pick → enforce → certify. The one-command refactor.
cherry	Cherry-pick the best candidates from a recon result for selective transmutation.
finalize	Apply the cherry-picked transmutation. apply=false dry-runs.

Typical call sequence: auto (one-shot) or cherry → inspect → finalize.

---

loop

Action-dispatch tool for LLM-in-the-loop iteration and self-improvement.

Action	What it does
iterate	Start an LLM loop: intent → code → absorb → score → iterate
resume	Resume a paused iterate session by session ID
evolve	Recursive self-improvement over N rounds
evolve_step	Execute a single step of an evolve session

---

hive

Action-dispatch tool for multi-agent coordination — agent registry, consensus voting, handoffs, enhancement proposals.

Action	What it does
register	Register an agent in the hive
list	List active agents
deactivate	Deactivate an agent
observe	Record an observation from an agent
propose	Submit a consensus proposal
vote	Cast a vote on a proposal
needs_vote	Check whether a proposal needs more votes
result	Retrieve the consensus result
recap	Summarize recent hive activity
handoff_create	Create a structured session handoff artifact
handoff_list	List available handoffs
enhance_propose	Propose an enhancement to the codebase via hive consensus
enhance_list	List enhancement proposals

---

wisdom

Action-dispatch tool for institutional memory — record and query knowledge across sessions.

Action	What it does
record	Store a wisdom entry (insight, lesson, pattern)
query	Semantic search over stored wisdom
list	List all wisdom entries
recall	Retrieve a specific entry by ID
promote	Promote a wisdom entry to canonical guidance

---

nexus

Operation-dispatch tool for AAAA-Nexus auth and trust primitives.

Important: nexus uses op= as its dispatch key instead of action=. This avoids collision with the authorize_action operation's own action parameter that passes through to the Nexus API.

Op	What it does
identity_verify	Topological identity verification
federation_mint	Mint a cross-platform portable identity token
authorize_action	Pre-action authorization gateway with cryptographic token
sys_trust_gate	PASS/FAIL hallucination and drift screen for agent payloads
contract_verify	Verify agent policy claims against formal bounds
lineage_record	Tamper-proof decision trace capture with hash chain
ratchet_register	Register a 47-epoch RatchetGate session (MCP CVE-2025-6514 mitigation)

---

inspect

Action-dispatch tool for low-level AST inspection and repo-structure reads. Split from explore to give agents a clean, schema-validated surface for fine-grained code reads.

Action	What it does
body	Extract the full source body of a named function or class
symbol	Extract a named symbol (with its imports) from a source file
class_signals	Detect class-level signals (abstract, dataclass, protocol, etc.)
ast_scope_blueprint	Build a multi-repo AST scope blueprint for deterministic edit planning
mint_ast_locks	Mint time-bounded edit locks from an existing blueprint
add_node	Add a node to an existing AST scope (returns updated blueprint)
classify_repo_layout	Detect repo layout style (monadic, src-layout, flat, poetry, etc.)
fingerprint_repo	SHA-256 normalized-AST fingerprint per module (content hash, not file hash)
synthesis_plan	Extract actionable synthesis plan from harvest candidates below TAU_TRUST
swarm_repo_specs	Build batch repo-spec list for multi-repo emergent swarm operations

---

create

No action parameter. Intent + seed repos → shippable pip package.

Phase 1 pipeline: emergent_swarm + materialize. Supply a natural-language intent and one or more seed repo paths; Forge emits a fully-structured, tier-organized package ready for pip install.

{ "tool": "create", "intent": "a fast CSV differ", "seed_repos": ["/path/to/repo"] }

---

Dispatch Protocol

All tools except nexus and welcome use action=<name> for dispatch:

{ "tool": "explore", "action": "recon", "project_root": "/path/to/repo" }

nexus uses op=<name>:

{ "tool": "nexus", "op": "sys_trust_gate", "payload": "..." }

welcome and create take no dispatch key — pass parameters directly.

---

---

CLI-only verbs (no MCP action yet)

The following verbs added in v0.76–v0.80 are available on the CLI but do not yet have corresponding MCP actions:

CLI verb	Version	What it does
forge graft	v0.76	Single-symbol cross-repo capability transfer
forge token-savings	v0.78	Display lifetime token-savings ledger
forge replay	v0.79	Deterministic golden-recipe execution
forge mcb-check	v0.80	Flag unbounded loops/recursion in tier-a1
forge aiom-check	v0.80	Flag forbidden I/O imports in tier-a1
forge fingerprint	v0.80	SHA-256 normalized-AST fingerprint per a1 module
forge fuzz	v0.80	Hypothesis property fuzzing on __invariants__-annotated a1 callables

---

Numbers sourced from forge_metrics.json (canonical, regenerated on every push). Full CLI reference: docs/02-commands.md