Stellaris MCP

An MCP server that combines semantic search (pluggable embeddings + LanceDB) with AST-based code exploration (tree-sitter) for AI agents.

Search your codebase with natural language, browse file structures, inspect symbol outlines, and retrieve exact source code — all through the Model Context Protocol.

Version francaise / French version

Features

• Hybrid search (FTS5 + vector embeddings + RRF) — finds exact identifiers and semantic concepts

• Pluggable embeddings — OpenAI (default), Voyage AI (voyage-code-3, best on code), or Ollama (fully local, no internet required)

• Optional re-ranking — Voyage rerank-2 or Cohere rerank-v3.5 post-RRF pass for +15-30% top-5 precision

• Dependency graph — resolves imports to real file paths, tracks file→file dependencies

• Blast radius analysis — BFS traversal to find what would break if you change a file

• Architecture boundaries (v4.4) — enforce layer rules (stellaris.boundaries.json) at index time; violations surfaced via get_boundary_violations with zero runtime cost

• Doc/spec linking (v4.4) — markdown `backtick-quoted` symbol references are linked to their definitions, queryable via find_doc_references

• Context-overflow protection (v4.4) — tier-aware result limits + automatic truncation with _truncated metadata, configured by STELLARIS_CONTEXT_WINDOW (small/medium/large/massive tiers)

• MCP Prompts — 5 guided workflows (/nova_explore, /nova_find, /nova_file, /nova_review, /nova_usage)

• Usage dashboard — tracks Claude Code token consumption and estimated API cost in real time, with cache analytics and task category breakdown

• Token breakdown — see where tokens go: by task category (coding, debugging, feature…), MCP server, and core tool — inspired by codeburn

• Index integrity checker — automatically purges orphaned chunks and stale meta entries at every startup

• Auto-reindex hook — keeps the index fresh automatically after every Write/Edit

• AST exploration: file tree, symbol outlines, source extraction — zero API calls

• Context-aware: imports, sibling symbols, and TODO/FIXME warnings included automatically

• Incremental indexing: only changed files are re-embedded

• Safe by default: no auto-indexing until you explicitly run reindex for the first time

• Auto-indexing on subsequent startups (opt-in via .stellarisrc)

• 25 file extensions: TS, JS, Python, Go, Rust, PHP, Java, Ruby, HTML, CSS, Astro, Vue, Svelte, SCSS, JSON, YAML, SQL, GraphQL, Prisma, TOML, and more

• Graceful degradation: works without any API key (AST tools still available)

Benchmark: Stellaris vs Grep/Glob

Tested on a real-world Astro project (341 files, 430 chunks indexed):

Stellaris excels at complex multi-file questions (auth flows, payment logic, i18n systems). Grep/Glob remain better for exhaustive file listings. Best strategy: Stellaris first, Grep/Glob as complement.

Tools (16)

Semantic search (requires an embedding API key, or Ollama locally)

Structural exploration (no API calls)

Dependency graph (no API calls)

Architecture & documentation (no API calls, v4.4)

Usage tracking (no API calls)

MCP Prompts

Type /nova in Claude Code to access guided workflows:

Context-aware design

A common pitfall with code search tools is returning results that are too precise — the LLM gets the exact function it asked for, but misses the surrounding context needed to make safe decisions (imports, sibling functions, TODO warnings).

Stellaris addresses this with automatic context enrichment:

• get_symbol returns the requested source code plus file-level context by default:

  • Imports — so the LLM knows where dependencies come from

  • Sibling symbols — names and line ranges of other functions/classes in the same file, preventing duplications and revealing patterns

  • Warnings — TODO, FIXME, HACK, NOTE, @deprecated comments found anywhere in the file

• get_file_outline returns symbol names plus the file's imports and exports, so the LLM understands the dependency graph before diving into code.

This adds ~100-200 tokens of "useful noise" per call — far cheaper than reading the entire file (~800-2000 tokens), while preventing blind refactoring errors.

The context parameter on get_symbol can be set to false if you only need the raw source.

Example get_symbol response

{
  "file": "src/indexer/chunker.ts",
  "symbol": "chunkCodeAST",
  "lines": "299-380",
  "source": "function chunkCodeAST(content, file) { ... }",
  "file_context": {
    "imports": ["node:crypto", "tree-sitter", "../config/defaults.js"],
    "exports": ["chunkFile", "parseFileSymbols", "extractFileContext"],
    "siblings": [
      "function extractImports (261-285)",
      "function chunkMarkdown (382-429)",
      "function chunkCodeFallback (431-465)"
    ],
    "warnings": ["L42: TODO handle edge case for empty files"]
  }
}

Recommended workflow

1. reindex — index the project for the first time (builds vector, FTS, and graph indexes)

2. get_file_tree — discover the project structure

3. search_code — find features by natural language description (hybrid search)

4. get_file_outline — view symbols + imports/exports in a matched file

5. get_symbol — retrieve exact source code with surrounding context

Or use /nova_explore to run steps 2–5 as a guided workflow.

Impact analysis workflow:

1. get_dependents — find who imports a file you're about to change

2. get_blast_radius — get full transitive impact before making changes

3. get_dependencies — understand what a file relies on

Steps 2, 4, 5, and all graph tools consume zero API tokens.

After the first reindex, a .stellarisrc file is created in the project root with auto_index=true. Subsequent server startups will automatically run incremental indexing (only changed files).

Auto-reindex hook

To keep the index fresh in real time during Claude Code sessions, add this to your ~/.claude/settings.json:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "node \"/path/to/stellaris-code-search/scripts/reindex-file.mjs\" \"$file_path\" 2>&1 || true",
        "timeout": 30
      }]
    }]
  }
}

Replace /path/to/stellaris-code-search with the actual path to your Stellaris installation.

Installation

git clone https://github.com/GDM-Pixel/stellaris-code-search.git
cd stellaris-code-search
npm install
npm run build

Configuration

Environment variables

Without any embedding API key (and no Ollama), the server starts normally — get_file_tree, get_file_outline, and get_symbol work without it.

Switching embedding providers

If you change EMBEDDING_PROVIDER on an existing index, Stellaris will refuse to run an incremental reindex (to avoid silently corrupting the vector store). Run:

# Force-rebuild the index with the new provider
reindex force=true

This deletes the old LanceDB table and meta.json, then rebuilds from scratch.

.vectorconfig.json (optional)

Place at the root of the project to index:

{
  "include": ["src/**", "packages/**", "docs/**"],
  "exclude": ["node_modules/**", "dist/**", "**/*.test.ts"],
  "chunkStrategy": "ast"
}

stellaris.boundaries.json (optional, v4.4)

Place at the project root to enforce architecture layer rules at index time. Any depends_on edge that matches a deny rule is flagged as a boundary violation and surfaced through get_boundary_violations. Detection happens during reindex — there is no runtime cost.

{
  "deny": [
    {
      "name": "ui-never-imports-db",
      "from": "src/ui/**",
      "to": "src/db/**",
      "reason": "UI layer must go through services, not DB directly"
    },
    {
      "from": "src/domain/**",
      "to": "src/infrastructure/**",
      "reason": "Hexagonal architecture: domain must stay infrastructure-agnostic"
    }
  ]
}

Glob syntax: ** matches any depth, * matches one path segment, ? matches one character. Paths are relative to project root, forward slashes.

.stellarisrc (auto-generated)

Created automatically after the first successful reindex. Controls auto-indexing and embedding configuration.

# Stellaris Code Search configuration
auto_index=true

# Embedding provider (openai | voyage | ollama) — default: openai
# embedding_provider=voyage
# embedding_model=voyage-code-3

# Re-ranking (off | voyage | cohere) — default: off
# rerank_provider=voyage

You can toggle auto_index via the reindex tool (enable_auto_index: false) or edit the file manually.

.vectorignore (optional)

Same syntax as .gitignore, to exclude files from indexing.

Security

Stellaris never indexes sensitive files. Two layers of protection ensure secrets are never sent to OpenAI:

1. Glob exclusions (DEFAULT_EXCLUDE) — files matching these patterns are never scanned:

   • .env*, secrets.*, credentials.*

   • *.pem, *.key, *.cert, *.p12, *.pfx, *.keystore

2. Ignore filter (defense in depth) — same patterns applied via the ignore library during file scanning, as a second safety net.

Additionally, .gitignore and .vectorignore rules are always respected.

Claude Desktop integration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "stellaris-mcp": {
      "command": "node",
      "args": ["/path/to/stellaris-code-search/dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

To use Voyage embeddings instead of OpenAI:

{
  "mcpServers": {
    "stellaris-mcp": {
      "command": "node",
      "args": ["/path/to/stellaris-code-search/dist/index.js"],
      "env": {
        "EMBEDDING_PROVIDER": "voyage",
        "VOYAGE_API_KEY": "pa-...",
        "RERANK_PROVIDER": "voyage"
      }
    }
  }
}

To use Ollama (fully local, no API key needed):

{
  "mcpServers": {
    "stellaris-mcp": {
      "command": "node",
      "args": ["/path/to/stellaris-code-search/dist/index.js"],
      "env": {
        "EMBEDDING_PROVIDER": "ollama",
        "OLLAMA_MODEL": "nomic-embed-text"
      }
    }
  }
}

Supported languages & formats

Architecture

src/
  index.ts              # MCP entry point, tool + prompt registration
  startup.ts            # Auto-indexing on startup (reads .stellarisrc)
  prompts.ts            # MCP Prompts definitions (nova_explore, nova_find, nova_usage, ...)
  config/
    defaults.ts         # Extensions, chunking settings, LanceDB config
    loader.ts           # .vectorconfig.json loader
    stellarisrc.ts      # .stellarisrc reader/writer
  indexer/
    scanner.ts          # File scanning (.gitignore, .vectorignore)
    chunker.ts          # Multi-language AST parsing + symbol extraction
    embedder.ts         # Embedding factory (provider-agnostic)
    hasher.ts           # SHA-256 hashing + _index_config sentinel
    providers/
      base.ts           # EmbeddingProvider interface + retry helper
      openai.ts         # OpenAI provider (text-embedding-3-small)
      voyage.ts         # Voyage AI provider (voyage-code-3)
      ollama.ts         # Ollama provider (nomic-embed-text, local)
  store/
    lancedb.ts          # LanceDB vector storage (dynamic dims)
    fts.ts              # SQLite FTS5 full-text index
  search/
    hybrid.ts           # RRF fusion of vector + FTS results + optional rerank
    reranker.ts         # Voyage / Cohere re-ranking post-RRF
  graph/
    resolver.ts         # Import string → real file path resolution
    store.ts            # SQLite dependency graph (graph.db)
    blast.ts            # BFS blast radius + dependency chain
  tools/
    searchCode.ts       # search_code tool (hybrid)
    searchDocs.ts       # search_docs tool (hybrid)
    reindex.ts          # reindex + reindex_file tools
    getFileTree.ts      # get_file_tree tool
    getFileOutline.ts   # get_file_outline tool
    getSymbol.ts        # get_symbol tool
    getDependencies.ts  # get_dependencies tool
    getDependents.ts    # get_dependents tool
    getBlastRadius.ts   # get_blast_radius tool
    usageStats.ts       # usage_stats tool (group_by: model/project/day/cache/anomaly/category/mcp/core_tool)
    usageDashboard.ts   # usage_dashboard tool + HTTP server
    usageBreakdown.ts   # usage_breakdown tool (Markdown report)
  usage/
    scanner.ts          # JSONL scanner — global dedup by message.id, MCP/core split, classifier
    store.ts            # SQLite schema: turns, sessions, processed_files + v3.9 columns
    pricing.ts          # Per-model pricing table (April 2026)
    classifier.ts       # 13-category heuristic classifier (bilingual FR+EN)
    dashboard.ts        # Interactive HTML dashboard renderer (5 tabs incl. Breakdown)
  indexer/
    integrity.ts        # Startup integrity check: orphan purge + stale meta cleanup
scripts/
  reindex-file.mjs      # Hook script for auto-reindex after Write/Edit

Storage

The index is stored in .vectors/ at the project root:

• .vectors/lancedb/ — LanceDB vector database (embeddings)

• .vectors/fts.db — SQLite FTS5 full-text index

• .vectors/graph.db — SQLite dependency graph

• .vectors/meta.json — file meta-index (hashes, chunk IDs, timestamps)

This directory is automatically excluded from scanning.

Usage data is stored globally in ~/.claude/usage.db (SQLite). Data older than 180 days is automatically purged at startup. The dashboard shows the last 90 days.

At every startup, an integrity check runs automatically:

• Orphaned chunks (in LanceDB/FTS/graph but absent from meta.json) are purged from all 3 stores

• Stale meta.json entries (source file deleted from disk) are removed so the next reindex handles them correctly

Development

npm run dev    # Run with tsx (hot reload)
npm run build  # Compile TypeScript
npm run watch  # Watch mode compilation

License

MIT