convez.ai
PluginDevOps & InfraestruturaIntermediário
ozgurcd

GoGraph — Motor de Análise Estática Go com MCP

ozgurcd/gograph

Grafo de chamadas Go para agentes IA — análise local, zero tokens em grep

Ver no GitHub
Muito bomPluginScore · de 0 a 100

Motor de análise estática local para Go que constrói um grafo de chamadas AST-aware e expõe 50+ ferramentas de query via CLI e MCP. Oferece aos agentes de IA consciência estrutural determinística: grafos de chamadas, análise de impacto, busca de símbolos e muito mais — sem executar código ou fazer chamadas de rede.

Instalação

$npx convez-ai ozgurcd/gograph

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
231
Forks
16
Acompanhando
1
Saúde
100%
Último commit
há 1 dia
Versão
v1.7.21
Issues abertas
0
Contribuidores
4

Casos de uso

  • Navegação estrutural de repositórios Go para agentes de IA codificadores
  • Análise de impacto antes de refatorações e mudanças arquiteturais
  • Auditoria de conformidade de agentes (verificação se executam plan/review)
  • Detecção de código morto, acoplamento excessivo e violações de arquitetura
  • Extração precisa de contexto de funções (eliminação de ~93% de ruído token)

Veredito

Ferramenta especializada e bem-executada para agentes de IA trabalharem com Go. Resolve real problema de tokens queimados em grep com análise estrutural determinística. Público-alvo restrito (Go + MCP), mas solução é sólida.

README

A tradução para o português deste README ainda está na fila.

gograph

Go Report Card License: MIT Go Version Homebrew Docs

Stop burning tokens on grep. Give your AI agent a graph.

gograph builds a local, AST-aware call graph of your Go repository and exposes 50+ query tools via CLI and MCP so coding agents can navigate packages, symbols, call chains, routes, SQL, env vars, and tests — without reading raw files.

Gograph Demo

Zero network. Zero execution. Zero secrets read. gograph is purely static analysis — it never runs your code, makes API calls, or opens non-.go files.

Quick Start

# Install
brew install ozgurcd/tap/gograph

# Build the graph
gograph build . --precise

# Try it — who calls ValidateToken?
gograph callers "ValidateToken"

# Full context in ONE call (node + source + callers + callees + tests)
gograph context "ValidateToken"

# Change plan before editing (callers, tests, routes, SQL, env risk)
gograph plan "ValidateToken"

Why gograph?

Benchmarked on gograph's own codebase (70 files, 518 symbols, 16 packages):

Taskgrep -rngographSavings
Find callers of loadGraph158 noisy lines (comments, docs, vars)56 exact structural call sites~65% noise eliminated
Locate symbol definitions842 lines matching "Symbol"83 true type/method declarations~90% noise eliminated
Read one function bodycat dumps 180+ lines of the whole filesource extracts the exact 12-line function~93% fewer tokens
Understand a symbol fully4–5 separate tool calls1 call: context bundles everything80% fewer tool calls

Key Features

50+ Query Tools — callers, callees, impact, context, plan, review, errorflow, orphans, hotspot, coupling, and more. Full command reference →

Native MCP Server — all tools available as MCP endpoints for Claude, Cursor, Copilot, and any MCP-compatible agent. One command setup: gograph add-claude-plugin

Token-Saving Composites — context replaces 5 calls. plan replaces 8. explain synthesizes architectural narratives. Built to minimize agent round-trips.

Safe by Design — no network, no code execution, no secrets, no .env files read. AI worktree directories (.claude/, .cursor/, .agents/) auto-excluded.

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

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

Command Reference

All commands support --json for machine-readable output and --files-only for flat file lists.

CategoryCommandsWhat it does
Indexingbuild . [--precise], stale, statsParse AST, write graph. Check freshness. Index health.
Navigationquery, callers [--depth N], callees [--depth N], path, source, nodeFind symbols, trace call chains, extract source.
Contextcontext, explain, focus, endpointBundled structural data in one call. Token savers.
Change Analysisplan, review, impact [--uncommitted|--since], changes [--git], api --sincePre-edit planning, post-edit review, blast radius, drift.
Architectureboundaries, coupling, complexity, godobj, orphans, arityQuality gates, dead code, coupling, god objects.
Types & Structsfields, implementers [--test-only], interfaces, embeds, constructors, literals, usages, mutate, schemaStruct fields, interface satisfaction, type usage.
Infrastructureroutes, sql, envs, errors, concurrency, globals, deps [--transitive], dependentsHTTP routes, SQL, env vars, concurrency, imports.
Testingtests, fixtures, mocksTest coverage map, helpers, mock implementations.
Error Tracingerrorflow [--no-tests], traceReverse-BFS from error strings to HTTP entry points.
Diagnosticshotspot, returnusage, skeleton, diagram, changes, publicHotspots, return usage, API signatures, Mermaid diagrams.
CI/CDcheck [--since|--uncommitted], gate, snapshot save|diff|list|dropPolicy checks, threshold enforcement, metric snapshots.
Telemetrysession create|end|audit|cleanupAgent compliance tracking and grading (A–F).
LLM-Wikiwiki [--output dir]Generate llm-wiki/ — machine-first markdown pages for zero-cost agent orientation (overview, architecture, hotspots, routes, env, errors, concurrency, per-package, API surface).
Summarysummary [--json]Single-call codebase briefing: top 3 hotspots, worst instability package, highest complexity function, orphan count, god-object count. Replaces 5 separate calls.
Untesteduntested [--pkg name] [--top N] [--json]Functions with callers but zero test edges — coverage gaps invisible to orphans or per-symbol test queries. One sweep replaces N tests <sym> calls.
Docdoc <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.

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

Define boundaries in .gograph/boundaries.json:

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

Run gograph boundaries — exits with code 1 on violation. Works in CI/CD.

AI Agent Integration

One-command setup (Claude Desktop + Claude Code):

gograph add-claude-plugin

This registers the MCP server, injects CLAUDE.md steering rules, and installs a PreToolUse hook that redirects grep on Go symbols to gograph tools.

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

gograph mcp .   # Run as MCP server over stdio

Add to your .cursorrules or AI system prompt:

Before answering architecture or repository questions, inspect the available gograph_* MCP tools and use them instead of grep/find. Run gograph capabilities first.

All commands support --json for machine-readable output:

gograph callers "ValidateToken" --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/
# then read: llm-wiki/README.md → project.md → rules.md → agent-contract.md → overview.md

Add llm-wiki/ to .gitignore — these files are regenerated each session.

Example Output

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

External Dependencies (Tech Stack)

ModuleVersion
github.com/gin-gonic/ginv1.9.1
github.com/jackc/pgx/v5v5.5.5

Important Symbols (Top by outgoing calls)

SymbolKindFileLineCalls out
(Server).Startmethodserver.go4218
ValidateAuthfunctionauth.go1214

Why not use a Language Server (gopls)?

gopls is optimized for human IDEs. gograph is optimized for terminal-based LLMs:

  1. Protocol Mismatch — gopls returns file:line:col coordinates. Agents must then burn tokens running cat/sed to read the actual code. gograph extracts the exact structural slice and formats it as Markdown.
  2. Graph-Level Diagnostics — gopls does hover and go-to-definition. gograph does reverse-BFS error tracing, full blast radius analysis, and PR-level change plans across the entire call graph.
  3. Composable Intelligence — gopls answers one question at a time. gograph context bundles node + source + callers + callees + tests in a single call. gograph plan aggregates impact, routes, SQL, env, and test risk into one checklist.
  • Default mode uses Go AST parsing and best-effort heuristics. Tolerates incomplete or non-compiling repositories.
  • Precise mode uses type-checked enrichment and requires compilable packages.
  • Heuristic extractors (routes, SQL, tests, error mapping) are navigation aids, not authoritative program analysis.
  • No multi-language parsing
  • No AI/model API calls
  • No embeddings or SaaS backend
  • No telemetry
  • 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

Ver o original no GitHub

Bom para

Relacionados