gograph

Detect public API surface drift by comparing exported Go symbols between the current working tree and a baseline. A `since` value ending in `.json` loads a regular saved graph inside the project root with no linked path component and the exact current repository source-policy marker; its serialized root is ignored. Otherwise gograph validates the value as a Git ref and uses `git archive` to build a temporary baseline. The MCP server checks freshness before this call and refreshes in the current requested analysis mode; precise and precise_fallback graphs retry CHA/SSA after source changes. Read-only apart from reading the selected graph or extracting a temporary archive that is removed after the call. WHEN TO USE: Before releasing or merging a PR to catch breaking-change regressions — exported symbols added, removed, or renamed since the baseline. NOT TO USE: For listing current exports without a diff baseline (use gograph_public or gograph_skeleton instead). RETURNS: JSON with baseline and breaking flags; nested exported_symbols, interfaces, structs, and routes groups containing added/removed arrays plus changed detail objects; affected_tests, affected_mocks, and findings arrays. Empty groups indicate no drift.

Find functions and methods with at least a threshold number of parameters — the long-parameter-list smell. The MCP server checks freshness before this call. Read-only; no side effects. `min` sets the inclusive minimum (default: 5; 0 includes zero-arity functions), matching CLI --min. WHEN TO USE: During code smell audits. NOT TO USE: For struct field counts (use gograph_fields or gograph_godobj). RETURNS: Functions meeting the threshold with parameter count, signature, and file location.

Refresh source analysis and check package imports against a boundaries.json configuration. The required config defaults to .gograph/boundaries.json; explicit paths must remain inside the analyzed project, and every path component plus the final regular file is read through the rooted repository boundary. Create it with gograph_boundaries_create. Read-only; no side effects. WHEN TO USE: In CI gates or post-edit reviews to enforce layer separation. NOT TO USE: For unconstrained dependency exploration (use gograph_deps or gograph_coupling). RETURNS: Structured pass state and boundary violations.

Create a baseline architecture boundary configuration from the repository's current package imports. Defaults to .gograph/boundaries.json under the graph root, uses repository-rooted regular-file creation, and refuses linked paths or overwrite. Mutating and non-idempotent; no network access. WHEN TO USE: Once when adopting boundary checks in an existing repository, then review and tighten the generated rules. NOT TO USE: To verify an existing configuration (use gograph_boundaries). RETURNS: The written config path or an error when the path is unsafe or already exists.

Find functions and methods called by the specified function. Defaults to one-hop fan-out; depth 2-10 expands the downstream call graph. The MCP server refreshes source analysis before the call. Read-only; no persistent side effects. WHEN TO USE: To understand a function's downstream dependencies. NOT TO USE: For upstream callers (use gograph_callers); for package dependency trees (use gograph_deps). RETURNS: Callee symbols with package paths, file locations, and call-site line numbers; with mermaid=true, Mermaid flowchart text.

Find functions and methods that call the specified function or interface method. Defaults to one-hop fan-in; depth 2-10 expands callers-of-callers. In a precise graph, Interface.Method expands through all recorded implementations and reports a shared source call site once. The MCP server refreshes source analysis before the call. Read-only; no persistent side effects. WHEN TO USE: Before renaming, removing, or changing a function or interface method signature. NOT TO USE: For unbounded upstream blast radius (use gograph_impact); for downstream callees (use gograph_callees). RETURNS: Caller symbols with package paths, file locations, and call-site line numbers; with mermaid=true, Mermaid flowchart text.

List the running gograph server version, all available MCP tools, their purposes, and recommended agent workflows. Once the project-scoped MCP server has started, this tool has no additional graph-state prerequisite. Read-only; no side effects. WHEN TO USE: Call once per session to record the analysis instrument and orient before issuing analytical queries. NOT TO USE: Do not repeat after capabilities are cached in context. RETURNS: Structured JSON with version, every registered tool name, one-line purposes, recommended workflow sequences, and known static-analysis limitations.

Compare Go declaration fingerprints, including bodies, without marking every symbol in an edited file modified. Without git_ref, inspects trusted persisted graph.json without refreshing, or the startup fallback if no usable artifact exists. With git_ref, refreshes and extracts a confined declaration baseline without compiling application code. Existing but deselected files are excluded, not deleted; unsafe inputs and parse failures produce diagnostics, never deletion proof. Missing legacy declaration fingerprints produce unknown. Read-only analysis. WHEN TO USE: After editing to identify changed declarations before impact/review. NOT TO USE: For line-level diffs or a complete census when evaluation is partial/cannot_evaluate. RETURNS: Native gograph.changes.v1 with complete/partial/cannot_evaluate, diagnostics, changed_files, and new/modified/deleted/excluded/unknown symbol rows; CLI uses the same value and exits 2 for incomplete evaluation. Uncommitted modes compare declarations against HEAD, including selected untracked Go files. Traversal consumers refuse deleted declarations requiring historical caller evidence. Review instead includes changes --git HEAD declaration evidence and names unavailable historical callers, tests and risk. Incomplete comparisons and missing/ambiguous current identities remain errors. Rebuild before traversing newly added symbols.

Refresh source analysis and run static policy checks: boundaries, API drift, changed-route/export tests, test coverage, orphans, globals, arity, and complexity. The default or a relative checks config is confined to a regular non-linked file beneath the project; an absolute config is an explicit operator-selected regular file. Baselines use the same validated builder as CLI: a value ending in `.json` loads a regular saved graph inside the project root with no linked component and the exact current source-policy marker, ignoring its serialized root; otherwise it is treated as a Git ref and extracted temporarily. WHEN TO USE: During PR review or pre-commit analysis. NOT TO USE: For CI process exit enforcement (use CLI gograph gate). RETURNS: Structured pass/warn/fail status, findings, and summary counts. Uncommitted modes compare declarations against HEAD, including selected untracked Go files. Traversal consumers refuse deleted declarations requiring historical caller evidence. Review instead includes changes --git HEAD declaration evidence and names unavailable historical callers, tests and risk. Incomplete comparisons and missing/ambiguous current identities remain errors. Rebuild before traversing newly added symbols.

Report estimated cyclomatic complexity for Go functions, sorted highest-to-lowest with severity labels (LOW/MEDIUM/HIGH/VERY HIGH). A function whose repository source cannot be read or parsed safely is retained as UNKNOWN with score -1. The MCP server checks freshness before this call and refreshes in the current requested analysis mode; precise and precise_fallback graphs retry CHA/SSA after source changes. Read-only; no side effects. Optional `symbol` substring filters to a specific function or set of functions. WHEN TO USE: During code quality audits, identifying functions that need decomposition, or setting complexity budgets in CI. NOT TO USE: For import dependency metrics (use gograph_coupling or gograph_deps); for God Object detection (use gograph_godobj). RETURNS: Structured list of functions with complexity score and severity label; empty when no functions match the filter.

Find indexed concurrency sites in the codebase: goroutine spawns (`go` statements), channel sends, and calls on sync.Mutex/RWMutex, sync.WaitGroup, and sync.Once. The MCP server checks freshness before this call and refreshes in the current requested analysis mode; precise and precise_fallback graphs retry CHA/SSA after source changes. Read-only; no side effects. Optional `term` filter (e.g., "mutex", "goroutine", "channel"). WHEN TO USE: When auditing race safety, understanding async flow, or locating synchronization points before a concurrency refactor. NOT TO USE: For standard sequential call flow analysis (use gograph_callers/gograph_callees). RETURNS: File locations, line numbers, and primitive kind for each indexed concurrency site; empty when no sites are found. Channel receives and select statements are not indexed.

Find all factory and constructor functions that instantiate and return a named Go struct (functions whose return type includes the struct name). The MCP server checks freshness before this call and refreshes in the current requested analysis mode; precise and precise_fallback graphs retry CHA/SSA after source changes. Read-only; no side effects. WHEN TO USE: When looking for the canonical way to create a struct, or before modifying struct initialization to ensure all construction paths are updated. NOT TO USE: For direct composite-literal sites (use gograph_literals); for struct fields (use gograph_fields). RETURNS: List of constructor function names with signatures, package paths, and file locations; empty when no factory functions are found.

Fetch a pre-flight context bundle for a single Go symbol: AST node metadata, source code, direct callers, direct callees, linked test functions, and architectural role classification — all in one call. The MCP server checks freshness before this call and refreshes in the current requested analysis mode; precise and precise_fallback graphs retry CHA/SSA after source changes. Read-only analysis; an active audit session may append local command telemetry. Set uncommitted=true to bundle context for all currently modified symbols at once. WHEN TO USE: As the first call before editing a symbol — eliminates 4–5 separate tool roundtrips. NOT TO USE: For package-level orientation (use gograph_focus); for transitive blast radius (use gograph_impact). RETURNS: JSON with node (first match), nodes[] (all matches), source, callers[], callees[], tests[], test_results[], and top-level role in both text and gograph.read.v1 structured content; a missing symbol is a named error. source_error reports a partial context when indexed metadata exists but source cannot be served, also named in graph_state.read_diagnostic. With uncommitted=true, returns a contexts[] array; count:0 when no uncommitted symbols exist. Uncommitted modes compare declarations against HEAD, including selected untracked Go files. Traversal consumers refuse deleted declarations requiring historical caller evidence. Review instead includes changes --git HEAD declaration evidence and names unavailable historical callers, tests and risk. Incomplete comparisons and missing/ambiguous current identities remain errors. Rebuild before traversing newly added symbols.

Report fan-in (Ca), fan-out (Ce), and instability I=Ce/(Ca+Ce) per package. The MCP server refreshes source analysis before the call. Read-only; no side effects. package filters by substring; include_stdlib and internal_only control scope. WHEN TO USE: To evaluate package isolation. RETURNS: Package coupling records; with mermaid=true, Mermaid flowchart text.

Return the transitive set of production functions and methods statically reachable from one test function. The MCP server refreshes the graph first. Exact results have an all-static path; any parser-only or CHA dispatch edge degrades that symbol and its descendants to possible. Same-named tests in multiple packages return status=ambiguous and are never merged; retry with the stable test ID from matched_tests or gograph_identity. The optional package qualifier resolves the uncommon in-package versus external foo_test ID collision. Set exact_only=true to omit possible results. This is static attribution, not runtime or branch coverage proof. Read-only; no side effects. WHEN TO USE: To map one test to the product symbols it structurally exercises. NOT TO USE: To claim execution or branch coverage. RETURNS: gograph.coverage.v1 JSON with analysis precision, test-call resolution, matched tests, symbols, resolution, depth, representative stable-ID paths, and limitations.

Find all packages that import the named package (inverse of gograph_deps). The MCP server refreshes source analysis before the call. Read-only; no side effects. WHEN TO USE: Before a package-level interface change or removal. NOT TO USE: For a single function's callers (use gograph_callers). RETURNS: Dependent packages; with mermaid=true, Mermaid flowchart text.

List the import dependencies of a named package. With transitive=false (default), returns direct imports; true returns the BFS closure. The MCP server refreshes source analysis before the call. Read-only; no side effects. WHEN TO USE: When auditing package layering. NOT TO USE: For reverse lookup (use gograph_dependents). RETURNS: direct[] and transitive[] arrays; with mermaid=true, Mermaid flowchart text; found:false when absent.

Refresh source analysis and generate a Mermaid architecture diagram of the package dependency graph. Read-only; no side effects. WHEN TO USE: Onboarding, architecture review, or communicating package structure. Use group_by=module for monorepos and group_by=file for drill-downs. NOT TO USE: For call-graph traversal or single-package focus. RETURNS: Mermaid text; use max_depth or coarser grouping for large graphs.

Fetch Go documentation for a package, stdlib symbol, or third-party symbol by running `go doc <query>`. The handler does not query the graph, though the project-scoped MCP server must already have started with a usable artifact or buildable Go source. Filesystem-shaped queries are rejected, and the command is refused for source-tree links the Go toolchain may inspect across the selected root plus its effective module root, or the workspace root and member trees; .git and .gograph are excluded from that preflight. It also refuses a special recognized Go build input, linked/non-regular Go tool metadata (go.mod, go.sum, go.work, go.work.sum, or vendor/modules.txt), or a workspace member outside the workspace directory. Each applicable member directory, go.mod, and optional go.sum is validated first. Dependency and toolchain resolution remain open-world under the user's Go environment. WHEN TO USE: When a call chain reaches code outside the project. NOT TO USE: For project-internal symbols (use gograph_source or gograph_context). RETURNS: A one-element JSON array containing {query, output}, where output is the raw go doc text; an error when the query or repository input is unsafe, the symbol is not found, or go is unavailable.

Find all Go structs that embed the named struct via anonymous field composition. The MCP server checks freshness before this call and refreshes in the current requested analysis mode; precise and precise_fallback graphs retry CHA/SSA after source changes. Read-only; no side effects. WHEN TO USE: When understanding how a base type is extended throughout the codebase, or before modifying a shared embedded struct to estimate blast radius. NOT TO USE: For interface implementations (use gograph_implementers); for named field type references in other structs (use gograph_usages). RETURNS: List of embedding parent struct names with package paths and file locations; empty when the struct is embedded nowhere.

Build a full vertical slice for one HTTP route: the matched handler symbol, a BFS call chain downstream (default depth 5), all SQL queries emitted in that chain, and all env vars read. Constant nested Gin/Echo/Fiber Group prefixes and Chi Route closure prefixes are composed into final paths; dynamically computed prefixes remain unresolved and can still be queried by suffix or handler. The MCP server checks content-digest freshness before this call and incrementally refreshes changed package ASTs in the current requested analysis mode; precise and precise_fallback graphs retry repository-wide CHA/SSA after source changes. Read-only; no side effects. WHEN TO USE: When auditing what an API endpoint does end-to-end — its downstream dependencies, database queries, and configuration reads. NOT TO USE: For listing all routes (use gograph_routes first to find the pattern); for raw handler source code only (use gograph_source). RETURNS: Array of endpoint slices with route, handler, call chain, SQL, and env fields; found:false with a suggestion when the query does not match any route. `query` accepts route pattern ("POST /api/users"), path fragment ("/users"), or handler name. `depth` controls call-chain BFS depth (default: 5).

Find all environment variable reads in the codebase via os.Getenv, os.LookupEnv, and common config frameworks, with their enclosing function context. The MCP server checks freshness before this call and refreshes in the current requested analysis mode; precise and precise_fallback graphs retry CHA/SSA after source changes. Read-only; no side effects. Optional `term` filters by key name substring (e.g., "DATABASE" matches DATABASE_URL and DATABASE_HOST). WHEN TO USE: When compiling a deployment configuration manifest, documenting required env vars, or auditing what secrets a service reads at startup. NOT TO USE: For reading actual runtime env values (this is static analysis); for database queries (use gograph_sql). RETURNS: List of env key names, calling function, and file/line; empty when no env reads match the filter.

Trace how a named error sentinel or error message string is defined, returned, and propagates up the call graph toward HTTP handlers or CLI entry points. The MCP server checks freshness before this call and refreshes in the current requested analysis mode; precise and precise_fallback graphs retry CHA/SSA after source changes. Read-only; no side effects. Accepts either `query` (preferred) or `term` as the error name or message substring. WHEN TO USE: When auditing how a specific error is produced and handled end-to-end — find definition sites, all return sites, and upstream propagation paths (e.g., ErrNotFound). NOT TO USE: For general upstream traversal of any function (use gograph_callers or gograph_impact); for listing all error definitions (use gograph_errors). RETURNS: Definition sites, return sites, propagation path chains, and related test names; paths is empty when no propagation chain is found. Note: heuristic analysis — does not perform SSA or full data-flow tracking.

Find all error and panic sites in the codebase: errors.New, fmt.Errorf, sentinel var declarations, and panic calls. The MCP server checks freshness before this call and refreshes in the current requested analysis mode; precise and precise_fallback graphs retry CHA/SSA after source changes. Read-only; no side effects. Optional `term` filters by message substring (e.g., "ErrInvalid", "unauthorized"). WHEN TO USE: When cataloging error codes and panic paths, standardizing error messages, or checking whether a specific error string is already defined before adding a new one. NOT TO USE: For tracing how an error propagates up the call stack (use gograph_errorflow instead). RETURNS: List of error or panic sites with message text, file path, and line number; empty when no matches found.

Generate a synthesized, LLM-ready narrative for a Go symbol: role classification, callers, callees, complexity, SQL, env vars, HTTP routes, concurrency primitives, tests, and interface satisfaction — all in one structured document. The MCP server checks freshness before this call and refreshes in the current requested analysis mode; precise and precise_fallback graphs retry CHA/SSA after source changes. Read-only; no side effects. WHEN TO USE: For onboarding to an unfamiliar symbol, generating PR documentation, or getting an opinionated architectural assessment without issuing multiple tool calls. NOT TO USE: For raw source code (use gograph_source); for targeted blast-radius analysis (use gograph_impact). RETURNS: Rich structured JSON with role, narrative summary, and all associated cross-references; {"found":false} when symbol is not in the graph.

Explore a lexical term or Go symbol in one bounded call. Standard mode combines ranked matches with selected-symbol source, direct callers/callees, tests, and exact impact. compact=true returns discovery, selected-node metadata, role, complete counts, and explicit omitted_sections while suppressing token-heavy bodies (default limit 5). deep=true retains standard evidence and adds bounded depth-3 exact identity callers/callees, package context, and explanation (default limit 25). compact and deep are mutually exclusive; an explicit limit overrides their defaults. Possible dispatch is excluded from bundled identity impact and deep traversals. The MCP server refreshes source analysis before the call. Read-only; no persistent side effects. Question-like text is lexical, not model-interpreted. Focused tools remain authoritative for complete output. RETURNS: shared gograph.explore.v1 with mode, selection_basis, ambiguity, totals, truncation, and omission metadata.

Extract all declared fields from a named Go struct: field names, Go types, and raw struct tag strings (json, db, yaml, gorm, etc.). The MCP server checks freshness before this call and refreshes in the current requested analysis mode; precise and precise_fallback graphs retry CHA/SSA after source changes. Read-only; no side effects. WHEN TO USE: When mapping JSON/DB serialization tags, inspecting struct layouts, or enumerating fields before adding a new one. NOT TO USE: For methods on the struct (use gograph_node or gograph_source); for all struct initialization sites (use gograph_literals). RETURNS: Array of field entries with name, type, and tag string; empty when the struct is not found.

Find test helper structs and factory/builder functions declared in *_test.go files for a named package. The MCP server checks freshness before this call and refreshes in the current requested analysis mode; precise and precise_fallback graphs retry CHA/SSA after source changes. Read-only; no side effects. WHEN TO USE: Before writing new tests — check what test infrastructure (helper builders, stub factories, shared setup structs) already exists in the package to avoid duplication. NOT TO USE: For test functions that exercise a symbol (use gograph_tests); for external test data files on disk (those are not tracked in the graph — use filesystem search). RETURNS: Symbols defined in test files for the package including helper structs and factory functions; empty when the package has no test helper infrastructure.

Find potential untrusted-data paths from HTTP request objects, decoded JSON values, or environment variables to SQL query text, process execution arguments, filesystem paths, or outbound HTTP targets. The MCP server refreshes source analysis before this call; run `gograph build . --precise` first for stronger method/interface targets. Read-only; no side effects. WHEN TO USE: During a security review or before changing request parsing, command execution, file access, SQL construction, or URL handling. NOT TO USE: As proof of exploitability; the analysis is path-insensitive and call/return context for the 3 most recent call sites by default (context depth up to 16; deeper returns that lose their call site are kept at low confidence), bounded by a size-derived work budget that reports incomplete runs explicitly. RETURNS: Structured findings with source, sink, severity, confidence, and path steps. Configure trusted return-value sanitizers in .gograph/flow.json or with config.

Extract a comprehensive structural summary of one Go package: all files, defined symbols, internal call edges, and package-level imports. The MCP server checks freshness before this call and refreshes in the current requested analysis mode; precise and precise_fallback graphs retry CHA/SSA after source changes. Read-only; no side effects. WHEN TO USE: When orienting to an unfamiliar package before editing it — provides a full map of what the package contains and how it connects to the rest of the codebase. NOT TO USE: For a single symbol's details (use gograph_context or gograph_source); for global keyword searches (use gograph_query). RETURNS: All files, symbol names, call edges, and import paths within the package; empty when the package is not found.

Find package-level variable declarations (var blocks) and the functions that mutate them in a specific package. The MCP server checks freshness before this call and refreshes in the current requested analysis mode; precise and precise_fallback graphs retry CHA/SSA after source changes. Read-only; no side effects. WHEN TO USE: When auditing mutable global state, identifying thread-safety hazards, or locating shared singleton variables before a concurrency refactor. NOT TO USE: For local-scope variables; for environment variable reads (use gograph_envs). RETURNS: Package-level variable names, types, and the functions that write to them; empty when the package has no package-level variables.

Detect God Object anti-pattern candidates by scoring structs on method count, field count, and outgoing call count. The MCP server checks freshness before this call and refreshes in the current requested analysis mode; precise and precise_fallback graphs retry CHA/SSA after source changes. Read-only; no side effects. Thresholds: `methods` (default: 5), `fields` (default: 8), `calls` (default: 15); `top` limits results (default: 10). Exceeding any enabled threshold qualifies a struct, and the combined excess determines rank. WHEN TO USE: During architecture reviews to find monolithic structs that should be decomposed. NOT TO USE: For general struct layout inspection (use gograph_fields); for single-function complexity (use gograph_complexity). RETURNS: Ranked candidates with method, field, and call counts; empty when no threshold is exceeded.

Rank functions by incoming call count (fan-in) to identify the most-depended-on symbols in the codebase. The MCP server checks freshness before this call and refreshes in the current requested analysis mode; precise and precise_fallback graphs retry CHA/SSA after source changes. Read-only; no side effects. `top` controls result count (default: 10; 0 = all). Set include_tests=true to count test-file call edges — by default excluded so test helpers don't dominate rankings in test-heavy codebases. WHEN TO USE: When deciding where to invest refactoring effort or documentation — high fan-in functions are the highest-risk change targets. NOT TO USE: For single-package metrics (use gograph_focus or gograph_coupling); for complexity scores (use gograph_complexity). RETURNS: Ranked list of function names with fan-in count and package location.

List a bounded page of HTTP evidence from imported, unshadowed net/http Get/Post/PostForm/Head calls and possible NewRequest/NewRequestWithContext construction. Client receiver methods and arbitrary URL-building functions are not inferred. Static strings and bounded lexical base + static suffix expressions are recorded; runtime environment values are never read. Construction is not dispatch proof. Workspace http_clients may explicitly map bases or env:KEY to scoped logical authorities; unresolved destinations remain workspace diagnostics. The MCP server refreshes source analysis before this call. Read-only. Optional term matches method, URL/base, or function. RETURNS: gograph.results.v1 rows with file/line and dynamic base/suffix or request-only evidence in detail, plus total/returned/truncated/next_cursor. For server routes use gograph_routes.

Resolve an exact Go symbol spelling or canonical stable ID to location-independent symbol identity plus current source location. Canonical IDs are module import path + receiver/name and survive line shifts and file moves within the same package; package/module moves, receiver changes, and renames change the ID. Ambiguous short names return every candidate and never select one silently. An optional exact package qualifier disambiguates the uncommon in-package versus external foo_test ID collision. The MCP server refreshes the graph first. Read-only; no side effects. WHEN TO USE: Before persisting cross-document references or to re-resolve an existing stable ID. RETURNS: gograph.identity.v1 JSON with status exact, ambiguous, or not_found and deterministic matches.

Traverse the call graph backwards to find every symbol that transitively calls the target — the full upstream blast radius of a change. The MCP server checks freshness before the call. Read-only; no side effects. Three modes: (1) single symbol via `symbol`; (2) uncommitted changes via `uncommitted=true`; (3) git-ref changes via `since`. WHEN TO USE: Before refactoring a core function to see what breaks. NOT TO USE: For direct one-hop callers only (use gograph_callers). RETURNS: Transitive upstream affected symbols; with mermaid=true, Mermaid flowchart text; a bounded native page (including empty pages). Exact and possible paths remain distinct; Mermaid uses dotted edges for possible evidence. Uncommitted modes compare declarations against HEAD, including selected untracked Go files. Traversal consumers refuse deleted declarations requiring historical caller evidence. Review instead includes changes --git HEAD declaration evidence and names unavailable historical callers, tests and risk. Incomplete comparisons and missing/ambiguous current identities remain errors. Rebuild before traversing newly added symbols.

Find all concrete structs that implement a named Go interface. Type-checked production results are merged with AST-discovered implementations from test files because production package loading excludes test variants. The MCP server checks freshness before this call and refreshes in the current requested analysis mode; precise and precise_fallback graphs retry CHA/SSA after source changes. Read-only; no side effects. Set test_only=true to restrict to structs in *_test.go files (mocks/stubs). WHEN TO USE: When tracing polymorphism, locating dependency injection points, or finding all mock implementations of an interface. NOT TO USE: For interfaces a struct satisfies — inverse direction (use gograph_interfaces instead); for struct fields (use gograph_fields). RETURNS: List of implementing struct names with package paths and file locations; empty when no struct implements the interface.

Find all files and packages in the codebase that import a specific package by its exact import path. The MCP server checks freshness before this call and refreshes in the current requested analysis mode; precise and precise_fallback graphs retry CHA/SSA after source changes. Read-only; no side effects. WHEN TO USE: When isolating usage of a third-party library before removing or replacing it, or tracing where an internal package is consumed from outside. NOT TO USE: For a package's own outgoing imports (use gograph_deps); for reverse package-level dependency lookup by short name (use gograph_dependents). RETURNS: File paths and package names of all importers; empty when the package is imported nowhere.

Find all Go interfaces satisfied by a named concrete struct (duck-typing resolution — inverse of gograph_implementers). Given a struct name, returns every interface whose complete method set is a subset of that struct's methods. The MCP server checks freshness before this call and refreshes in the current requested analysis mode; precise and precise_fallback graphs retry CHA/SSA after source changes. Read-only; no side effects. WHEN TO USE: When you need to know which contracts a struct implicitly fulfills — useful before refactoring a method to understand which interface contracts will break. NOT TO USE: For finding structs that implement an interface (use gograph_implementers); for listing interface declarations in a package (use gograph_node or gograph_public). RETURNS: Interface names, method signatures, and file locations; empty when the struct satisfies no known interfaces.

Find every composite-literal initialization site for a named Go struct — all locations where Foo{...} syntax is used to construct the struct. The MCP server checks freshness before this call and refreshes in the current requested analysis mode; precise and precise_fallback graphs retry CHA/SSA after source changes. Read-only; no side effects. WHEN TO USE: Before adding a required field to a struct — every site returned will fail to compile if the new field has no default; run this first to scope the migration blast radius. NOT TO USE: For finding string or integer magic values (use gograph_envs or grep for those); for factory functions that return the struct (use gograph_constructors). RETURNS: All file paths and line numbers where the named struct is composite-initialized; empty when the struct has no direct initialization sites.

Find structs in *_test.go files that implement a named interface — test doubles, mocks, and stubs. Equivalent to gograph_implementers with test_only=true; kept for compatibility. The MCP server checks freshness before this call and refreshes in the current requested analysis mode; precise and precise_fallback graphs retry CHA/SSA after source changes. Read-only; no side effects. WHEN TO USE: When writing tests and wanting to find existing mock implementations before creating a new one. NOT TO USE: For production interface implementers (use gograph_implementers without test_only); prefer gograph_implementers(test_only=true) for new code. RETURNS: Test-file struct names implementing the interface with file locations; empty when no test mocks exist for the interface.

Find struct-field and package-global mutation sites. Use Type.Field to exclude same-named fields on unrelated types; ordinary local-variable assignments are excluded. The MCP server refreshes in the current requested analysis mode; a precise graph adds ++/+=, pointer-alias, atomic/sync/wrapper, and channel mutations and re-runs that analysis after source edits. Read-only; no side effects. WHEN TO USE: Diagnosing state changes or auditing mutability. NOT TO USE: For field declarations (gograph_fields) or whole-struct initialization (gograph_literals). RETURNS: Mutation locations and indirect mutator method names when applicable.

Fetch AST metadata for a named symbol, package, or file: kind, file path, line number, full signature, doc comment, and struct fields if applicable. The MCP server checks freshness before this call and refreshes in the current requested analysis mode; precise and precise_fallback graphs retry CHA/SSA after source changes. Read-only; no side effects. WHEN TO USE: When you need structural metadata (kind, signature, line number) without the full source body — lighter than gograph_source for metadata-only lookups. NOT TO USE: For full source code (use gograph_source); for call relationships (use gograph_callers/gograph_callees). RETURNS: Node properties array with kind, file, line, and signature; empty when the name is not found.

Find functions and methods unreachable from runtime roots (main/init), test/benchmark/fuzz roots, HTTP route handlers, and eligible externally callable exports; exports confined under internal/ are not roots. Uses full BFS reachability. The MCP server checks freshness before this call and refreshes in the current requested analysis mode; precise and precise_fallback graphs retry CHA/SSA after source changes. Read-only; no side effects. WHEN TO USE: During code cleanup or dead-code audits. NOT TO USE: For checking one symbol's usages (use gograph_usages or gograph_callers). RETURNS: Orphan symbols with package paths and file locations; empty means no unreachable code was detected.