Constellation is an MCP server that gives AI coding assistants queryable code intelligence (structure, dependencies, and relationships) without transmitting source code.
Search symbols: searchSymbols finds where functions/classes are defined and includes complexity metrics.
Inspect symbols: getSymbolDetails returns detailed metadata for a given symbol.
Map dependencies: getDependencies and getDependents show what a file imports and what imports it.
Trace usage: traceSymbolUsage finds all usages of a symbol across the codebase.
Analyze call graphs: getCallGraph reveals call chains for a symbol.
Assess impact: impactAnalysis estimates blast radius before refactoring or editing code.
Find dead code: findOrphanedCode identifies unused exports/orphaned symbols.
Detect circular dependencies: findCircularDependencies surfaces circular import/relationship cycles.
Get architecture overview: getArchitectureOverview provides a high-level structural view of unfamiliar codebases.
Check language support: getCapabilities shows which languages are indexed.
Privacy-first: only metadata is uploaded; no raw source code leaves the environment, with API-key access control and per-branch isolation.
Integrates with Git to provide branch-aware code intelligence, ensuring that codebase metadata and analysis remain discrete and isolated between different development branches.
Provides GitHub Copilot with structured codebase metadata and relationship analysis, enabling deeper context for code intelligence and assistant-led development.
Give your AI coding assistant instant, intelligent access to your entire codebase's structure, dependencies, and relationships without transmitting any source code. Constellation provides code intelligence as a service to AI coding assistant tools.
Add the Constellation MCP server to your AI assistant project-level config (or system-level if your tooling doesn't support project-level configuration):
{
"mcpServers": {
"constellation": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@constellationdev/mcp@latest"],
"env": {
"CONSTELLATION_ACCESS_KEY": "${CONSTELLATION_ACCESS_KEY}"
}
}
}
}
The above example is a generic format for the .mcp.json file used by some tools such as VSCode and Claude Code.
Rather than directly configuring the MCP server, it is recommended to install and utilize official Constellation Plugins for optimal performance and behavior!
For information on configuring other AI assistants see the MCP Server > Installation doc.
For further instructions regarding authentication, project setup, and configuration refer to the official docs.
Related MCP server: NOMIK
%%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#4A90E2', 'primaryTextColor': '#EEEEEE', 'primaryBorderColor': '#2B2C34', 'lineColor': '#4A90E2', 'secondaryColor': '#1F1F28', 'tertiaryColor': '#0B0C10', 'edgeLabelBackground': '#1F1F28' }}}%%
flowchart LR
subgraph local["š» Your Environment"]
direction TB
code["š Source Code"]
cli["āļø Constellation CLI"]
ai["š¤ AI Coding Assistant"]
mcp["š§© Constellation MCP"]
code --> cli
end
subgraph cloud["āØ Constellation Service"]
direction TB
api["š API"]
graphdb[("š§ Knowledge Graph")]
api <--> graphdb
end
cli a1@-->|"Metadata Upload"| api
ai <-->|"Tool Calls"| mcp
mcp a2@<-->|"Queries"| api
a1@{ animation: fast }
a2@{ animation: fast }
style local fill:#1F1F28
style cloud fill:#1F1F28,stroke:#4A90E2
style cli stroke:#4A90E2
style mcp stroke:#4A90E2
style api stroke:#4A90E2
style graphdb stroke:#4A90E2Parse and Analyze: The CLI tool analyzes source code in your environment, extracting structural metadata (functions, classes, variables, imports, calls, references, etc.)
Upload: Only the metadata is securely sent to Constellation, never raw source code
Query: AI assistants use the Constellation MCP tool to send complex queries, and get rapid answers derived from the knowledge graph
Find the full and comprehensive documentation at docs.constellationdev.io/mcp/
Installation & Setup - Configure for Claude Code, Cursor, GitHub Copilot, and more
Tools Reference - Code Mode API and available methods
Troubleshooting - Common issues and solutions
No source code transmission - Only metadata and relationships
Access control - API keys required for all requests
Branch isolation - Each git branch maintains discrete code intelligence
For comprehensive information regarding privacy and security, see the official Privacy & Security documentation and the Privacy Policy.
Documentation: docs.constellationdev.io
Report Issues: GitHub Issues
AGPL-3.0 - See LICENSE for details.
Copyright Ā© 2026 ShiftinBits Inc.
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.
File-path-scoped methods (getDependencies, getDependents, getCallGraph, traceSymbolUsage, impactAnalysis) reject calls whose filePath extension is not in the project's configured languages with UNSUPPORTED_LANGUAGE ā check api.getCapabilities() first.
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
Sandbox limits: 50 api.* calls per execution, 128 MB memory, 100 KB max code size, limit max 100 on any method with a limit param. Pure JS only ā no require/import/fs/net/process (see constellation://docs/guide for full restrictions).
IMPORTANT: The cwd parameter is required ā always set it to the target project directory path.
The optional hook input is for agent-plugin hooks; agents omit it.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | Yes | Absolute path to the project directory being queried. Used to locate the correct constellation.json by finding the git repository root. Set this to the root of the repository or workspace folder you are working in. | |
| code | Yes | JavaScript code to execute. Can use top-level await. Available API methods: searchSymbols, getSymbolDetails, getDependencies, getDependents, findCircularDependencies, traceSymbolUsage, getCallGraph, impactAnalysis, findOrphanedCode, getArchitectureOverview | |
| hook | No | For agent-plugin hooks; agents omit it. Runs `code` with a read-only `hook` global and returns an advisory hook output instead of the result envelope. | |
| timeout | No | Optional execution-time override in milliseconds. When omitted, the sandbox derives the timeout from the static complexity of your code (heavier api.* methods raise the budget) and clamps the result to [1000, 60000]. The breakdown is returned in the response so you can see what was applied. Explicit values still win and are clamped to the same range. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive behavior, but the description adds substantial context beyond them: sandbox call/memory/size limits, `limit` max 100, prohibited Node APIs, required `cwd`, and UNSUPPORTED_LANGUAGE rejection for file-path-scoped methods. This is exactly the extra behavioral disclosure an agent needs before running arbitrary code.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well structured with headers, quick-start examples, and front-loaded decision rules. Some points, especially the Grep-vs-structure rule, are repeated in 'NOT FOR' and 'WRONG TOOL SIGNAL', which costs a little conciseness without hurting usability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a complex sandboxed-code tool with nested objects and an output schema, the description covers execution constraints, language support, error behavior, required inputs, and the recommended workflow. Return values need not be explained because an output schema exists, so nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description emphasizes that `cwd` is required and that agents should omit `hook`, but the schema already says both; its `limit` note applies to nested API methods rather than top-level parameters, so added meaning over the schema is marginal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific purpose: graph-backed code intelligence for structure questions, explicitly contrasted with text search via Grep. It names concrete API methods (searchSymbols, impactAnalysis, getDependents) and the questions they answer, so an agent can tell exactly what the tool is for.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit decision rule (structure ā this tool, text ā Grep), a 'NOT FOR' list, a 'WRONG TOOL SIGNAL' trigger for repeated Grep calls, and a typical workflow (code_intel ā Edit). Alternatives and exclusions are both named, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.3.0code_intel8 fields changedInput schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesRemoved value: -falseInput schema / properties / hookAdded value: +{
+ "description": "For agent-plugin hooks; agents omit it. Runs `code` with a read-only `hook` global and returns an advisory hook output instead of the result envelope.",
+ "properties": {
+ "event": {
+ "description": "Hook event name (string), e.g. PreToolUse or SessionStart."
+ },
+ "input": {
+ "description": "Hook payload (JSON)."
+ },
+ "sessionId": {
+ "description": "Hook session id (string)."
+ },
+ "settings": {
+ "description": "CONSTELLATION_* env names to expose (string[])."
+ }
+ },
+ "required": [
+ "event"
+ ],
+ "type": "object"
+}Output schema / $schemaRemoved value: -"http://json-schema.org/draft-07/schema#"Output schema / additionalPropertiesRemoved value: -falseOutput schema / anyOfAdded value: +[
+ {
+ "additionalProperties": false,
+ "properties": {
+ "asOfCommit": {
+ "type": "string"
+ },
+ "error": {
+ "type": "string"
+ },
+ "lastIndexedAt": {
+ "type": "string"
+ },
+ "logs": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "result": {},
+ "resultContext": {
+ "additionalProperties": false,
+ "properties": {
+ "branchIndexed": {
+ "type": "boolean"
+ },
+ "indexedFileCount": {
+ "type": "number"
+ },
+ "reason": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "reason",
+ "branchIndexed",
+ "indexedFileCount"
+ ],
+ "type": "object"
+ },
+ "success": {
+ "type": "boolean"
+ },
+ "time": {
+ "type": "number"
+ },
+ "timeoutBreakdown": {
+ "additionalProperties": false,
+ "properties": {
+ "appliedMs": {
+ "type": "number"
+ },
+ "baseMs": {
+ "type": "number"
+ },
+ "calls": {
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "computed": {
+ "const": true,
+ "type": "boolean"
+ },
+ "method": {
+ "type": "string"
+ },
+ "weight": {
+ "type": "number"
+ }
+ },
+ "required": [
+ "method",
+ "weight"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "coldStartGraceMs": {
+ "type": "number"
+ },
+ "estimatedMs": {
+ "type": "number"
+ },
+ "parallelismFactor": {
+ "type": "number"
+ },
+ "warnings": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "baseMs",
+ "calls",
+ "parallelismFactor",
+ "estimatedMs",
+ "coldStartGraceMs",
+ "appliedMs",
+ "warnings"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "success"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "hookSpecificOutput": {
+ "additionalProperties": false,
+ "properties": {
+ "additionalContext": {
+ "type": "string"
+ },
+ "hookEventName": {
+ "enum": [
+ "PreToolUse",
+ "PostToolUse",
+ "SessionStart",
+ "SubagentStart",
+ "UserPromptSubmit",
+ "Stop"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "hookEventName",
+ "additionalContext"
+ ],
+ "type": "object"
+ },
+ "systemMessage": {
+ "type": "string"
+ }
+ },
+ "type": "object"
+ }
+]Output schema / propertiesRemoved value: -{
- "asOfCommit": {
- "type": "string"
- },
- "error": {
- "type": "string"
- },
- "lastIndexedAt": {
- "type": "string"
- },
- "logs": {
- "items": {
- "type": "string"
- },
- "type": "array"
- },
- "result": {},
- "resultContext": {
- "additionalProperties": false,
- "properties": {
- "branchIndexed": {
- "type": "boolean"
- },
- "indexedFileCount": {
- "type": "number"
- },
- "reason": {
- "type": "string"
- }
- },
- "required": [
- "reason",
- "branchIndexed",
- "indexedFileCount"
- ],
- "type": "object"
- },
- "success": {
- "type": "boolean"
- },
- "time": {
- "type": "number"
- },
- "timeoutBreakdown": {
- "additionalProperties": false,
- "properties": {
- "appliedMs": {
- "type": "number"
- },
- "baseMs": {
- "type": "number"
- },
- "calls": {
- "items": {
- "additionalProperties": false,
- "properties": {
- "computed": {
- "const": true,
- "type": "boolean"
- },
- "method": {
- "type": "string"
- },
- "weight": {
- "type": "number"
- }
- },
- "required": [
- "method",
- "weight"
- ],
- "type": "object"
- },
- "type": "array"
- },
- "coldStartGraceMs": {
- "type": "number"
- },
- "estimatedMs": {
- "type": "number"
- },
- "parallelismFactor": {
- "type": "number"
- },
- "warnings": {
- "items": {
- "type": "string"
- },
- "type": "array"
- }
- },
- "required": [
- "baseMs",
- "calls",
- "parallelismFactor",
- "estimatedMs",
- "coldStartGraceMs",
- "appliedMs",
- "warnings"
- ],
- "type": "object"
- }
-}Output schema / requiredRemoved value: -[
- "success"
-]v1.2.4code_intel2 fields changedOutput schema / properties / timeoutBreakdown / properties / coldStartGraceMsAdded value: +{
+ "type": "number"
+}Output schema / properties / timeoutBreakdown / requiredPrevious value: -[
- "baseMs",
- "calls",
- "parallelismFactor",
- "estimatedMs",
- "appliedMs",
- "warnings"
-]New value: +[
+ "baseMs",
+ "calls",
+ "parallelismFactor",
+ "estimatedMs",
+ "coldStartGraceMs",
+ "appliedMs",
+ "warnings"
+]v1.2.1code_intelv1.2.0code_intelScored across 1 tool
With a single tool, there is no cross-tool ambiguity to resolve, and the description explicitly draws a clear boundary against Grep/Glob/Read (structure vs text search). The only residual overlap is internal (getDependents vs getCallGraph vs traceSymbolUsage), which the description addresses but does not fully resolve without running api.listMethods().
A single name cannot be internally inconsistent, and 'code_intel' is a clean, readable snake_case identifier. It is a noun phrase rather than a verb_noun pattern, so there is no predictable action convention to anchor on, but nothing is violated.
The one-tool design is intentional (a code-execution entry point fronting a multi-method api.* surface), which is defensible for this domain. However, as presented the server exposes exactly one thinly-described tool whose real capabilities are hidden behind api.listMethods()/api.help(), making the surface feel thin and requiring a discovery round-trip.
The stated domain ā graph-backed code intelligence ā is well covered: symbol search, dependencies/dependents, call graph, usage tracing, impact analysis, orphan detection, and architecture overview. Gaps are minor (e.g. no explicit symbol-level diff/change-scope or test-impact mapping), and read-only scope is appropriate for an intelligence tool.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Codebase intelligence for AI agents ā dead code, blast radius, ownership.
Codebase knowledge graph ā architectural awareness for AI coding agents via MCP
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
