Skip to main content
Glama

gograph

Symbol queries accept path/to/file.go:Name, including path/to/file.go:Receiver.Method, or an import-qualified file path when a short name is ambiguous. file.go:Name never matches a method; methods need file.go:Receiver.Method. source prints exact selectors for ambiguous matches, and every printed selector resolves to exactly one declaration. Supported declaration tools and named exceptions are listed in the selector contract. Queries include struct fields; query --no-tests excludes test-file rows. Precise mutation queries recover the type of fields assigned on returned values. Routes retain constant and unresolved path registrations; precise builds resolve constants across packages, including net/http method patterns. tests --transitive --files-only prints unique file paths, matching the files in the MCP transitive report.

Graph-state output and capabilities expose freshness_context: CLI freshness checks use the querying process's Go context, including GOFLAGS; MCP uses its startup context and explicit tags. A context mismatch remains stale, even when source bytes have not changed. No environment values are printed. Precise indexes include package-level constant references in usages and query, including comparisons, switch cases, composite values, and function arguments. Typed enum-like constants retain their declaration identity; local shadows are excluded. query labels these reference sites as usage rows. AST-only graphs do not claim type-resolved constant usages. review uses the same test attribution as context. Rebuild after upgrading.

review --uncommitted includes deleted declarations from changes --git HEAD and explicitly leaves historical callers, tests and risk unevaluated. Other current-graph traversal commands retain their deletion refusal. Builds explain when an enclosing Git repository ignores the requested directory.

Uncommitted plan/review skip blank-identifier declarations such as var _ I = (*T)(nil) during symbol traversal. Review keeps their declaration evidence and names the limit; changes --git HEAD still lists them.

Session audits list invocation errors separately from operational failures and exclude them from compliance scoring. Composability measures the mix of composed and raw query commands; it does not measure answer correctness or token savings.

Go Report Card License: MIT Go Version Homebrew Docs

Give Go coding agents a compiler-aware map for safer refactors.

gograph builds a local structural graph of your Go repository, with optional type-checked CHA/SSA enrichment. Its CLI and MCP workflows help coding agents trace callers and interface implementations, plan change impact, and enforce architecture without embeddings or a hosted code index.

Explore the interactive no-install demo · Review the reproducible benchmark

See CLI/MCP query contracts for bounded result pages, snapshot-bound cursors, exact/possible impact, and change-evaluation status.

Companion projects: Scrinium provides repository-owned, evidence-backed knowledge for coding agents, while Rulefloor protects repository-local invariants by binding them to concrete tests and detecting drift. They are independent, optional tools: Scrinium can keep Gograph structural observations and Rulefloor validation results as separate evidence without treating either as proof of unrelated behavior or global project correctness.

Gograph Demo

Static analysis; no target-code execution. Default indexing parses Go source locally and does not call application services. Linked directories and linked/special files for extensions recognized by go/build are excluded; unrelated regular-file or dangling links with non-Go extensions are not Go tool inputs and do not block precise analysis. Graph-directed source reads remain confined to regular files beneath the analyzed repository, and linked/non-regular Go tool metadata (go.mod, go.sum, go.work, go.work.sum, and vendor/modules.txt) is rejected before toolchain invocation; an explicitly symlinked repository root remains supported. Applicable go.work use members may be sibling modules beneath the nearest real Git checkout; without that boundary they remain confined beneath the workspace directory. Each member directory, go.mod, and optional go.sum is validated before cmd/go starts. Gograph also reads project metadata such as .gitignore, graph/config JSON, and Git state. Indexing asks the installed Go toolchain for the effective build/module context; precise mode additionally performs package type loading, and doc runs go doc. Those operations follow your configured module/cache/network policy. Before repository package loading or go doc, applicable local module/workspace source trees are preflighted for links that cmd/go may inspect; .git and .gograph subtrees are excluded. Session telemetry is local under .gograph/sessions/; nothing is sent to gograph services.

Quick Start

# Install
brew install --cask ozgurcd/tap/gograph
# or: go install github.com/ozgurcd/gograph/cmd/gograph@latest

# Confirm which installation will run and detect PATH shadowing
gograph doctor --json

# Build a type-enriched precise graph, then verify it
gograph build . --precise
gograph stats

# Optional CI contract: fail when precise enrichment falls back
gograph build . --precise --strict

# Optional: prioritize lower heap use on constrained hosts
gograph build . --precise --memory-mode=low --max-memory=1GiB

# Optional: include integration-tagged files and tests in this graph
gograph build . --precise --tags=integration

# Optional: omit unrelated broken package directories
gograph build . --precise --strict --exclude-dirs=legacy,examples/broken

# Start with repository-wide results that require no guessed symbol
gograph summary
gograph hotspot --top 5
gograph flow --no-tests

Homebrew and go install install the normal gograph CLI. MCP clients that support MCP Bundles can instead discover the local stdio server in the official MCP Registry as io.github.ozgurcd/gograph. Registry/MCPB installation is a separate distribution path; it does not install the Homebrew cask or configure the Claude Code marketplace plugin. The Registry is currently in preview. See Official MCP Registry and MCPB installation for client support, target selection, and current limitations.

Choose a real function or method shown by summary, hotspot, or gograph complexity, then substitute its name below:

gograph explore "YourSymbol" --compact # low-token discovery, identity/role, and complete evidence counts
gograph explore "YourSymbol"           # standard source + callers/callees + tests + exact identity impact
gograph explore "YourSymbol" --deep    # standard response + depth-3 exact evidence, package context, explanation
gograph context "YourSymbol" # source + callers + callees + tests

# For compilable repositories, enrich the graph before a major refactor
gograph build . --precise
gograph plan "YourSymbol"

Build artifacts are written under the target .gograph/ directory. gograph adds .gograph/ to the enclosing Git repository root .gitignore when available, falls back to the build target .gitignore outside Git, and exits without replacing artifacts if no Go files are found or no source file parses successfully. The update accepts only an absent or regular .gitignore; a repository-provided link is refused and its target is not modified. Go build constraints, explicit comma-separated --tags (or inherited GOFLAGS when the flag is absent), cmd/go package-directory rules, generated sources, module-mode ignore directives, and Git ignores use the same scanner policy for building, freshness checks, and change detection. Linked .go files, linked directories, and other non-regular recognized Go inputs are reported and excluded. Unrelated regular-file and dangling links with non-Go extensions (for example YAML configuration or TSV fixtures) are ignored by Go-tool preflight; linked/non-regular go.mod, go.sum, go.work, go.work.sum, and vendor/modules.txt entries are rejected before gograph or the Go toolchain reads them. Applicable go.work use members may be sibling modules beneath the nearest real Git checkout. Non-Git layouts retain workspace-directory confinement, nested Git boundaries are not crossed, and every member directory, go.mod, and optional go.sum is validated before cmd/go starts. .gograph itself must be a real directory, and graph.json must be a regular repository-confined file. Graphs with a missing or unsupported confinement policy marker must be rebuilt with the current binary before graph-backed commands use them. Older binaries do not enforce this boundary and should not be used to analyze untrusted repositories.

Each indexed source file stores a SHA-256 content digest. Rebuilds reparse all selected files in a changed package together and reuse parser records for unchanged packages; stats reports reused_files and rebuilt_packages. Precise builds reuse that AST work but still recompute repository-wide type/CHA/SSA enrichment so cross-package dispatch remains correct.

Low-memory mode preserves those graph semantics while using more aggressive garbage collection, reclaiming memory between production and test analysis, and avoiding a full JSON copy of the AST graph. --max-memory accepts integer byte sizes such as 1GB or 1GiB and requires --memory-mode=low. It is a soft Go-runtime memory target—not a hard RSS cap—so memory-mapped files, the executable, and Go toolchain subprocesses can make process memory exceed the requested value. Aggressive GC can increase CPU time, and a target that is too low may make the build much slower or fail; Gograph never silently reduces precision to meet it.

Precise fallback continues to exit zero by default for compatibility and is recorded in graph metadata. Add --strict with --precise when fallback must fail CI; Gograph still publishes or retains the diagnostic artifact before returning non-zero.

For precise builds blocked by unrelated directories, see directory exclusions. Use the same --exclude-dirs selection on gograph mcp startup; imported dependencies must still type-check. For symlinked skills, v1.7.2 supports --exclude-dirs=.claude/skills: directory links beneath that real directory are hidden from Go loading, without following their targets. Linked Go inputs and metadata remain protected. See the Codex MCP setup guide for registration and verification.

Related MCP server: Context Zero Engine

Machine-readable structural validation

External consumers can validate one closed structural predicate without parsing human CLI output:

gograph version --json
gograph validate --repo /work/project --binding-json '{"schema_version":"gograph.binding.v1","predicate":"symbol_exists","subject":{"language":"go","kind":"symbol","id":"example.com/project/internal/auth::Authorize"},"required_precision":"ast"}' --json

The version and result schemas are gograph.version.v1 and gograph.validation.v1; bindings use gograph.binding.v1. V1 supports symbol_exists, package_imports, call_edge_exists, type_implements, and the policy predicates imports_only_from, callers_only_from and call_arg_constant, which report every violating file:line. Validation is read-only and never builds or refreshes the graph. Exit 0 means pass, exit 1 means a conclusively evaluated fail, and exit 2 means cannot_evaluate or an invalid request.

Negative results require predicate-specific completeness: symbol and direct import absence need a current complete AST graph; implementation absence needs a current precise-complete graph; call absence additionally requires complete resolution of the subject's relevant call edges. Missing, stale, partial, ambiguous, or unresolved evidence degrades to cannot_evaluate; a precise_fallback graph may support AST presence but never evaluated absence. The result binds the exact graph bytes, selected source/build-context manifest, and canonical binding with SHA-256 fingerprints.

Gograph validates selected-build-context Go structure. It does not prove runtime behavior or business correctness. CHA edges are possible static targets, not runtime dispatch certainty. V1 excludes reachability, unstable or external symbol identities, unnamed types, and non-Go languages. See the exact machine-validation contract. Applicable local module/workspace source roots must remain beneath the explicit --repo root; v1 returns cannot_evaluate instead of widening that authority.

MCP refreshes stay in memory by default. To publish each successful refresh for CLI consumers and later server processes, start the server explicitly with:

gograph mcp . --persist-refresh
# Keep MCP startup and every later refresh on the integration-tagged selection:
gograph mcp . --tags=integration
# Optional low-memory policy for startup analysis and later refreshes:
gograph mcp . --memory-mode=low --max-memory=1GiB

This opt-in mode writes or overwrites .gograph/graph.json and the nine Markdown reports after a confirmed-fresh refresh. It does not modify .gitignore, so ignore .gograph/ yourself before enabling it when needed. The directory holds only the latest published state; it is not a per-branch cache. If no usable graph exists (including an unsafe or unsupported artifact), the startup auto-build is published before serving; a failure there prevents startup. A later tool-triggered publication failure makes that tool return an error, and the server retries the pending publication on another refresh-capable call without rebuilding the already-fresh in-memory graph. Writers coordinate through a local .gograph/.artifacts.lock file; an existing lock entry must be regular rather than a link or special file. Reports are replaced first and graph.json is replaced last as the publication commit marker; the complete ten-file bundle is not a single atomic filesystem transaction. Same-directory replacement is atomic on Unix-like systems; Go does not guarantee atomic rename semantics on non-Unix platforms. The lock file remains as operational coordination state in addition to the ten outputs.

Persisted graphs are bound to their effective Go environment and build selection. Start MCP with the same GOWORK, GOFLAGS, and --tags context used to build the graph; a mismatch is stale and must refresh successfully or return a diagnostic rather than silently serving incompatible facts. gograph doctor --json reports that repository diagnostic.

Why gograph?

Illustrative point-in-time output comparison from an earlier gograph revision (counts vary as the repository evolves; these commands return different kinds of evidence):

Task

grep -rn

gograph

Observed output difference

Find callers of loadGraph

158 matching lines (comments, docs, vars)

56 AST-derived call-site rows

~65% fewer rows in that run

Locate symbol definitions

842 lines matching "Symbol"

83 true type/method declarations

~90% noise eliminated

Read one function body

cat displays 180+ lines of the whole file

source extracts the 12-line function

~93% fewer source lines in that run

Gather common symbol context

Separate node, source, caller, callee, and test queries

context bundles those fields

Five evidence types in one response

Key Features

Machine and Agent Workflows — explore provides bounded first-call discovery with ranked lexical matches, explicit symbol selection, source, callers, callees, tests, and exact identity-resolved impact; focused callers, callees, broader impact, reverse test coverage, stable identity, plan, review, flow, validation, and policy commands remain available. The MCP server registers 70 endpoints including four session lifecycle tools. Full command reference →

Federated Workspaces — model multiple checked-out repositories through independently fingerprinted repository graphs plus a small deterministic cross-repository overlay. Resolution scopes support alternative fleets such as OSS/CE without merging repository ownership. P0 resolves Go modules, ordinary cross-repository Go calls, and first-class HTTP contracts for workspace-wide status, query, path, and impact analysis. The four read-only workspace MCP tools return the same native result values as CLI --json; member refresh and overlay publication remain explicit CLI mutations. Workspace guide →

Native MCP Server — all 66 repository query, analysis, and workflow capabilities have project-MCP equivalents for Claude, Cursor, Copilot, and other MCP clients; four additional endpoints cover session lifecycle (70 project tools total). A separate workspace server provides status, query, path, and impact with the same native results as the corresponding CLI operations. The normal mapping is CLI <command> to MCP gograph_<command>; contract, boundaries --create, and session actions use the documented special mappings. CLI-only process/host/artifact operations are build, validate, doctor, gate, snapshot, plugin/hook installation, project/workspace MCP startup, workspace build/member refresh, and help. The standalone version command has no MCP tool, but gograph_capabilities reports the running server version. Transport presentation differs where appropriate, but paired operations share functional semantics. Complete CLI/MCP matrix →

Explicit Freshness Model — CLI graph-backed analysis reads the last trusted persisted graph. Its JSON envelope includes gograph.graph-state.v1, separating source (persisted/in_memory), freshness (current/stale), completeness (complete/partial), precision (ast/precise/fallback), refresh outcome, and persistence outcome; bounded diagnostics remain on the operation that produced them. Text stats and stale report the same persisted state. gograph stale compares selected source content digests plus the effective build/module fingerprint; mtimes are diagnostic only for current indexes. It is a tri-state predicate: exit 0 means current, 2 means stale, and 1 means an operational or JSON serialization error; a missing or unsupported source-policy marker is an explicit status-1 rebuild requirement. MCP source-analysis tools check the same freshness per call, adopt a newer persisted precise graph, and incrementally rebuild changed package ASTs in memory using the latest requested analysis mode. Refresh-backed tools return their answer once, as compact JSON text without structuredContent, and attach _meta.gograph_graph_state; a stale or degraded graph is also named in the text. Failed precise enrichment can serve a clearly marked current in-memory fallback, while an ordinary refresh failure can serve the last trusted stale graph; neither degraded result is silently published, and a mismatched effective Go environment still fails closed. MCP stale, default changes, and stats inspect the trusted persisted snapshot, or the startup auto-build fallback when no usable artifact exists. With --persist-refresh, that snapshot advances after a successful refresh; publication failures leave the fresh in-memory graph usable and explicitly report persistence.outcome=failed with a persistence diagnostic for retry.

Compact Composite Workflows — explore, context, plan, and explain combine source and graph evidence that would otherwise require several separate queries. explore is additive: specialized commands remain the complete, stable interfaces for focused analysis. Actual tool-call and token savings depend on the repository and task.

Narrow by Design — never runs target repository binaries or tests and does not intentionally scan .env, key, certificate, or credential files. Linked directories and linked/special recognized Go build inputs are excluded; unrelated non-Go regular-file links are outside Go-tool preflight. On-demand source and snippet reads use a repository-rooted filesystem handle and accept only regular .go files without symlink components. Linked/non-regular Go module/workspace metadata, sums, and vendor/modules.txt are rejected before toolchain use. Applicable go.work members may be siblings inside the nearest real Git checkout and otherwise stay beneath the workspace directory; their directories plus module metadata are preflighted before cmd/go. Default/relative policy configs are project-confined; documented absolute config/output arguments are explicit operator-selected local locations. AI worktree directories (.claude/, .cursor/, .agents/) are excluded. The installed Go toolchain resolves effective build context during indexing; precise repository package loading and external go doc run only after a preflight that rejects source-tree links cmd/go may inspect across the selected root plus its effective module root, or the workspace root and member trees, excluding .git and .gograph. Dependency and toolchain resolution remain open-world under the user's Go environment.

Architecture Enforcement — boundary rules, API drift detection, complexity gates, dead code sweeps, god-object detection, coupling analysis. Run in CI with gograph gate.

Security Flow Analysis — flow follows potential HTTP request, decoded JSON, and environment data across assignments and function calls to SQL query text, process execution, filesystem paths, and outbound HTTP targets. Findings include severity, confidence, and source-to-sink path steps; MCP exposes the same analysis as gograph_flow.

Integrity-Aware Indexing — publication refuses a linked or non-directory .gograph; graph.json is staged and replaced last only after a successful parse (the same-directory rename is atomic on Unix-like systems), records complete/partial build health and ast/precise/precise_fallback analysis status, and exposes both through gograph stats. gate refuses to evaluate a stale graph.

Agent Compliance Auditing — session telemetry tracks whether agents run plan before edits and review after. Grades agent behavior A–F with actionable recommendations.

Audit sessions belong to an explicit caller. gograph session create task prints the session ID; pass it on subsequent CLI commands with --session-id ID or GOGRAPH_SESSION=ID. The flag overrides the environment. Selected analytical commands retain the --intention requirement and existing audit grades. Agent shells usually do not keep GOGRAPH_SESSION between commands, so a CLI command without a selector uses the repository's only active session when this host's CLI created it; that covers build, plan, review, and session end. When several sessions are active, or the only one is MCP-owned, from another host, or lacks owner metadata, nothing is adopted: read-only commands then require no intention and never write to another caller's audit. gograph session end ID ends a named session. A session its job forgot cannot block later jobs: every CLI command and MCP call first ends other callers' abandoned sessions, meaning CLI sessions with no activity for GOGRAPH_SESSION_IDLE_LIMIT (a Go duration, default 2h; 0 or off disables) and sessions of MCP servers that have exited on this host. It prints each one it ends on stderr. Refused calls do not count as activity, and a call's own selected session is never ended. The forgotten owner's next call reports that its session was ended as abandoned. Independent callers may create separate sessions concurrently. Repository writes and session end/cleanup refuse while another caller owns an active session, naming that session. Ending an owned session remains possible while other owners are active. Unset GOGRAPH_SESSION after ending it.

MCP tools accept session_id and intention per request. Use the ID returned by gograph_session_create; analytical owner calls require a rationale. The server does not inherit GOGRAPH_SESSION, so sharing one MCP process does not merge callers. Default in-memory refresh remains read-only; --persist-refresh calls are guarded as writes. Session IDs are cooperative attribution selectors, not credentials or an OS-user security boundary. Older active sessions can be selected explicitly by their existing ID. See the session design.

Command Reference

Query and composed-analysis commands support --json; version --json and validate ... --json use their dedicated machine schemas. The exact --files-only surface is listed in the command reference. Operational commands such as build, wiki, gate, snapshot, installation, and help use text output; doctor and workspace build/status/query/path/impact also accept --json, and session audit additionally supports raw JSON. CLI --mermaid renders callers, callees, impact, endpoint, dependents, deps, path, and coupling as fenced Mermaid. Their MCP equivalents accept mermaid=true and return the same Markdown-fenced Mermaid text; without it, each tool retains its normal response format.

Category

Commands

What it does

Indexing

build . [--precise] [--strict] [--memory-mode=low] [--max-memory=1GiB], stale, stats

Parse AST, optionally require precise success or prioritize lower heap use, write graph, check freshness and health.

Machine Validation

version --json, validate --repo PATH --binding-json JSON --json, whatsnew [--since vX.Y.Z] [--json]

Versioned exact structural and policy predicates with tri-state outcomes; release notes for the running binary.

Navigation

query, callers [--depth N], callees [--depth N], path, source, node

Find symbols, trace call chains, extract source.

Context

context, explain, focus, endpoint

Bundled structural data in one call. Token savers.

Change Analysis

plan, review, risk, impact [--uncommitted|--since], changes [--git], api --since

Pre-edit planning, post-edit review, risk analysis, blast radius, drift.

Architecture

boundaries, coupling, complexity [--no-tests] [--top N] [--path DIR], godobj, orphans, arity

Quality gates, dead code, coupling, god objects. Policies live in the committable gograph/ directory (.gograph/ still read).

Types & Structs

fields, implementers [--test-only], interfaces, embeds, constructors, literals, usages, mutate, schema

Struct fields, interface satisfaction, type usage.

Infrastructure

routes [term] [--module MODULE] [--include-tests] [--limit N] [--cursor CURSOR], sql [term] [--table T] [--verb V] [--access read|write|ddl] [--function F] [--module M] [--no-tests] [--limit N] [--cursor C], envs, errors, concurrency, globals, httpcalls, deps [--transitive], dependents, imports

Bounded CLI/MCP route and PostgreSQL static SQL pages with cursor continuation, module selectors, explicit test controls, and structured filtering; plus env vars, concurrency, outbound HTTP calls, and imports.

Security

flow [term] [--source kind] [--sink kind] [--config path] [--no-tests] [--package path]... [--max-work N] [--context-depth N]

Potential untrusted-data paths to SQL, process, filesystem, and outbound HTTP sinks, plus policy-defined sources, sinks and argument sanitizers; constant non-shell programs are parameter_only.

Testing

tests [symbol] [--transitive] [--exact-only] [--package name] [--max-depth N] [--limit N] [--cursor T], tests --uncommitted, tests --since <ref>, tests <symbol> --format go-test, coverage <TestFunc> [--exact-only] [--package name], untested [--pkg name] [--top N] [--exclude glob] [--wide] [--exclude-interface-methods] [--coverprofile file], uncovered --uncommitted|--since <ref> --coverprofile file, fixtures, mocks

Direct and transitive reverse exact/possible static test attribution, runnable per-package go test -run selection for a change, one-sweep gap census, runtime coverage gaps and unexecuted changed lines, full stable-ID output, helpers, mock implementations.

Error Tracing

errorflow [--no-tests], trace

Reverse-BFS from error strings to HTTP entry points.

Diagnostics

doctor [--json], hotspot, returnusage, skeleton, diagram, changes, public

Install/PATH plus current graph freshness/capability diagnostics, hotspots, return usage, API signatures, Mermaid diagrams.

CI/CD

check [--since|--uncommitted], gate, snapshot save|diff|list|drop

Policy checks, threshold enforcement, metric snapshots.

Telemetry

session create|end|audit|cleanup

Agent compliance tracking and grading (A–F).

LLM-Wiki

wiki [--output dir]

Generate llm-wiki/ and prune obsolete generator-owned package pages while preserving custom pages and packages/README.md.

Summary

summary [--json]

Single-call codebase briefing: top 3 hotspots, worst instability package, highest complexity function, orphan count, god-object count. Replaces 5 separate calls.

Stable IDs

identity <symbol-or-stable-id> [--package name] [--json]

Print and re-resolve module/package/receiver/name identity that survives line shifts and file moves inside a package; package disambiguates external-test collisions.

Reverse Attribution

coverage <TestFunc> [--exact-only] [--package name] [--json]

Transitive product-symbol set for one unambiguous test, with stable-ID paths and exact/possible propagation. Static evidence only—not runtime or branch coverage.

Tests reaching a symbol

tests <symbol> --transitive [--exact-only] [--package name] [--max-depth N] [--limit N] [--cursor T] [--json]

Versioned reverse attribution: a summary by depth and resolution, then 50 tests per page nearest first, each with a representative stable-ID path to one product symbol. Default tests remains direct for compatibility.

Tests to run

tests --uncommitted|--since <ref> [--format run|go-test] [--max-depth N] [--exact-only], tests <symbol> --format go-test

Which tests to run for a change: per package, anchored -run patterns and ready go test commands with the graph's -tags; unselectable declarations are listed, never dropped.

Untested

untested [--pkg name] [--top N] [--exclude glob] [--wide] [--exclude-interface-methods] [--coverprofile file] [--json]

Called production symbols without an exact transitive test path, none before possible. Precise builds devirtualize only proven concrete receivers; open interface paths remain test_resolution=possible. --exclude-interface-methods skips Error/String-style methods; --coverprofile lists functions a go test -coverprofile run never executed. JSON includes stable_id; --wide prints it without truncation.

Uncovered changes

uncovered --uncommitted|--since <ref> --coverprofile file [--json]

Changed lines of non-test Go files that a coverage profile shows were never executed, as exact ranges.

Doc

doc <pkg[.Symbol]> [--json]

go doc wrapper — signature + doc comment for any stdlib or third-party symbol. No graph required. Closes the gap when call chains leave the project.

Precise implementers results merge type-checked production types with AST-discovered test-file fakes; --test-only/MCP test_only=true returns only the latter. Direct tests lookup accepts Receiver.Method (including pointer receivers) or a stable ID. usages covers signature/field/interface references and Foo{...} construction. Precise indexes also include package variables and constants referenced in expressions; literals remains the focused construction-only view.

SQL extraction includes direct literals and statically resolvable local or same-file package const/var declarations, straight-line assignments, and bounded string concatenations. Runtime-generated SQL remains excluded. Route and SQL JSON are paged row censuses; --files-only follows all pages but emits a complete deduplicated file census, not every row.

Full command reference with examples: gograph.identuum.ai/docs/command-reference

Define boundaries in the committable gograph/boundaries.json (.gograph/boundaries.json, which gograph git-ignores, is still read when no committed file exists):

{
  "layers": [
    { "name": "domain", "packages": ["internal/domain/**"], "may_import": [] },
    { "name": "handler", "packages": ["internal/handler/**"], "may_import": ["internal/service/**", "internal/domain/**"] }
  ]
}

Run gograph stale (and rebuild when stale) before gograph boundaries; the CLI evaluates the persisted graph and exits with code 1 on violation. The default policy is gograph/boundaries.json, else .gograph/boundaries.json; use --config PATH for another regular, repository-confined policy. MCP uses the same evaluation after its normal source refresh. Works in CI/CD.

gograph flow includes test files by default; add --no-tests for production-only results. It automatically reads gograph/flow.json (else .gograph/flow.json) when present, or accepts --config <path> for another JSON file inside the graph root. Sanitizers apply to a function's return value and can be scoped to selected sink kinds:

{
  "sanitizers": [
    { "function": "security.CleanPath", "for": ["filesystem"] },
    { "function": "security.ValidateURL", "for": ["outbound_http"] }
  ]
}

Omit for to trust the return value for every sink kind. function accepts the call spelling or a fully-qualified symbol ID; use the fully-qualified form when names collide. A validator that returns only bool or error does not sanitize the original input; wrap validation in a function that returns the trusted value if that is the intended policy.

AI Agent Integration

Official MCP Registry (preview): MCPB-capable clients can discover io.github.ozgurcd/gograph. The bundle asks for the root directory of the Go project and launches the bundled executable with separate arguments equivalent to gograph mcp <project-directory>. Releases provide macOS, Linux, and Windows bundles for both amd64 and arm64. The current Registry package schema cannot select by CPU architecture, so choose the asset whose filename matches the host; do not assume a client will select it automatically. All analysis still runs locally over stdio, with no hosted gograph service or remote telemetry.

The Registry bundle and installer-generated MCP registrations intentionally omit --persist-refresh, keeping disk publication off by default. Use a custom local MCP command if you explicitly want that behavior.

Desktop config, shared rules, and Claude Code hook setup:

gograph add-claude-plugin

This registers the Claude Desktop MCP server, injects shared CLAUDE.md steering rules, and installs a Claude Code PreToolUse hook. The hook redirects Go-symbol searches only when an effective search target belongs to a repository with a .gograph index, so unindexed folders in multi-root workspaces remain unaffected. For Claude Code MCP registration, also run the command printed by the installer: claude mcp add gograph -- gograph mcp .. The installer exits non-zero when any installation step fails.

Alternative — install via Claude Code plugin marketplace:

/plugin marketplace add ozgurcd/gograph
/plugin install gograph@gograph

Discovers gograph through Claude Code's plugin marketplace and ships a SKILL.md that auto-activates on Go work, teaching the agent the workflow (doctor --json → capabilities → stats → plan → context → edit → review), when a durable precise CLI build is useful, when to use structural queries, and when to verify with gopls or targeted text/source search.

You still need the gograph binary installed (brew install --cask ozgurcd/tap/gograph or go install github.com/ozgurcd/gograph/cmd/gograph@latest). Use gograph add-claude-plugin for Claude Desktop MCP wiring plus shared rules and the Claude Code hook; register the Claude Code MCP server with the printed claude mcp add command. Use the plugin marketplace when you prefer discovery from Claude Code's plugin UI.

Other agents (Cursor, Copilot, Antigravity, etc.):

gograph mcp .                     # stdio server; refreshes stay in memory
gograph mcp . --persist-refresh   # opt in to publishing refreshed artifacts
gograph mcp . --tags=integration  # retain the same tagged context on every refresh
gograph mcp . --memory-mode=low --max-memory=1GiB  # same low-memory refresh policy as CLI builds

Add to your .cursorrules or AI system prompt:

Before answering architecture or repository questions, inspect the available gograph_* MCP tools and run gograph capabilities. Prefer gograph for supported structural queries; use gopls or targeted source/text search when results are ambiguous, precision fell back, or a known source call is missing.

Query and composed-analysis commands support --json for machine-readable output:

gograph callers "YourSymbol" --json
# → {"schema_version": "1", "command": "callers", "status": "ok", "count": 2, "results": [...]}

For full integration guides, see docs/coding-agent-usage.md.

Zero-cost orientation with llm-wiki/: Run gograph wiki once per session to generate a directory of machine-first markdown pages — overview, architecture diagram, hotspots, routes, env vars, error sites, concurrency, per-package docs, and the full API surface. Agents read these pages instead of issuing dozens of individual tool calls:

gograph build . --precise
gograph wiki                 # writes to ./llm-wiki/
# generated orientation starts at: llm-wiki/overview.md
# if maintained governance pages exist, read:
# llm-wiki/index.md → project.md → agent-rules.md → agent-contract.md

Add generated wiki output to .gitignore when it is disposable. Do not overwrite a repository's maintained or Scrinium-protected agent-rules.md; propose governed changes through that repository's documented workflow. Regeneration removes only obsolete package pages that match Gograph's generated signature; custom package pages and packages/README.md are preserved.

Example Output

When you run gograph build ., the generated GRAPH_REPORT.md gives your AI a condensed context map:

External Dependencies (Tech Stack)

Module

Version

github.com/gin-gonic/gin

v1.9.1

github.com/jackc/pgx/v5

v5.5.5

Important Symbols (Top by outgoing calls)

Symbol

Kind

File

Line

Calls out

(Server).Start

method

server.go

42

18

ValidateAuth

function

auth.go

12

14


How does gograph complement gopls?

gopls is the Go project's compiler-backed language server. It provides live workspace diagnostics, navigation, references, implementations, refactoring support, and an experimental MCP server. It should remain the first choice for editor and compiler-aware workspace operations.

gograph adds a different layer for repository and agent workflows:

  1. Persisted snapshots — CLI analysis can inspect a stable graph artifact, while MCP refreshes source-analysis state and preserves the requested precision mode.

  2. Repository-level analyses — change impact, reachability, routes, SQL, environment reads, security-flow candidates, coupling, and policy gates are represented together.

  3. Composed responses — context, plan, review, and summary package related evidence for agent workflows rather than exposing only one language operation at a time.

Use gopls for live compiler-backed navigation and refactoring, rg for text and non-Go searches, and gograph when a persisted repository graph or composed change-analysis workflow is useful. See the benchmark guidance for how to measure these different workflows without assuming one tool is a drop-in replacement for another.

  • Default mode uses Go AST parsing and best-effort heuristics. Tolerates incomplete or non-compiling repositories.

  • Repository source boundary excludes linked directories plus linked/special recognized Go build inputs before build selection, while unrelated regular-file or dangling non-Go links do not block precision. It supplies confined bytes to the AST parser and confines later source, caller/callee snippet, complexity, and changed-file reads to regular repository files. Linked/non-regular go.mod, go.sum, go.work, go.work.sum, and vendor/modules.txt metadata is rejected before gograph or the Go toolchain reads it. Applicable go.work use paths may select sibling modules beneath the nearest real Git checkout; without one they remain beneath their workspace directory. Nested Git boundaries are not crossed, and member directories, go.mod, and optional go.sum are validated before cmd/go. Precise loading and doc preflight the selected root plus its effective module root, or the workspace root and every member tree; .git and .gograph are excluded from that source-tree walk. Persisted graph.json is also read through this boundary, .gograph must be a real directory, and an explicitly symlinked repository root is allowed. Missing or unsupported source-policy markers and artifacts larger than 512 MiB are rebuild-required, and serialized graph roots are never trusted. Saved baseline graphs must be regular non-linked files inside the selected project with the exact marker and size bound. Default/relative check and flow configs, boundaries, gate config, and repository-controlled session/snapshot/wiki mutations reject linked path components; documented absolute config/wiki locations are explicit operator selections. Use the current binary for untrusted repositories.

  • Precise mode attempts type-checked production enrichment and needs compilable, build-selected packages for CHA/SSA results. SSA bodies are built for selected repository packages, not the full transitive dependency closure; imported types and local external-call references remain available without dependency-body call graphs or their source-less wrapper noise. If enrichment fails or omits an indexed non-test source file, the command warns, publishes the AST graph, and records precise_fallback; if a fresh successful precise artifact already covers the same sources, a failed retry keeps that artifact instead. Default fallback remains exit zero for compatibility; --strict requires --precise and returns non-zero after publication or retention. Successful and AST-only builds record precise and ast respectively. Test packages are loaded in a separate non-fatal typed pass: broken tests yield typed_partial test-call attribution without downgrading successful production precision. Typed-only test targets are recomputed rather than reused as parser facts, preventing edge multiplication across unchanged precise builds.

  • Low-memory mode changes execution policy, not analysis meaning. It uses aggressive GC, releases completed production type/SSA state before typed-test loading, and honors an optional soft Go runtime memory target. The target is neither an RSS ceiling nor a guarantee that all repositories can complete within that amount; Gograph reports fallback/failure normally rather than silently omitting precise facts.

  • A precise interface invocation whose SSA receiver is proven to contain one concrete dynamic type is devirtualized to one exact ordinary call. Otherwise it is represented by one call edge per valid named in-repository CHA target. A single visible implementation is never treated as proof. callers Interface.Method (including inherited and promoted methods) expands through recorded implementers and deduplicates shared source expressions. Compiler-generated promoted-method forwarding remains traversal-only.

  • Open CHA dispatch is conservative rather than points-to precise: it may retain implementations that cannot occur in one runtime configuration. Reflection, unsafe, plugins, unresolved function values, test-only implementations, unnamed concrete types, and module-external implementations can still be incomplete. Precise test attribution also proves single-assignment, non-escaping concrete interface locals; other interface targets remain explicitly possible, and typed_partial means some tests stayed on parser heuristics.

  • Callback references are retained only when they resolve to repository callables, and exact call edges are deduplicated before serialization.

  • Mutation queries ignore ordinary local assignments and retain owning type information when statically known, so Type.Field disambiguates same-named fields.

  • Synchronization extraction requires a receiver tied to a known sync type. Error messages come from panic, errors.New, and fmt.Errorf, including import aliases.

  • Heuristic extractors (routes, SQL, parser-only tests, and error mapping) are navigation aids, not authoritative program analysis. SQL classification is limited to static PostgreSQL literals, reports exact/partial/unknown, resolves CTEs to their terminal operation, preserves data-modifying CTE write evidence, and does not claim coverage of runtime-generated SQL. Typed test attribution is still static evidence rather than runtime coverage proof.

  • Security flow analysis is interprocedural and path-insensitive, with 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. Default graphs resolve direct local/imported functions; build . --precise supplies stronger method/interface targets. It does not model reflection, globals, arbitrary heap aliases, or every dynamic call. Unresolved external transformations are retained with low confidence; every finding requires source review.

  • No multi-language parsing

  • No AI/model API calls

  • No embeddings or SaaS backend

  • No remote telemetry or hosted analytics (optional audit sessions write local metadata only)

  • No replacement for compiler/type-checker correctness

Contributing

Pull requests welcome! See CONTRIBUTING.md for build, test, and contribution guidelines.

Language Support: gograph currently parses Go only. The architecture is extensible — if you want to add Python, TypeScript, Rust, etc., please open an issue first.

License

MIT — see LICENSE.

gograph MCP server

Available Tools

70 tools
gograph_apiA
Read-onlyIdempotent

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. 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.

Inputs: since (required), root, intention, session_id.

gograph_arityA
Read-onlyIdempotent

Find functions and methods with at least a threshold number of parameters — the long-parameter-list smell. 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.

Inputs: min, root, intention, session_id.

gograph_boundariesA
Read-onlyIdempotent

Refresh source analysis and check package imports against a boundaries.json configuration. The required config defaults to the committable gograph/boundaries.json, then .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. 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.

Inputs: root, limit, config, cursor, +2 more.

gograph_boundaries_createA

Create a baseline architecture boundary configuration from the repository's current package imports. Defaults to the committable 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.

Inputs: root, config, intention, session_id.

gograph_calleesA
Read-onlyIdempotent

Find functions and methods called by the specified function. Defaults to one-hop fan-out; depth 2-10 expands the downstream call graph. 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.

Inputs: function (required), root, depth, limit, +5 more.

gograph_callersA
Read-onlyIdempotent

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. 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.

Inputs: function (required), root, depth, exact, +6 more.

gograph_capabilitiesA
Read-onlyIdempotent

List the running gograph server version, all available MCP tool names, and recommended agent workflows. Once the project-scoped MCP server has started, this tool has no additional graph-state prerequisite. 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: JSON with version, every registered tool name, recommended workflow sequences, and known static-analysis limitations; tool descriptions are in tools/list.

Inputs: root, intention, session_id.

gograph_changesA
Read-onlyIdempotent

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.

Inputs: root, git_ref, intention, session_id.

gograph_checkA
Read-onlyIdempotent

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.

Inputs: root, since, config, intention, +2 more.

gograph_complexityA
Read-onlyIdempotent

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. Optional symbol substring filters to a specific function or set of functions; top limits the report (default: 20; 0 = all). 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.

Inputs: top, path, root, symbol, +3 more.

gograph_concurrencyA
Read-onlyIdempotent

Find indexed concurrency sites in the codebase: goroutine spawns (go statements), channel sends, and calls on sync.Mutex/RWMutex, sync.WaitGroup, and sync.Once. 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.

Inputs: root, term, limit, cursor, +2 more.

gograph_constructorsA
Read-onlyIdempotent

Find all factory and constructor functions that instantiate and return a named Go struct (functions whose return type includes the struct name). 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.

Inputs: struct (required), root, limit, cursor, +2 more.

gograph_contextA
Read-onlyIdempotent

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. 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; 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 _meta.gograph_graph_state.read_diagnostic. With uncommitted=true, returns a contexts[] array; count:0 when no uncommitted symbols exist.

Inputs: root, exact, symbol, intention, +2 more.

gograph_couplingA
Read-onlyIdempotent

Report fan-in (Ca), fan-out (Ce), and instability I=Ce/(Ca+Ce) per package. 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.

Inputs: root, mermaid, package, intention, +3 more.

gograph_coverageA
Read-onlyIdempotent

Return the transitive set of production functions and methods statically reachable from one test function. 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. 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.

Inputs: test (required), root, package, intention, +2 more.

gograph_dependentsA
Read-onlyIdempotent

Find all packages that import the named package (inverse of gograph_deps). 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.

Inputs: package (required), root, limit, cursor, +3 more.

gograph_depsA
Read-onlyIdempotent

List the import dependencies of a named package. With transitive=false (default), returns direct imports; true returns the BFS closure. 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.

Inputs: package (required), root, mermaid, intention, +2 more.

gograph_diagramA
Read-onlyIdempotent

Refresh source analysis and generate a Mermaid architecture diagram of the package dependency graph. 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.

Inputs: root, group_by, intention, max_depth, +2 more.

gograph_docA
Read-onlyIdempotent

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.

Inputs: query (required), root, intention, session_id.

gograph_embedsA
Read-onlyIdempotent

Find all Go structs that embed the named struct via anonymous field composition. 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.

Inputs: struct (required), root, limit, cursor, +2 more.

gograph_endpointA
Read-onlyIdempotent

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. 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).

Inputs: query (required), root, depth, mermaid, +3 more.

gograph_envsA
Read-onlyIdempotent

Find all environment variable reads in the codebase via os.Getenv, os.LookupEnv, and common config frameworks, with their enclosing function context. 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.

Inputs: root, term, limit, cursor, +2 more.

gograph_errorflowA
Read-onlyIdempotent

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. 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.

Inputs: root, term, query, no_tests, +2 more.

gograph_errorsA
Read-onlyIdempotent

Find all error and panic sites in the codebase: errors.New, fmt.Errorf, sentinel var declarations, and panic calls. 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.

Inputs: root, term, limit, cursor, +3 more.

gograph_explainA
Read-onlyIdempotent

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. 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.

Inputs: symbol (required), root, intention, session_id.

gograph_exploreA
Read-onlyIdempotent

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. 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.

Inputs: query (required), deep, root, exact, +4 more.

gograph_fieldsA
Read-onlyIdempotent

Extract all declared fields from a named Go struct: field names, Go types, and raw struct tag strings (json, db, yaml, gorm, etc.). 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.

Inputs: struct (required), root, limit, cursor, +2 more.

gograph_fixturesA
Read-onlyIdempotent

Find test helper structs and factory/builder functions declared in *_test.go files for a named package. 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.

Inputs: package (required), root, limit, cursor, +2 more.

gograph_flowA
Read-onlyIdempotent

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. Run gograph build . --precise first for stronger method/interface targets. 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, parameter_only (constant non-shell program), and path steps; an exhausted budget lists top_functions by work. The policy (.gograph/flow.json or config) adds return-value or argument sanitizers and custom sources and sinks by function.

Inputs: root, sink, term, config, +7 more.

gograph_focusA
Read-onlyIdempotent

Extract a comprehensive structural summary of one Go package: all files, defined symbols, internal call edges, and package-level imports. 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.

Inputs: package (required), root, limit, cursor, +2 more.

gograph_globalsA
Read-onlyIdempotent

Find package-level variable declarations (var blocks) and the functions that mutate them in a specific package. 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.

Inputs: package (required), root, limit, cursor, +2 more.

gograph_godobjA
Read-onlyIdempotent

Detect God Object anti-pattern candidates by scoring structs on method count, field count, and outgoing call count. 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.

Inputs: top, root, calls, fields, +3 more.

gograph_hotspotA
Read-onlyIdempotent

Rank functions by incoming call count (fan-in) to identify the most-depended-on symbols in the codebase. 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.

Inputs: top, root, intention, session_id, +1 more.

gograph_httpcallsA
Read-onlyIdempotent

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. 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.

Inputs: root, term, limit, cursor, +2 more.

gograph_identityA
Read-onlyIdempotent

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. 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.

Inputs: symbol (required), root, package, intention, +1 more.

gograph_impactA
Read-onlyIdempotent

Traverse the call graph backwards to find every symbol that transitively calls the target — the full upstream blast radius of a change. 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.

Inputs: root, limit, since, cursor, +6 more.

gograph_implementersA
Read-onlyIdempotent

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. Type-checked production results merge AST-discovered test-file fakes; 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.

Inputs: interface (required), root, limit, cursor, +3 more.

gograph_importsA
Read-onlyIdempotent

Find all files and packages in the codebase that import a specific package by its exact import path. 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.

Inputs: package (required), root, limit, cursor, +2 more.

gograph_interfacesA
Read-onlyIdempotent

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. 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.

Inputs: struct (required), root, limit, cursor, +2 more.

gograph_literalsA
Read-onlyIdempotent

Find every composite-literal initialization site for a named Go struct — all locations where Foo{...} syntax is used to construct the struct. 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.

Inputs: struct (required), root, limit, cursor, +2 more.

gograph_mocksA
Read-onlyIdempotent

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. 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.

Inputs: interface (required), root, limit, cursor, +2 more.

gograph_mutateA
Read-onlyIdempotent

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. A precise graph adds ++/+=, pointer-alias, atomic/sync/wrapper, and channel mutations and re-runs that analysis after source edits. 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.

Inputs: field (required), root, limit, cursor, +2 more.

gograph_nodeA
Read-onlyIdempotent

Fetch AST metadata for a named symbol, package, or file: kind, file path, line number, full signature, doc comment, and struct fields if applicable. 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.

Inputs: name (required), root, limit, cursor, +2 more.

gograph_orphansA
Read-onlyIdempotent

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. 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.

Inputs: root, limit, cursor, intention, +1 more.

gograph_pathA
Read-onlyIdempotent

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. 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.

Inputs: to (required), from (required), root, mermaid, +2 more.

gograph_planA
Read-onlyIdempotent

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. 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.

Inputs: root, symbol, intention, session_id, +2 more.

gograph_publicA
Read-onlyIdempotent

List all exported (public) symbols of a specific package, including functions, methods, types/interfaces, variables, and constants. 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.

Inputs: package (required), root, limit, cursor, +2 more.

gograph_queryA
Read-onlyIdempotent

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.... 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.

Inputs: root, term, limit, query, +5 more.

gograph_returnusageA
Read-onlyIdempotent

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. 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.

Inputs: function (required), root, limit, cursor, +2 more.

gograph_reviewA
Read-onlyIdempotent

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. 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).

Inputs: root, symbol, intention, session_id, +1 more.

gograph_riskA
Read-onlyIdempotent

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. 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.

Inputs: root, symbol, intention, session_id, +1 more.

gograph_routesA
Read-onlyIdempotent

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. 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.

Inputs: root, term, limit, query, +5 more.

gograph_schemaA
Read-onlyIdempotent

Find Go structs that declare a mapping to a specific database table via struct tags (e.g., db:"table_name", gorm:"table:table_name"). 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.

Inputs: table (required), root, limit, cursor, +2 more.

gograph_session_auditA
Read-onlyIdempotent

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.

Inputs: json, root, intention, session_id.

gograph_session_cleanupA
DestructiveIdempotent

Archive stale and inactive session telemetry without following linked repository paths; never deletes. Each pass moves files into .gograph/to_delete//. 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.

Inputs: root, intention, session_id.

gograph_session_createA

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.

Inputs: root, intention, session_id, custom_word.

gograph_session_endA

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.

Inputs: root, intention, session_id.

gograph_skeletonA
Read-onlyIdempotent

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. 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.

Inputs: file, root, intention, session_id.

gograph_sourceA
Read-onlyIdempotent

Retrieve verbatim Go source for a named function, method, struct, interface, type, variable, or constant, including complete bodies or declarations. Source reads are confined to regular .go files beneath the analyzed repository and reject symlink path components. 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. The text carries 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).

Inputs: symbol (required), root, intention, session_id.

gograph_sqlA
Read-onlyIdempotent

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. 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[].

Inputs: root, term, limit, verbs, +8 more.

gograph_staleA
Read-onlyIdempotent

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. 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.

Inputs: root, intention, session_id.

gograph_statsA
Read-onlyIdempotent

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. 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.

Inputs: root, intention, session_id.

gograph_stringsA
Read-onlyIdempotent

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. 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.

Inputs: root, term, limit, query, +5 more.

gograph_summaryA
Read-onlyIdempotent

Single-call codebase briefing: top 3 hotspots (most-called symbols), worst instability package, highest cyclomatic complexity function, total orphan count, and god-object count. 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.

Inputs: root, intention, session_id.

gograph_testsA
Read-onlyIdempotent

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: a summary of every reaching test by depth and resolution, then one page (default 50, nearest first, with total, truncated and next_cursor) of tests with exact/possible resolution, depth, and a representative stable-ID path; max_depth keeps only nearby tests; exact_only omits uncertain paths and package disambiguates the selected product symbol. WHEN TO USE: To choose which tests to run after an edit (uncommitted=true); 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. Set uncommitted=true, since=, or select=true with a symbol to get gograph.test_selection.v1: the tests to run for a change, grouped per package, each with an anchored go test -run pattern and ready go test commands (with the graph's build tags). RETURNS: Direct result rows by default, or a versioned reverse-transitive report or test selection when requested.

Inputs: root, limit, since, cursor, +9 more.

gograph_traceA
Read-onlyIdempotent

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. WHEN TO USE: Prefer gograph_errorflow; this alias exists for compatibility. RETURNS: The same structured output as gograph_errorflow.

Inputs: term (required), root, no_tests, intention, +1 more.

gograph_uncoveredA
Read-onlyIdempotent

Changed lines of non-test Go files that a go test -coverprofile run never executed, as exact line ranges per file (gograph.uncovered.v1). Lines outside coverage blocks are never reported; changed files without profile data are listed separately. WHEN TO USE: After running tests with -coverprofile, to see which lines of your change no test executed. RETURNS: files with uncovered ranges, changed and uncovered line counts.

Inputs: coverprofile (required), root, since, intention, +2 more.

gograph_untestedA
Read-onlyIdempotent

Sweep the full graph in one pass and return called production functions and methods without an exact transitive static path from any test. 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. 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.

Inputs: pkg, top, root, exclude, +4 more.

gograph_usagesA
Read-onlyIdempotent

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. 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.

Inputs: type (required), root, limit, cursor, +2 more.

gograph_wikiA
DestructiveIdempotent

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/.md per internal package. 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.

Inputs: root, output, intention, session_id.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 70 tools

    Disambiguation3/5

    Descriptions do heavy lifting with explicit WHEN TO USE / NOT TO USE cross-references, which makes most pairwise choices resolvable. However, there is genuine redundancy: gograph_trace is an admitted alias of gograph_errorflow, gograph_mocks duplicates gograph_implementers(test_only=true), and a cluster of synthesis tools (gograph_summary, gograph_explain, gograph_explore, gograph_context, gograph_plan, gograph_review, gograph_risk, gograph_wiki) all promise 'bundled overview of a symbol/change' with only subtle deltas. An agent must read carefully to avoid picking the wrong bundle.

    Naming Consistency4/5

    All 70 tools share the gograph_ prefix and snake_case, and most use a recognizable noun or verb form (gograph_callers, gograph_boundaries_create, gograph_session_end). A few are bare nouns where a verb would help (gograph_api, gograph_node, gograph_plan, gograph_risk, gograph_impact), and the mix of noun-style and verb-style names for sibling operations is a minor deviation but nothing inconsistent or chaotic.

    Tool Count2/5

    70 tools is well past the point where a set stays legible; several are explicitly justified as call-count reducers (gograph_summary collapsing five metrics) or compatibility shims (gograph_trace, gograph_mocks), which signals the surface grew organically. The domain is legitimately broad (call graph, packages, HTTP, SQL, env, tests, sessions, wiki), but a single server with 70 entry points burdens tool selection.

    Completeness4/5

    Coverage of Go static analysis is unusually thorough: call graph both directions, package coupling, interface/inverse-interface, literals/constructors/usages, HTTP routes and endpoints, SQL, env vars, errors, concurrency, test attribution, complexity, boundaries, API drift, and session telemetry. Gaps are minor and mostly by design (no test execution, no symbol editing, runtime coverage only via external -coverprofile), which an agent can work around with the shell.

    Maintenance

    ActivityActive
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that transforms codebases into knowledge graphs using Neo4J, enabling AI assistants to understand code structure, relationships, and metrics for more context-aware assistance.
      28
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      A local code-intelligence engine for AI agents that indexes repositories into a PostgreSQL-backed code graph and serves structured, token-budgeted context over MCP and HTTP, enabling targeted queries on symbols, dependencies, contracts, and impact analysis.
      7
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Zero-dependency Go MCP server that indexes codebases into an embedded Kùzu graph DB—enabling 90%+ token reduction, precise call-chain queries, and AI architectural health audits.
      1
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables AI coding agents to interrogate a local repository deterministically for symbols, dependencies, call paths, routes, tests, and Git impact, returning verified structured evidence with exact line citations instead of requiring the whole codebase to be read.
      261 PyPI
      4
      -