gograph MCP server
Commit Nov 14, 2026Builds a local structural graph of Go repositories to help AI agents trace callers, interface implementations, and plan code refactors.
Also known as ozgurcd/gograph
- Stars
- 231
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 1.7.19
- Last commit
- Nov 14, 2026
- License
- MIT
What is gograph MCP?
gograph builds a local structural graph of Go repositories to help AI agents trace callers, interface implementations, and plan code refactors.
Summary generated from the project's README
About gograph MCP server
gograph provides a local structural graph of Go repositories to assist AI agents in navigating complex codebases. It functions as a compiler-aware map that allows developers to trace callers, interface implementations, and function flows without relying on hosted indexes or embeddings. The tool operates locally, using the installed Go toolchain to perform static analysis and can be integrated into MCP clients via a stdio server.
Users can choose between standard AST-only indexing or a precise mode that includes type-checked CHA/SSA enrichment for accurate cross-package dispatch. The system supports advanced features like memory-constrained builds using a low-memory mode and strict CI enforcement to prevent precision fallbacks. It manages local build artifacts within a .gograph directory and respects existing Git configurations and Go build constraints to ensure the analysis remains confined to the intended repository boundaries.
What you can do with it
- 1Trace interface implementationsAn AI agent can identify which specific types implement a given interface to understand polymorphic behavior.
- 2Validate structural requirementsAutomate checks to ensure specific symbols or relationships exist within a repository using machine-readable output.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 12, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packageNot checked
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubgograph
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. source prints exact selectors for ambiguous matches.
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.
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.

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/buildare 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, andvendor/modules.txt) is rejected before toolchain invocation; an explicitly symlinked repository root remains supported. Applicablego.work usemembers 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 optionalgo.sumis validated beforecmd/gostarts. 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, anddocrunsgo doc. Those operations follow your configured module/cache/network policy. Before repository package loading orgo doc, applicable local module/workspace source trees are preflighted for links thatcmd/gomay inspect;.gitand.gographsubtrees 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.
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 only
symbol_exists, package_imports, call_edge_exists, and type_implements.
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 |
gograph MCP questions
Does gograph execute the target code?
No, it performs static analysis and does not call application services or execute target code.
How can I limit memory usage during a build?
You can use the --memory-mode=low flag along with a --max-memory limit (e.g., 1GiB) to prioritize lower heap use.
Can I exclude specific directories from the analysis?
Yes, you can use the --exclude-dirs flag to omit unrelated or broken package directories.