# Goatlas

> GoAtlas: The AI-Powered Code Intelligence Engine — A server-side MCP platform that deeply indexes Go/TypeScript codebases via AST parsing, builds a Neo4j knowledge graph, and provides hybrid semantic search (BM25 + pgvector). Features process detection, community clustering, auto-generated docs, and a Gemini AI agent.

- **Type:** MCP server
- **Install:** `agentstack add mcp-xdotech-goatlas`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [xdotech](https://agentstack.voostack.com/s/xdotech)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [xdotech](https://github.com/xdotech)
- **Source:** https://github.com/xdotech/goatlas

## Install

```sh
agentstack add mcp-xdotech-goatlas
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```mermaid
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**
```bash
git clone https://github.com/xdotech/goatlas
cd goatlas
```

**2. Start all services**
```bash
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:
```bash
LLM_PROVIDER=ollama EMBED_PROVIDER=ollama make docker-up
```

To use an OpenAI-compatible API (vLLM, LiteLLM, etc.):
```bash
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**
```bash
docker compose exec goatlas ./goatlas index /path/to/your/repo
```

**4. Ask questions**
```bash
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**
```bash
go install github.com/xdotech/goatlas@latest
```

**2. Start PostgreSQL and Neo4j**

You can use the provided compose file for just the databases:
```bash
docker compose up -d postgres neo4j
```

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

**3. Run migrations**
```bash
export DATABASE_DSN=postgres://goatlas:goatlas@localhost:5432/goatlas
goatlas migrate
```

**4. Index your repo**
```bash
goatlas index /path/to/your/repo
```

**5. Ask questions**
```bash
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.

```bash
# 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` |

```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:
```env
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:
```env
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

```bash
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

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-xdotech-goatlas
- Seller: https://agentstack.voostack.com/s/xdotech
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.