接入你的智能体
从发布者处安装。不是 PlugMCP 端点。
远程 URL 还是本机命令？ 两种安装方式的区别
来自发布者
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.
MCP tool to enable semantic code search in your project.
voyage-code-3, best on code), or Ollama (fully local, no internet required)rerank-2 or Cohere rerank-v3.5 post-RRF pass for +15-30% top-5 precisionstellaris.boundaries.json) at index time; violations surfaced via get_boundary_violations with zero runtime cost`backtick-quoted` symbol references are linked to their definitions, queryable via find_doc_references_truncated metadata, configured by STELLARIS_CONTEXT_WINDOW (small/medium/large/massive tiers)/nova_explore, /nova_find, /nova_file, /nova_review, /nova_usage)npm install; Claude Code needs a PostToolUse snippet (see below)reindex for the first time.stellarisrc)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:
~/.grok/skills/stellaris-explore/SKILL.md or <project>/.grok/skills/stellaris-explore/SKILL.md~/.claude/skills/stellaris-explore/SKILL.md or <project>/.claude/skills/stellaris-explore/SKILL.mdMCP prompts /nova_explore and /nova_find already follow this contract.
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).
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.
STELLARIS_TOOLS=all)STELLARIS_TOOLS=all)Type /nova in Claude Code to access guided workflows:
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:
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.
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"]
}
}
reindex — index the project for the first time (builds vector, FTS, and graph indexes)get_file_tree — discover the project structuresearch_code (hybrid). Known identifier definition → search_code (FTS). Occurrences of a known name → grep/rg. Optional path to search another already-indexed project.get_file_outline — view symbols + imports/exports in a matched large file (Read small files directly)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:
get_dependents — find who imports a file you're about to changeget_blast_radius — get full transitive impact before making changesget_dependencies — understand what a file relies onSteps 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_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
}]
}]
}
}
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
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.
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.
Stellaris never indexes sensitive files. Two layers of protection ensure secrets are never sent to OpenAI:
Glob exclusions (DEFAULT_EXCLUDE) — files matching these patterns are never scanned:
.env*, secrets.*, credentials.**.pem, *.key, *.cert, *.p12, *.pfx, *.keystoreIgnore 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.
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"
}
}
}
}
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
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:
meta.json) are purged from all 3 storesmeta.json entries (source file deleted from disk) are removed so the next reindex handles them correctlynpm 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).
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" }.
MCP tool to enable semantic code search in your project.
工具
暂无工具列表。远程服务器在首次健康检查后会获得工具列表。
常见问题
在本页复制适用于 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 配置。它使用发布者的安装方式，而不是 PlugMCP 代理。
此记录未列出必需的环境变量。
Stellaris Code Search 通过 stdio 在本地运行。
上次检查时间：2026-10-28。 MCP tool to enable semantic code search in your project.