gograph

Find the best call chain from one symbol to another. Competing paths rank exact before possible, then shorter, production before tests, typed resolution before heuristics, with a deterministic canonical tie-breaker. The MCP server refreshes source analysis before the call. Read-only; no side effects. WHEN TO USE: To confirm reachability between non-adjacent symbols. NOT TO USE: For all transitive upstream callers (use gograph_impact). RETURNS: from, to, found, and steps[]; with mermaid=true, Mermaid flowchart text.

Generate a structured pre-edit plan for a target symbol: which symbols to read first, which tests cover them, which routes and env vars they touch, and whether the change is public-API or SQL-touching. 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 with_context=true to inline full source+callers+callees for each symbol to inspect — eliminates follow-up gograph_context calls. WHEN TO USE: Before multi-file refactoring or architectural changes to understand scope upfront. NOT TO USE: For trivial single-line fixes; for post-edit verification (use gograph_review instead). RETURNS: JSON with inspect_first[], tests[], routes[], env[], and a risk object (public_api, touches_sql, etc.); with with_context=true, also includes inspect_contexts[] with full per-symbol bundles. 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.

List all exported (public) symbols of a specific package, including functions, methods, types/interfaces, variables, and constants. 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 reviewing a package's public contract before changing it, building integration documentation, or checking what a package exposes to callers. NOT TO USE: For unexported/private symbols (use gograph_node or gograph_focus); for API drift detection against a baseline (use gograph_api). RETURNS: List of exported symbol names with kinds and file locations; empty when the package has no exports or is not found.

Search the graph index for symbols, packages, files, and import edges that match one or more keyword substrings. Multiple terms use OR semantics, matching CLI `query term...`. The MCP server refreshes source analysis before the call. Read-only; no persistent side effects. WHEN TO USE: During initial exploration when you have a keyword or feature name but do not know its package. NOT TO USE: When you already know the exact symbol (use gograph_source or gograph_node); for package dependency trees (use gograph_deps). RETURNS: Matching symbols, files, and imports; empty when no terms match.

Show how each caller uses the return value(s) of a named function: discarded, assigned, partially ignored, returned upstream, or passed directly to another 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; no side effects. WHEN TO USE: Before changing a function's return signature — see which callers ignore the error or only use some return values. NOT TO USE: For error propagation tracing (use gograph_errorflow); for finding all callers without usage detail (use gograph_callers). RETURNS: List of call sites with usage classification (discarded/assigned/partially_ignored/returned/passed); empty when the function has no callers.

Summarize the scope and risk profile of a change: which symbols changed, which tests cover them, which routes and env vars they touch, and whether SQL is involved. 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. Requires either symbol or uncommitted=true. WHEN TO USE: After editing — as a post-edit verification step before committing; confirms the blast radius matches expectations. Use uncommitted=true to review all current unstaged changes at once. NOT TO USE: For boundary constraint enforcement (use gograph_boundaries); for pre-edit planning (use gograph_plan). RETURNS: JSON with changed_symbols[], tests[], routes[], env[], errors[], and a risk object (public_api, touches_sql, touches_routes, touches_env). 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.

Evaluate the change risk profile of target symbol(s) or uncommitted changes. Combines blast radius, cyclomatic complexity, test coverage, and downstream environment/SQL dependencies into a normalized 0–100 risk score and verdict. 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. Requires either symbol or uncommitted=true. WHEN TO USE: Before committing edits or when planning changes to understand the technical risk. NOT TO USE: For post-edit review checklist generation (use gograph_review); for pre-edit plan generation (use gograph_plan). RETURNS: JSON with title, results[] containing risk scores, verdicts, and breakdown metrics, and optional message. 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.

List a deterministic bounded page of HTTP routes with methods, URL patterns, handler names, and source locations. Production routes are returned by default; include_tests=true adds *_test.go registrations. Optional term matches method/path, handler, or file. module selects an exact module path/directory, a unique nested-module directory basename, or the repository directory name for a root module. limit defaults to 100 and is restricted to 1-200; next_cursor continues the same filtered census. Each page is also bounded to 64 KiB so the result stays directly consumable instead of spilling to an out-of-band file. Constant nested Gin/Echo/Fiber Group prefixes and Chi Route closure prefixes are composed; Gin/Fiber use the final variadic argument as the terminal handler, while Echo uses the handler immediately after the path. Dynamically computed prefixes remain unresolved. The MCP server refreshes source analysis before this call. Read-only; no side effects. WHEN TO USE: To inventory one service/module or find a route before gograph_endpoint. NOT TO USE: For a handler's downstream call chain (use gograph_endpoint). RETURNS: gograph.routes.v1 JSON with total, returned, truncated, routes[], and next_cursor when more matches exist.

Find Go structs that declare a mapping to a specific database table via struct tags (e.g., `db:"table_name"`, `gorm:"table:table_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 tracing which Go types represent a database table, or before writing a migration to understand the current ORM model. NOT TO USE: For non-tagged Go structs used as query results (use gograph_fields or gograph_query instead). RETURNS: Matching struct names with package paths and file locations; empty when no structs map to the named table.

Review and grade agent compliance (Plan rule, Review rule, Composability/Efficiency) and tool success rates. Session IDs are strictly validated and only regular repository-confined logs are read. No additional prerequisite once the MCP server is running. WHEN TO USE: After ending a session to obtain compliance metrics and recommendations. RETURNS: Audited session details and grade.

Archive stale and inactive session telemetry without following linked repository paths; never deletes. Each pass moves files into .gograph/_to_delete/<UTC time>_<suffix>/. First ends other callers' CLI-owned sessions idle past the idle limit (GOGRAPH_SESSION_IDLE_LIMIT, default 2h) or MCP-owned sessions whose server process exited on this host (owners without metadata or on another host are kept), listing each, and archives an unselected legacy active_session.json; then archives logs with end records; preserves the selected active log and refuses while any other caller is still live. MCP annotations mark this operation mutating and destructive. No prerequisites. WHEN TO USE: Call after auditing to keep the repository clean. RETURNS: Each ended session, any archived legacy pointer, and the number of session logs moved with the archive folder, or Nothing to archive.

Start a telemetry audit session for tracking agent compliance and tool success metrics. Writes only regular, repository-confined session state under .gograph/sessions and refuses linked storage; MCP annotations mark it mutating and non-idempotent. No prerequisites once the MCP server is running. WHEN TO USE: Call once at the start of a multi-step coding task to track your work. Pass the returned ID as session_id on this caller's later requests. Independent callers may create alongside other active sessions. RETURNS: Message with the caller session ID.

End only the explicitly selected caller session, append its end record, and remove its active marker through repository-confined regular-file operations. MCP annotations mark it mutating and non-idempotent. No additional prerequisite once the MCP server is running. WHEN TO USE: Call once after you have completed all edits and post-edit reviews. NOT TO USE: When no session is active. RETURNS: Message confirming ending of the session.

Emit API signatures with function bodies stripped — struct definitions, interface declarations, and function/method signatures only. Supply file for one exact repository-relative indexed file; omit it for the full repository. Unknown files return an error. 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. WARNING: whole-repository output can be very large. WHEN TO USE: For a file's declarations or a compact map of the entire codebase's shape. NOT TO USE: For full implementations (use gograph_source); for a single package (use gograph_public). RETURNS: Multi-line text of stripped declarations and package names.

Retrieve verbatim Go source for a named function, method, struct, interface, type, variable, or constant, including complete bodies or declarations. 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. Source reads are confined to regular .go files beneath the analyzed repository and reject symlink path components. Read-only; no side effects. WHEN TO USE: When you need a specific implementation or declaration in full without loading a large file — a targeted alternative to reading the whole file. NOT TO USE: For call hierarchy information (use gograph_callers/gograph_callees); for AST metadata without the full source (use gograph_node). RETURNS: Raw Go source blocks with file paths and line numbers. Text and gograph.read.v1 structured content both carry the source or a named refusal: absent symbol, ambiguity with candidates, unsafe/unreadable source, invalid indexed range, or source exceeding 65536 bytes (with its size).

Return one bounded gograph.sql.v1 page of static PostgreSQL query literals with operation, read/write/DDL access, referenced tables, enclosing function, module ownership, and source location. Extraction covers direct literals plus statically resolvable local or same-file package const/var declarations, straight-line assignments, and bounded string concatenations. The MCP server checks freshness before this call and refreshes in the current requested analysis mode. Read-only; no side effects. Filters in different categories AND-compose; repeated values within tables, verbs, and accesses OR-compose. Tests remain included by default for backward compatibility; set no_tests=true for production-only results. CTEs resolve to their actual operation, data-modifying CTEs retain write access/table evidence, PostgreSQL UPSERT remains INSERT, and unsupported classification is explicit rather than guessed. WHEN TO USE: Audit database interactions, write paths, or queries touching a table. NOT TO USE: For ORM struct mappings (use gograph_schema) or runtime-generated SQL that is not a static literal. RETURNS: A deterministic page with total/returned/truncated/next_cursor and queries[].

Check whether the trusted persisted graph index loaded from a regular, repository-confined .gograph/graph.json differs from the current selected-file inventory, effective Go build context, or selected source content digests. Modification times are returned only as diagnostics; legacy indexes without digests temporarily use the former mtime fallback until rebuilt. This tool intentionally does not refresh first; when the artifact is missing, unreadable, unsafe, or uses an unsupported source policy it compares against the startup auto-build fallback. Read-only; no side effects. WHEN TO USE: To decide whether CLI snapshot analysis or precise enrichment needs rebuilding. NOT TO USE: For module dependency freshness; for changed symbols (use gograph_changes). RETURNS: is_stale, graph_age, newest source metadata, changed_files, and build_context_changed.

Report trusted persisted-index health and counts without refreshing source analysis, or startup-fallback health when graph.json is missing, unreadable, unsafe, or uses an unsupported source policy: schema/build timestamps, complete/partial status, ast/precise/precise_fallback analysis status, scanned/parsed/reused/rebuilt-package/failure counts, and graph entity totals. Read-only; no side effects. WHEN TO USE: To validate the snapshot/fallback before relying on its data. NOT TO USE: For a live symbol profile (use gograph_node or gograph_complexity). RETURNS: Structured build health and repository counts.

Search Go string literals in the indexed source files for one or more case-insensitive substrings (OR semantics), returning file, line, the literal, and its enclosing function. Route-shaped terms match any path-parameter spelling (:id, {id}, *id). Source is read through the confined repository reader; unreadable files are named in a warning. The MCP server refreshes source analysis before the call. Read-only; no side effects. WHEN TO USE: To find raw route strings, URLs, SQL fragments, header names, or messages that are not symbols, instead of grep. NOT TO USE: For symbols (use gograph_query) or registered routes with handlers (use gograph_routes). RETURNS: gograph.results.v1 rows of kind string with total/returned/truncated/next_cursor.

Single-call codebase briefing: top 3 hotspots (most-called symbols), worst instability package, highest cyclomatic complexity function, total orphan count, and god-object 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. WHEN TO USE: At the very start of any session — replaces running gograph_hotspot + gograph_coupling + gograph_orphans + gograph_complexity + gograph_godobj separately (5 calls → 1). NOT TO USE: For detailed drill-down into a specific metric (use the dedicated tool after reviewing summary). RETURNS: JSON with symbols, packages, hotspots[], worst_instability, top_complexity, orphan_count, and god_object_count.

Find test functions in *_test.go files that statically exercise a named symbol, or list all attributed test edges when no symbol is given. Direct mode accepts Receiver.Method (including pointer receivers) or a full stable symbol ID. By default this preserves the direct-edge result contract. Set transitive=true with a required symbol to return gograph.tests.v1 reverse attribution, including exact/possible resolution, depth, and a representative stable-ID path from every reaching test; exact_only omits uncertain paths and package disambiguates the selected product symbol. The MCP server checks freshness before this call and refreshes in the current requested analysis mode. Read-only; no side effects. WHEN TO USE: Before editing a function — use transitive=true for router/callback-mediated coverage and direct mode for concrete test call sites. NOT TO USE: For test helper infrastructure (use gograph_fixtures); for running tests or proving runtime coverage. RETURNS: Direct result rows by default, or a versioned reverse-transitive report when requested.

Alias for gograph_errorflow. Refreshes in-memory source analysis, then traces an error string heuristically from its definition up through the call chain to HTTP handlers. Read-only; no side effects. WHEN TO USE: Prefer gograph_errorflow; this alias exists for compatibility. RETURNS: The same structured output as gograph_errorflow.

Sweep the full graph in one pass and return called production functions and methods without an exact transitive static path from any test. The MCP server checks freshness first. Precise direct calls and proof-backed concrete interface receivers are exact; open CHA or parser-only paths propagate possible to descendants, which remain visible with test_resolution=possible and possible_test_count. Repeatable CLI --exclude globs map to the MCP exclude string array and match repository-relative source paths lexically. This is static attribution, not runtime coverage proof. Read-only; no side effects. WHEN TO USE: During test census or pre-release hardening; it replaces N forward coverage or direct gograph_tests probes. NOT TO USE: For running tests or proving branch execution. RETURNS: JSON rows sorted by caller_count with stable_id, name, kind, file, line, caller_count, package, test_resolution, and optional possible_test_count.

Find every place a named Go type appears in function parameter lists, return type signatures, struct field or interface method declarations, and composite-literal construction. 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 changing an interface or type definition — see the consumption and construction blast radius. NOT TO USE: For call sites of a function (use gograph_callers); use gograph_literals when only struct Foo{...} initialization sites are needed; for all transitive callers use gograph_impact. Also answers struct fields: 'Type.Field', 'pkg.Type.Field', or a bare field name returns the declaration plus every field_read, field_write, field_address, and field_literal site, attributed to the declaring struct so promoted fields resolve; typed rows come from precise builds of production packages, while AST graphs return labelled name-only possible_field_use rows. RETURNS: File paths and line locations where the type or field appears; empty when the type is not referenced.

Generate the llm-wiki/ directory of machine-first markdown pages from the static graph. Pages produced: overview.md, architecture.md, hotspots.md, routes.md, env.md, errors.md, concurrency.md, api-surface.md, and one packages/<name>.md per internal 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. A relative output is anchored beneath the graph root and rejects linked components; an absolute output explicitly selects a local destination whose final directory must be real. Generated page paths and regular-file writes remain confined beneath the selected output root. Writes may overwrite existing regular files; MCP annotations mark it mutating and destructive. WHEN TO USE: At the start of an agent session on an unfamiliar codebase — run once to get a token-efficient orientation without issuing dozens of individual tool calls. NOT TO USE: For targeted symbol lookups (use gograph_context or gograph_source). RETURNS: JSON manifest of written page filenames and a count; error when the graph cannot be loaded or the output directory is unsafe or cannot be created.