go-code

module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 8, 2026 License: MIT

README

go-code

Code intelligence MCP server powered by tree-sitter AST parsing. Analyzes repositories, compares implementations, traces call chains, and searches symbols across any codebase — GitHub or local.

Features

  • 13 languages — Go, Python, TypeScript/JavaScript, Rust, Java, C, C++, Ruby, C#, PHP, Svelte, Astro
  • 8 MCP tools — from quick code search to deep structural analysis
  • Multiple analysis modes — deep (clone + AST + LLM), quick (GitHub Code Search), issues/PRs
  • Call chain tracing — bidirectional BFS with cycle detection and LLM narrative
  • Code comparison — three-pass symbol matching (exact/fuzzy/semantic) with quality verdicts
  • Knowledge graph — Apache AGE graph with NL-to-Cypher query generation
  • Caching — LRU in-memory + optional Redis L2 (200x speedup on repeated queries)
  • Learnings — prior review verdicts auto-surface in understand

Tools

Tool Description
repo_analyze Analyze a repository. Deep mode (AST + LLM), quick mode (GitHub Code Search), or issue/PR search
repo_search Discover GitHub repos via parallel SearXNG + GitHub API search with LLM-ranked results
file_parse Parse a single file with tree-sitter. Returns symbol table or raw AST
code_compare Compare two repositories structurally — architecture, API design, code quality
dep_graph Build dependency graph. Output as Mermaid, Graphviz DOT, or JSON
symbol_search Search symbols (functions, types, consts) by name pattern across a repo
call_trace Trace call chains — callees (forward) or callers (reverse) with depth control
code_graph Query a persistent code knowledge graph in Apache AGE via natural language

Optional: dead_code and code_health tools integrate with ox-codes, an internal Rust code analysis service. Without it, these tools degrade to AST-only heuristics and still produce useful results.

Quick Start

docker build -t go-code .
docker run -p 8897:8897 \
  -e LLM_API_BASE=http://host.docker.internal:8317/v1 \
  -e LLM_API_KEY=your-key \
  go-code
From source

Requires Go 1.24+ and a C compiler (CGO for tree-sitter grammars).

make build    # → bin/go-code
./bin/go-code
Register as MCP server
claude mcp add -s user -t http go-code http://127.0.0.1:8897/mcp

Usage Examples

Analyze a GitHub repo
{
  "tool": "repo_analyze",
  "arguments": {
    "repo": "golang/go",
    "query": "How does the garbage collector work?"
  }
}
Quick code search (no cloning)
{
  "tool": "repo_analyze",
  "arguments": {
    "repo": "anthropics/claude-code",
    "query": "MCP tool registration",
    "mode": "quick"
  }
}
Search issues and PRs
{
  "tool": "repo_analyze",
  "arguments": {
    "repo": "golang/go",
    "query": "generics performance",
    "type": "issue"
  }
}
Compare two implementations
{
  "tool": "code_compare",
  "arguments": {
    "repo_a": "gin-gonic/gin",
    "repo_b": "labstack/echo",
    "query": "middleware architecture and routing"
  }
}
Trace call chains
{
  "tool": "call_trace",
  "arguments": {
    "repo": "owner/repo",
    "function": "handleRequest",
    "direction": "callees",
    "depth": 5
  }
}
Analyze a local directory
{
  "tool": "repo_analyze",
  "arguments": {
    "repo": "/home/user/src/my-project",
    "query": "How is authentication implemented?"
  }
}

Configuration

Variable Default Description
MCP_PORT 8897 HTTP server port
LLM_API_BASE http://127.0.0.1:8317/v1 OpenAI-compatible LLM endpoint
LLM_API_KEY (required) API key for LLM
LLM_MODEL gemini-2.5-flash Model name
GITHUB_TOKEN (optional) GitHub token for higher API rate limits
WORKSPACE_DIR /tmp/go-code-workspace Temp directory for cloned repos
MAX_FILE_KB 512 Max file size to parse (KB)
MAX_REPO_MB 200 Max repo size to accept (MB)
REDIS_URL (optional) Redis URL for L2 cache
DATABASE_URL (optional) PostgreSQL DSN for Apache AGE code graph
SEARXNG_URL http://searxng:8888 SearXNG instance for repo_search

Architecture

cmd/go-code/          — MCP server, tool handlers (one file per tool)
internal/
  parser/             — tree-sitter AST parsing, 13 language handlers
  ingest/             — repo cloning, file walking, gitignore filtering
  clean/              — smart code cleaning for LLM context
  render/             — rendering modes (signatures, skeleton, focused)
  analyze/            — analysis orchestration
  compare/            — structural diff engine
  callgraph/          — call chain tracing (BFS/DFS, bidirectional)
  codegraph/          — Apache AGE knowledge graph
  github/             — GitHub API (search code/issues/repos, metadata)
  search/             — SearXNG web search client
  llm/                — LLM client with retry + fallback keys
  cache/              — generic LRU cache with Redis L2
  retry/              — exponential backoff with jitter
  metrics/            — atomic operation counters

Analysis Modes

Deep mode (default)

Clones the repo, walks the file tree, parses ASTs with tree-sitter, builds a symbol table, and answers questions via LLM. Supports depth (overview/module/deep) and mode (signatures/skeleton/focused) for controlling context size.

Quick mode (mode=quick)

Uses GitHub Code Search API — no cloning. Returns code fragments matching the query, optionally summarized by LLM. Use mode=raw for fragments without LLM processing.

Issues/PRs mode (type=issue or type=pr)

Searches GitHub Issues/Pull Requests API. Returns structured results with state, labels, author, and LLM analysis of trends and patterns.

Transport

  • HTTP (default): Streamable HTTP on MCP_PORT
  • Stdio: ./go-code --stdio — for pipe/SSH access

Build

make build      # Build binary (CGO required)
make lint       # Run golangci-lint
make test       # Run tests
make deploy     # Docker build + deploy

License

MIT — Copyright (c) 2026 Anatoly Koptev

Contributing

See CONTRIBUTING.md for how to add new tools and languages.

For security vulnerabilities, see SECURITY.md.

Directories

Path Synopsis
cmd
eval command
Package main — eval harness for go-code retrieval quality.
 Package main — eval harness for go-code retrieval quality.
go-code command
go-code — Code intelligence MCP server.
 go-code — Code intelligence MCP server.
internal
analyze
Package analyze provides analysis orchestration for MCP tool handlers.
 Package analyze provides analysis orchestration for MCP tool handlers.
cache
Package cache provides in-memory caches for parsed ASTs and LLM responses.
 Package cache provides in-memory caches for parsed ASTs and LLM responses.
callgraph
Package callgraph builds and queries call relationships between functions.
 Package callgraph builds and queries call relationships between functions.
clean
Package clean provides smart code cleaning for LLM consumption.
 Package clean provides smart code cleaning for LLM consumption.
codegraph
Package codegraph — surprise_index.go
 Package codegraph — surprise_index.go
codesearch
compare
Package compare provides structural and semantic code comparison between repositories.
 Package compare provides structural and semantic code comparison between repositories.
compound
Package compound provides high-level compound analysis tools that aggregate multiple lower-level analysis primitives into a single result.
 Package compound provides high-level compound analysis tools that aggregate multiple lower-level analysis primitives into a single result.
deadcode
Package deadcode detects functions and methods with zero incoming calls.
 Package deadcode detects functions and methods with zero incoming calls.
designmd
internal/designmd/parse.go
 internal/designmd/parse.go
embeddings
explore
Package explore provides a fast, structured overview of a repository.
 Package explore provides a fast, structured overview of a repository.
forge
Package forge defines the Forge interface and shared types for source-code hosting integrations (GitHub, GitLab, …).
 Package forge defines the Forge interface and shared types for source-code hosting integrations (GitHub, GitLab, …).
freshness
Package freshness parses dependency manifest files for multiple languages and discovers them in repository directory trees.
 Package freshness parses dependency manifest files for multiple languages and discovers them in repository directory trees.
gitutil
Package gitutil provides shared Git repository helpers used across multiple internal packages.
 Package gitutil provides shared Git repository helpers used across multiple internal packages.
goanalysis
Package goanalysis provides Go type-aware analysis via go/types.
 Package goanalysis provides Go type-aware analysis via go/types.
goutil
Package goutil provides shared utility functions used across multiple internal packages (analyze, explore, compare, codegraph).
 Package goutil provides shared utility functions used across multiple internal packages (analyze, explore, compare, codegraph).
graphx
Package graphx defines the cooperation interfaces between the ephemeral callgraph (internal/callgraph) and the persistent AGE graph (internal/codegraph).
 Package graphx defines the cooperation interfaces between the ephemeral callgraph (internal/callgraph) and the persistent AGE graph (internal/codegraph).
impact
Package impact computes blast radius for changing a symbol.
 Package impact computes blast radius for changing a symbol.
ingest
Package ingest handles repository ingestion: cloning remote repos, walking the local filesystem, filtering files by language/size/gitignore rules, and producing a normalized file list for downstream parsing.
 Package ingest handles repository ingestion: cloning remote repos, walking the local filesystem, filtering files by language/size/gitignore rules, and producing a normalized file list for downstream parsing.
jaegerclient
langutil
Package langutil provides shared language-aware helpers used across go-code packages.
 Package langutil provides shared language-aware helpers used across go-code packages.
learnings
Package learnings persists review findings so future reviews on the same repo/symbol can reference prior outcomes.
 Package learnings persists review findings so future reviews on the same repo/symbol can reference prior outcomes.
oxcodes
Package oxcodes provides an HTTP client for the ox-codes search service.
 Package oxcodes provides an HTTP client for the ox-codes search service.
parser
Package parser provides multi-language AST parsing via tree-sitter.
 Package parser provides multi-language AST parsing via tree-sitter.
parser/preproc
Package preproc extracts TypeScript-ish code blocks from preprocessor-language files (Svelte, Astro) into a "virtual source" buffer that can be fed to a tree-sitter TypeScript/TSX parser.
 Package preproc extracts TypeScript-ish code blocks from preprocessor-language files (Svelte, Astro) into a "virtual source" buffer that can be fed to a tree-sitter TypeScript/TSX parser.
policy
Package policy loads .go-code.yaml from a repo root and evaluates simple team rules against a review.DeltaResult.
 Package policy loads .go-code.yaml from a repo root and evaluates simple team rules against a review.DeltaResult.
polyglot
Package polyglot detects multi-language repository structures by scanning manifest files (go.mod, package.json, Cargo.toml, etc.) and grouping source files into language-specific layers.
 Package polyglot detects multi-language repository structures by scanning manifest files (go.mod, package.json, Cargo.toml, etc.) and grouping source files into language-specific layers.
promclient
prompts
Package prompts contains domain-specific LLM system prompts for go-code tools.
 Package prompts contains domain-specific LLM system prompts for go-code tools.
ranking
render
Package render provides advanced source code rendering modes for LLM context.
 Package render provides advanced source code rendering modes for LLM context.
research
Package research implements code-research: multi-signal retrieval that combines keyword (BM25F), semantic (vector embeddings), import-DAG graph expansion, and token-budget pruning to produce a compact, LLM-ready context from a repository.
 Package research implements code-research: multi-signal retrieval that combines keyword (BM25F), semantic (vector embeddings), import-DAG graph expansion, and token-budget pruning to produce a compact, LLM-ready context from a repository.
review
routes
scip
Package scip provides utilities for reading and processing SCIP code intelligence indexes.
 Package scip provides utilities for reading and processing SCIP code intelligence indexes.
semhealth
Package semhealth provides semantic health analysis bridging embeddings search with code quality metrics.
 Package semhealth provides semantic health analysis bridging embeddings search with code quality metrics.
slugparse
Package slugparse provides the canonical parser for source-code repository slugs.
 Package slugparse provides the canonical parser for source-code repository slugs.
tier
Package tier defines the 3-level analysis capability tiers and detects which tier is available based on the active backends.
 Package tier defines the 3-level analysis capability tiers and detects which tier is available based on the active backends.
webanalyze
websearch
Package websearch provides an HTTP client for go-search MCP server.
 Package websearch provides an HTTP client for go-search MCP server.
wphooks
Package wphooks provides lookup for WordPress core hook definitions.
 Package wphooks provides lookup for WordPress core hook definitions.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.