Constellation

Name: Constellation
Author: ShiftinBits

@ShiftinBits

Repository

About Constellation

Your AI agents don't understand your codebase. Upgrade from text search to code understanding.

#code #context #codegraph #navigation #intelligence #constellation #shiftinbits

Basic information

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "constellation": {
      "command": "npx",
      "args": [
        "-y",
        "@constellationdev/mcp@latest"
      ],
      "env": {
        "CONSTELLATION_ACCESS_KEY": "${CONSTELLATION_ACCESS_KEY}"
      }
    }
  }
}

Tools

DECISION RULE: Structure questions → this tool. Text search → Grep. Before using Grep, ask: Is this a STRUCTURE question (definitions, callers, impact) or a TEXT question (strings, config)? QUICK START: `return await api.searchSymbols({query: "AuthService"})` — simple queries are one-liners. Run `api.listMethods()` for full API reference with signatures and descriptions. Run `api.help("methodName")` for inline TypeScript type definitions — no resource reads needed. Compose: `const [impact, deps] = await Promise.all([api.impactAnalysis({symbolId}), api.getDependents({filePath})]);` WHY THIS TOOL: Graph-backed intelligence finds indirect relationships, transitive dependencies, and breaking change risks that text search cannot detect. "What uses X?" disambiguation: getDependents (file imports) vs getCallGraph (call chain) vs traceSymbolUsage (all usages). USE IMMEDIATELY WHEN: • BEFORE using Edit on a function/class → run impactAnalysis({symbolId}) first • BEFORE exploring an unfamiliar codebase → run getArchitectureOverview() • BEFORE refactoring → trace getDependencies + getDependents for blast radius • Running 3+ Grep calls for structure? STOP → use code_intel instead TOP 5 QUESTIONS (query is case-insensitive substring match): • "Where is X defined?" / "Find function Y" → searchSymbols({query}) • "What calls X?" / "What imports this?" → getDependents({filePath}) or getCallGraph({symbolId}) • "What does X depend on?" → getDependencies({filePath}) • "Safe to modify X?" / "Blast radius?" → impactAnalysis({symbolId}) • "Find dead code" / "Unused exports?" → findOrphanedCode() • "Complex functions?" / "Refactoring targets?" → searchSymbols results include complexity.cyclomaticComplexity + complexityRisk per function NOT FOR: literal string search, log messages, config values, or reading source code. Use Grep/Glob/Read for those. Supports TypeScript, JavaScript, Python, and more — run api.getCapabilities() to check your project. WRONG TOOL SIGNAL: If you've run 3+ Grep calls for structure (callers, dependencies, impact), STOP and use code_intel instead. Typical workflow: code_intel to find (results include source snippets) → Edit to modify IMPORTANT: The `cwd` parameter is required — always set it to the target project directory path.

Overview

What is Constellation?

Constellation turns your codebase into a queryable knowledge graph, giving AI assistants the structural understanding they need to reason about real software — not just plain text. It integrates with AI assistants via a single code_intel tool that exposes a rich JavaScript API for code intelligence queries.

How to use Constellation?

Invoke the code_intel tool with JavaScript API calls such as api.searchSymbols, api.impactAnalysis, and api.getDependents. The tool composes queries like code, allowing the assistant to ask about symbol definitions, usage, impact, and dependencies.

Key features of Constellation

Turns codebase into a semantic graph, not a grep loop
Single code_intel tool with JavaScript API
Multi-language: TypeScript, JavaScript, Python (more coming)
Multi-project support with per‑project git root resolution
Fast: parallel API calls, inline source snippets
Safe: hardened sandbox with isolated child process and memory limits
Privacy by design: source code never leaves your machine

Use cases of Constellation

Find where a symbol is defined and used across the codebase
Assess the blast radius of a code change before editing
Detect circular dependencies or dead code in modules
Trace data flow through the call graph

FAQ from Constellation

How does Constellation differ from plain text search?

Text search tells you where a string appears everywhere; Constellation gives you the exact location of a symbol, its meaning, its callers, and the impact of changing it — from a semantic graph, not a grep loop.

What languages does Constellation support?

TypeScript, JavaScript, and Python are supported, with more languages planned.

Where does my source code live?

Your source code never leaves your machine. Constellation parses it to a compressed AST locally; only structural metadata is sent to the service. Access keys scope each project to its own namespace.

What are the runtime requirements?

Constellation runs queries in an isolated child process with hard memory limits. It auto‑resolves per‑project configuration by git root with LRU caching.