Goatlas

GoAtlas

[](https://go.dev/) [](https://hub.docker.com/) [](https://neo4j.com/) [](https://www.postgresql.org/) [](https://modelcontextprotocol.io/)

GoAtlas is an AI-powered code intelligence platform that helps LLMs and developers deeply understand large codebases — combining multi-language AST parsing, a Neo4j knowledge graph, pgvector semantic search, and a pluggable LLM backend, all exposed via the Model Context Protocol (MCP).

What Makes It Different

• Multi-Language — Go, TypeScript/JSX, Python, and Java parsed via AST (tree-sitter); symbols, endpoints, imports extracted per language
• Zero-Config Auto-Discovery — Reads go.mod, package.json, requirements.txt, pom.xml to automatically activate connection detection patterns for gRPC, Kafka, HTTP clients, and more
• Cross-Service Connection Detection — Detects inter-service connections (gRPC, Kafka, HTTP) across Go, TS, Python, and Java with no config required
• Knowledge Graph — Neo4j graph of packages, files, functions, types with import/call/implementation edges
• Hybrid BM25 + Semantic Search — Reciprocal Rank Fusion merges keyword and vector results; semantic search via Gemini or Ollama embeddings
• Process & Community Detection — BFS from entry points traces execution flows; Louvain clustering groups code communities
• Pluggable LLM — Supports Gemini (gemini-2.0-flash), Ollama (any local model), and any OpenAI-compatible API (vLLM, LiteLLM, etc.) for both embeddings and agentic Q&A
• MCP Server — 22 tools, 5 resources, 3 prompts via stdio for Cursor, Claude Desktop, and any MCP client
• Claude Code Hooks — SessionStart/PreToolUse/PostToolUse integration for session context injection, semantic enrichment, and incremental re-indexing
• AI-Generated Docs — SKILL.md per community cluster and full Markdown wiki from the knowledge graph

Architecture

graph TB
    subgraph CLI["GoAtlas CLI"]
        direction LR
        IDX["index"]
        EMB["embed"]
        GR["build-graph"]
        DET["detect"]
        ASK["ask"]
        CHT["chat"]
        SRV["serve"]
        SKL["skills"]
        WK["wiki"]
    end

    subgraph Core["Core Engine"]
        direction TB
        PARSER["AST Parsers\nGo · TS/JSX · Python · Java"]
        INDEXER["Code Indexer\nsymbols · endpoints · connections"]
        CATALOG["Auto-Discovery\ngo.mod · package.json · pom.xml"]
        PROCDET["Process Detector\nBFS from entry points"]
        COMMDET["Community Detector\nLouvain algorithm"]
        AGENT["LLM Agent\nGemini or Ollama"]
        DOCGEN["Doc Generator\nskills · wiki"]
        MCP["MCP Server\ntools · resources · prompts"]
    end

    subgraph Data["Data Layer"]
        PG["PostgreSQL + pgvector\nsymbols · endpoints · embeddings"]
        NEO["Neo4j\nknowledge graph"]
        LLM["LLM Backend\nGemini API or Ollama"]
        QD["Qdrant (optional)\nvector backend"]
    end

    subgraph Clients["AI Assistants"]
        CURSOR["Cursor"]
        CLAUDE["Claude Desktop"]
        HOOKS["Claude Code Hooks"]
        ANY["Any MCP Client"]
    end

    IDX --> PARSER & CATALOG --> INDEXER --> PG
    EMB --> LLM --> PG
    GR --> NEO
    DET --> PROCDET & COMMDET --> PG
    ASK & CHT --> AGENT --> MCP
    SKL & WK --> DOCGEN --> LLM
    SRV --> MCP
    MCP --> PG & NEO & LLM
    CURSOR & CLAUDE & HOOKS & ANY --> MCP

Features

Code Intelligence

• Multi-Language Parsing — Go, TypeScript/JSX, Python, Java via AST (tree-sitter for Python/Java)
• Symbol Extraction — Functions, types, methods, interfaces, constants, variables per file
• API Endpoint Detection — HTTP routes from go-zero, gin, echo, chi, net/http, Spring MVC, and more
• Cross-Service Connection Detection — Auto-detects gRPC, Kafka, HTTP clients across all 4 languages
• Zero-Config Auto-Discovery — Reads go.mod, package.json, requirements.txt, pom.xml to activate connection patterns automatically
• Call Graph — Function-level call edges with 7-tier confidence scoring
• Interface Resolution — Detects struct-implements-interface relationships

Search & Discovery

• Keyword Search — PostgreSQL full-text search on symbol names and signatures
• Semantic Search — Vector similarity via Gemini or Ollama embeddings (pgvector or Qdrant backend)
• Hybrid Search (RRF) — Reciprocal Rank Fusion merging BM25 + vector scores for best results
• Symbol Lookup — Find symbols by name with kind filter

Process & Community Detection

• Process Detection — Forward BFS from HTTP handlers, Kafka consumers, and main() entry points
• Community Detection — Louvain modularity clustering groups tightly-connected code into named communities
• Confidence Scoring — 7-tier scores on call-graph edges and interface implementations

Knowledge Graph (Neo4j)

• Package → File → Symbol relationships
• Import edges between packages
• IMPLEMENTS edges between types and interfaces
• Service dependency mapping

AI Agent

• Pluggable LLM — Gemini (gemini-2.0-flash) or Ollama (any local model)
• Agentic Loop — Up to 20 tool-calling iterations per question
• Multi-Turn Chat — Full conversation history support
• Dynamic System Prompt — Includes repo summary, services, and available tools

Auto-Generated Documentation

• SKILL.md Generation — AI-generated skill files per community cluster for persistent Claude Code context
• Wiki Generation — Full Markdown wiki (services, communities, architecture) from the knowledge graph

Incremental Indexing

• Git-Aware — Tracks last indexed commit; --incremental re-indexes only changed files
• Staleness Detection — Check if index is behind git HEAD
• Claude Code Hooks — PostToolUse hook auto-triggers incremental re-index on file writes

Quick Start

Choose the setup path that fits you:

---

🐳 Option A — Docker (all-in-one)

Everything runs in containers — no manual DB setup needed.

1. Clone the repo

git clone https://github.com/xdotech/goatlas
cd goatlas

2. Start all services

GEMINI_API_KEY=your_key make docker-up

Builds GoAtlas and starts PostgreSQL, Neo4j, and Qdrant. Migrations run automatically on startup.

To use Ollama instead of Gemini:

LLM_PROVIDER=ollama EMBED_PROVIDER=ollama make docker-up

To use an OpenAI-compatible API (vLLM, LiteLLM, etc.):

OPENAI_BASE_URL=http://10.1.1.246:8001/v1 OPENAI_MODEL=qwen3.5-35b OPENAI_API_KEY=ignored LLM_PROVIDER=openai make docker-up

3. Index your repo

docker compose exec goatlas ./goatlas index /path/to/your/repo

4. Ask questions

docker compose exec goatlas ./goatlas ask "How does the payment service connect to Kafka?"

---

💻 Option B — Direct Install

Install the binary and connect to your own PostgreSQL and Neo4j.

1. Install

go install github.com/xdotech/goatlas@latest

2. Start PostgreSQL and Neo4j

You can use the provided compose file for just the databases:

docker compose up -d postgres neo4j

Or bring your own — just make sure DATABASE_DSN and NEO4J_URL point to them.

3. Run migrations

export DATABASE_DSN=postgres://goatlas:goatlas@localhost:5432/goatlas
goatlas migrate

4. Index your repo

goatlas index /path/to/your/repo

5. Ask questions

GEMINI_API_KEY=your_key goatlas ask "How does the payment service connect to Kafka?"
goatlas chat    # interactive multi-turn session

---

Claude Code Integration

The fastest way to get GoAtlas working inside Claude Code — both as hooks and as an MCP server.

Option A — Claude Code Hooks (recommended)

Hooks automatically enrich every Grep/Glob search with semantic context and re-index files after edits.

# Run once inside your repo
goatlas hooks install .

The command will:

1. Install SessionStart / PreToolUse / PostToolUse hooks in .claude/settings.json
2. Prompt you for DATABASE_DSN, GEMINI_API_KEY, and Neo4j credentials if not already configured
3. Save those values to ~/.claude/settings.json so they work in every project

> To update credentials later, edit the "env" section in ~/.claude/settings.json.

Option B — MCP Server

Connect GoAtlas as a full MCP server to get all 22 tools available in Claude Code, Cursor, or Claude Desktop.

Add the following config to the appropriate file for your client:

| Client | Config file | |--------|-------------| | Claude Code | .claude/settings.json (project) or ~/.claude/settings.json (global) | | Cursor | ~/.cursor/mcp.json | | Claude Desktop | claude_desktop_config.json |

{
  "mcpServers": {
    "goatlas": {
      "command": "/path/to/goatlas",
      "args": ["serve"],
      "env": {
        "DATABASE_DSN": "postgres://goatlas:goatlas@localhost:5432/goatlas",
        "NEO4J_URL": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASS": "goatlas_neo4j",
        "GEMINI_API_KEY": "your_gemini_api_key"
      }
    }
  }
}

> Replace /path/to/goatlas with the actual binary path (e.g. ~/go/bin/goatlas). Run which goatlas to find it.

> Tip: You can use both hooks and MCP together — hooks handle background enrichment and re-indexing, while MCP gives you direct tool access from the chat interface.

LLM Providers

GoAtlas supports Gemini (default), Ollama (local), and any OpenAI-compatible API (vLLM, LiteLLM, text-generation-inference, LocalAI, etc.) for both chat and embeddings, configured independently.

| Variable | Default | Description | |----------|---------|-------------| | LLM_PROVIDER | gemini | Chat/agent provider: gemini \| ollama \| openai | | EMBED_PROVIDER | gemini | Embedding provider: gemini \| ollama \| openai | | GEMINI_API_KEY | — | Required when using Gemini | | OLLAMA_URL | http://localhost:11434 | Ollama server URL | | OLLAMA_MODEL | llama3.2 | Ollama chat model | | OLLAMA_EMBED_MODEL | nomic-embed-text | Ollama embedding model | | OPENAI_BASE_URL | http://localhost:8001/v1 | OpenAI-compatible API base URL | | OPENAI_API_KEY | — | API key (use ignored for servers that don't need auth) | | OPENAI_MODEL | gpt-3.5-turbo | OpenAI-compatible chat model | | OPENAI_EMBED_BASE_URL | same as OPENAI_BASE_URL | Separate base URL for embedding requests (useful when running chat and embed on different servers) | | OPENAI_EMBED_MODEL | text-embedding-ada-002 | OpenAI-compatible embedding model |

Ollama example — run entirely locally:

LLM_PROVIDER=ollama
EMBED_PROVIDER=ollama
OLLAMA_URL=http://localhost:11434
OLLAMA_MODEL=llama3.2
OLLAMA_EMBED_MODEL=nomic-embed-text

OpenAI-compatible example — connect to vLLM, LiteLLM, or any OpenAI-compatible server:

LLM_PROVIDER=openai
OPENAI_BASE_URL=http://10.1.1.246:8001/v1
OPENAI_API_KEY=ignored
OPENAI_MODEL=qwen3.5-35b

> Note: Switching embedding models requires re-running go run . embed --force since vector dimensions differ (Gemini text-embedding-004 = 768 dims, nomic-embed-text = 768 dims, mxbai-embed-large = 1024 dims).

Multi-Language Support

GoAtlas auto-discovers connection patterns by reading your dependency files — no manual config needed.

| Language | Source | Detected Connections | |----------|--------|---------------------| | Go | go.mod | gRPC, Kafka (segmentio, sarama, confluent), HTTP (resty, standard), Redis, NATS | | TypeScript | package.json | KafkaJS, gRPC-JS, Axios, ioredis | | Python | requirements.txt | grpcio, kafka-python, httpx, requests, aiohttp, redis | | Java | pom.xml | io.grpc, Spring Kafka, OpenFeign, Spring Web, kafka-clients, Lettuce, JNATS |

Custom patterns can be added via patterns.yaml in the repo root — they merge additively with catalog defaults.

MCP Tools

GoAtlas exposes 22 MCP tools via stdio transport:

| Tool | Description | |------|-------------| | search_code | Keyword, semantic, or hybrid (RRF) symbol search | | find_symbol | Lookup a symbol by name and kind | | read_file | Read any indexed file with optional line range | | find_callers | Find all callers of a function | | list_api_endpoints | List detected HTTP routes | | get_file_symbols | All symbols defined in a file | | list_services | Top-level packages/services in the repo | | get_service_dependencies | Import graph for a service (Neo4j) | | get_api_handlers | Handler functions for an endpoint pattern (Neo4j) | | list_components | React components, hooks, interfaces, type aliases | | list_processes | Detected execution flows | | get_process_flow | Ordered call chain for a process | | list_communities | Louvain code community clusters | | detect_processes | Trigger process + community detection | | check_staleness | Check if index is behind git HEAD | | list_repos | All indexed repositories | | index_repository | Index or re-index a repository | | build_graph | Build the Neo4j knowledge graph | | generate_embeddings | Generate vector embeddings | | analyze_impact | All callers affected by a function change | | trace_type_flow | Trace data type producers and consumers | | get_component_apis | APIs called by a React component |

Resources — goatlas://repositories, goatlas://endpoints, goatlas://communities, goatlas://processes, goatlas://schema

Prompts — detect_impact, generate_map, explain_community

CLI Reference

goatlas index               # index a repository
goatlas index --force       # force re-index all files
goatlas index --incremental  # only changed files since last commit
goatlas embed                     # generate vector embeddings
goatlas embed --force             # re-embed everything
goatlas build-graph               # populate Neo4j knowledge graph
goatlas detect                    # process + community detection
goatlas ask ""          # single-shot AI Q&A
goatlas chat                      # interactive multi-turn session
goatlas serve                     # start MCP server (stdio)
goatlas skills generate     # generate SKILL.md per community
goatlas wiki          # generate Markdown wiki
goatlas check-coverage spec.md    # spec implementation coverage
goatlas hooks install       # install Claude Code hooks
goatlas migrate                   # run database migrations

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | DATABASE_DSN | postgres://goatlas:goatlas@localhost:5432/goatlas | PostgreSQL DSN | | QDRANT_URL | — | Qdrant gRPC endpoint (empty = use pgvector) | | NEO4J_URL | bolt://localhost:7687 | Neo4j Bolt endpoint | | NEO4J_USER | neo4j | Neo4j username | | NEO4J_PASS | goatlas_neo4j | Neo4j password | | GEMINI_API_KEY | — | Google Gemini API key | | LLM_PROVIDER | gemini | LLM backend: gemini \| ollama \| openai | | EMBED_PROVIDER | gemini | Embedding backend: gemini \| ollama \| openai | | OLLAMA_URL | http://localhost:11434 | Ollama server URL | | OLLAMA_MODEL | llama3.2 | Ollama chat model | | OLLAMA_EMBED_MODEL | nomic-embed-text | Ollama embedding model | | OPENAI_BASE_URL | http://localhost:8001/v1 | OpenAI-compatible API base URL | | OPENAI_API_KEY | — | API key (use ignored if not needed) | | OPENAI_MODEL | gpt-3.5-turbo | OpenAI-compatible chat model | | OPENAI_EMBED_BASE_URL | same as OPENAI_BASE_URL | Separate base URL for embedding requests | | OPENAI_EMBED_MODEL | text-embedding-ada-002 | OpenAI-compatible embedding model | | REPO_PATH | cwd | Default repository path |

Development

make build        # compile binary
make test         # run tests
make lint         # run linter
make docker-up    # build & start all services (migrations run automatically)
make docker-down  # stop all services
make migrate      # run migrations manua

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [xdotech](https://github.com/xdotech)
- **Source:** [xdotech/goatlas](https://github.com/xdotech/goatlas)
- **License:** MIT

Install and usage instructions live in the source repository linked above.