# constellation [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/ShiftinBits/constellation-mcp  
**GitHub Stars:** 3  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/constellation

## Description
Code Intelligence Platform for AI Coding Assistants

## Tools
Capabilities this server exposes over MCP:

- **code_intel** — 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.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

**Requires environment variables:** `CONSTELLATION_ACCESS_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation & README

# Constellation MCP Server

[![NPM Version](https://img.shields.io/npm/v/@constellationdev/mcp?logo=npm&logoColor=white)](https://www.npmjs.com/package/@constellationdev/mcp) ![TypeScript v5.9+](https://img.shields.io/badge/TypeScript-v5.9%2B-3178C6.svg?logo=typescript&logoColor=white) ![Node.js v24+](https://img.shields.io/badge/Node.js-v24%2B-5FA04E.svg?logo=node.js&logoColor=white) [![MCP Badge](https://lobehub.com/badge/mcp/shiftinbits-constellation-mcp?style=flat)](https://lobehub.com/mcp/shiftinbits-constellation-mcp) [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-3DA639?logo=opensourceinitiative&logoColor=white)](LICENSE) [![Snyk Monitored](https://img.shields.io/badge/Security-Monitored-8A2BE2?logo=snyk)](https://snyk.io/test/github/ShiftinBits/constellation-mcp)

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.

## Quick Start

Add the Constellation MCP server to your AI assistant project-level config (or system-level if your tooling doesn't support project-level configuration):

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

> [!NOTE]  
> 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](https://docs.constellationdev.io/plugins/) for optimal performance and behavior!
>
> For information on configuring other AI assistants see the [MCP Server > Installation doc](https://docs.constellationdev.io/mcp/#installation).

For further instructions regarding authentication, project setup, and configuration refer to the [official docs](https://docs.constellationdev.io/).

## How It Works

```mermaid
%%{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:#4A90E2
```

1. **Parse and Analyze**: The CLI tool analyzes source code in **_your_** environment, extracting structural metadata (functions, classes, variables, imports, calls, references, etc.)
2. **Upload**: Only the metadata is securely sent to Constellation, never raw source code
3. **Query**: AI assistants use the Constellation MCP tool to send complex queries, and get rapid answers derived from the knowledge graph

## Documentation

Find the full and comprehensive documentation at **[docs.constellationdev.io/mcp/](https://docs.constellationdev.io/mcp/)**

- [Installation & Setup](https://docs.constellationdev.io/mcp/#installation) - Configure for Claude Code, Cursor, GitHub Copilot, and more
- [Tools Reference](https://docs.constellationdev.io/mcp/tools) - Code Mode API and available methods
- [Troubleshooting](https://docs.constellationdev.io/mcp/troubleshooting) - Common issues and solutions

## Privacy & Security

- **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](https://docs.constellationdev.io/privacy-security) and the [Privacy Policy](https://constellationdev.io/privacy).

## Support

- Documentation: [docs.constellationdev.io](https://docs.constellationdev.io)
- Report Issues: [GitHub Issues](https://github.com/shiftinbits/constellation-mcp/issues)

## License

AGPL-3.0 - See [LICENSE](https://github.com/ShiftinBits/constellation-mcp/blob/HEAD/LICENSE) for details.

Copyright © 2026 ShiftinBits Inc.