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

• Routed search — identifier / dotted / quoted string → FTS only (never embeds; a miss is empty, not a vector guess). Intent → hybrid FTS + vectors + RRF. Language keywords refused.

• 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 — Grok installs it on npm install; Claude Code needs a PostToolUse snippet (see below)

• 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)

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

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

Related MCP server: Serena MCP Server

How agents should search

Grep/rg wins on a known name for occurrences. Stellaris wins for intent, ranked definition, and large-file outline/symbol. Do not send every lookup through hybrid search_code.

Copy the agent skill so this routing is loaded automatically:

skills/stellaris-explore/SKILL.md

• Grok: ~/.grok/skills/stellaris-explore/SKILL.md or <project>/.grok/skills/stellaris-explore/SKILL.md

• Claude Code: ~/.claude/skills/stellaris-explore/SKILL.md or <project>/.claude/skills/stellaris-explore/SKILL.md

MCP prompts /nova_explore and /nova_find already follow this contract.

Benchmark: intent / multi-file (not a known identifier)

Tested on a real-world Astro project (341 files, 430 chunks indexed), on intent questions (auth flows, payment, i18n) — not search_code("usePermissions"):

On a name you already have, grep/rg is cheaper for occurrences. search_code FTS is for the ranked definition (no embedding).

Tools

11 tools are listed by default: search_code, search_docs, get_file_tree, get_file_outline, get_symbol, get_dependencies, get_dependents, get_blast_radius, session_briefing, reindex, reindex_file.

Set STELLARIS_TOOLS=all in the server env to list the other 19 (graph analysis, architecture boundaries, DB schema, usage tracking) and to start the usage scanner. They stay callable either way.

Style and config files (.css, .scss, .less, .json, .yaml, .yml, .toml) are indexed for keyword search only: they are not embedded.

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, STELLARIS_TOOLS=all)

Usage tracking (no API calls, STELLARIS_TOOLS=all)

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 — only the ones the symbol refers to, so the LLM knows where its 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.

On files ≤150 lines, get_symbol omits file_context (Read the small file instead). The context parameter 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. Find code — intent → search_code (hybrid). Known identifier definition → search_code (FTS). Occurrences of a known name → grep/rg. Optional path to search another already-indexed project.

4. get_file_outline — view symbols + imports/exports in a matched large file (Read small files directly)

5. get_symbol — one body from a large file; follow the next: hint. Do not Read the whole file.

Or use /nova_explore / the stellaris-explore skill.

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 (Grok + Claude Code)

auto_index=true only runs at MCP startup. While a session is open, new/edited files are indexed by a PostToolUse hook.

Grok (automatic). npm install installs ~/.grok/hooks/stellaris-reindex.json when ~/.grok exists and Node 22 (nova-node) is available. It fires after write / search_replace (and Claude aliases Write / Edit), reads the path from hook stdin, and reindexes that file. Re-run:

npm run install-hooks

Then start a new Grok session (or /hooks-list to confirm stellaris-reindex). The hook must run under Node 22 — never PATH Node 26 — because it loads better-sqlite3.

Claude Code (manual). Add this to ~/.claude/settings.json (replace the path):

{
  "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
      }]
    }]
  }
}

Installation

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

Node 22 only (ABI 127). Grok / Nova launch this server with nova-node, not PATH node. This repo has a mise.toml pin. Do not npm rebuild better-sqlite3 under Node 24/26 — it breaks the MCP for every project until you reinstall with Node 22.

# if PATH node is not 22:
/home/charles/.local/bin/nova-node "$(command -v npm)" install
npm run doctor   # must print ABI 127

Configuration

Environment variables

The server and the per-edit hook read DOTENV_CONFIG_PATH, then the .env of the working directory, then the .env next to the install: one .env in the Stellaris folder is enough for every project.

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

# Import-alias overrides (safety net if auto-detection from
# tsconfig paths / vite resolve.alias fails). Path is relative
# to the project root.
# alias.@=src
# alias.#utils=src/lib/utils

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

Import alias resolution. The dependency graph auto-detects path aliases from the tsconfig.json/jsconfig.json nearest each source file (following extends, including monorepo subdirectories), falling back to vite.config.* resolve.alias. The @/ and ~/ conventions resolve to the nearest src/ automatically. Use the alias.<name>=<path> lines above only as an override when auto-detection can't find your config.

.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/
    route.ts            # Query classifier: identifier/exact → FTS, intent → hybrid
    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 (routed FTS / 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
npm test       # All test files (Node 22)

Native addons (better-sqlite3, LanceDB, tree-sitter) are built for Node 22: run npm install, npm run build and npm test under Node 22 (mise exec -- in this repo).

Maintenance scripts

The server repairs an index at startup (integrity check, then incremental reindex). These scripts do the same for a list of projects, without opening a session in each:

Run them with npx tsx. eval.json is a list of { "q": "question", "expect": "part of the file path" }.

License

MIT