code-prism 0.2.2
Code Prism - MCP server for intelligent codebase exploration with multi-LLM support and dependency analysis
Requires Python: >=3.11
Keywords: mcp, codebase, analysis, dependencies, ai, claude

# Prism - AI-Powered Codebase Explorer

![Prism - Refracting code into structured dependencies](prism.jpg)

**Give AI the bird's eye view it's missing.** Prism is an MCP server that helps AI assistants like Claude Code understand codebases from the top down, not the bottom up.

## The Problem: Tunnel Vision

When AI explores code, it sees files in isolation. It reads one file, then another, then another - like looking at a city through a drinking straw. Each file loads into context separately, with no map showing how they connect.

Import statements are buried in the code as text. The AI has to mentally parse "from auth import login" and guess where auth.py is, what it does, and how the pieces fit together.

This leads to:
- **Fragmented understanding** - Knows individual components but not the system
- **Missed context** - Doesn't see what calls what, or why something exists
- **Wrong assumptions** - Guesses at architecture from code alone instead of seeing the actual structure
- **Inefficient exploration** - Reads the wrong files, misses the important ones
- **Sequential bottleneck** - Can only ask one question at a time, losing the bigger picture

## The Solution: Hierarchical Understanding

Prism gives AI a **lens that zooms out** by building a dependency graph of your entire codebase. It analyzes import statements to create two indexes:

- **Forward index**: what each file imports (dependencies)
- **Reverse index**: what files import it (dependents)

This graph is built once and cached, making all lookups instant. Now AI can:

1. **See the big picture** - Load entire subsystems (file + all dependencies) into context at once
2. **Follow the flow** - Trace execution paths through the actual dependency graph, not guesswork
3. **Think hierarchically** - Start with architecture maps, then drill down with full context
4. **Navigate intelligently** - Know which files matter because it sees the connections

Instead of reading files randomly, AI gets **structural wisdom first, then specifics**. It's not searching for code—it's exploring a mapped system.

## Macro → Micro Exploration

Prism enables a natural exploration flow by creating **snapshots** - bundles of related code with their dependency maps:

**Macro Level (Bird's Eye View)**
- "Show me the overall architecture"
- "What are the main components and how do they interact?"
- "Where does authentication fit in the system?"

*Prism loads a high-level snapshot with entry points + system overview into AI context*

**Middle Level (Connections)**
- "What files handle user authentication?"
- "How does data flow from API to database?"
- "Which components depend on this module?"

*Prism creates a focused snapshot: target file + all parents (who imports it) + all children (what it imports)*

**Micro Level (Implementation)**
- "Show me the actual login function"
- "What's the specific error handling logic?"
- "Read the complete source for these 3 files"

*AI already has full context from the snapshot and can ask multiple detailed questions in parallel*

At each level, the dependency graph tells AI **exactly what to look at next** for deeper understanding.

## Quick Install for Claude Code

### Step 1: Get an API Key (30 seconds)

Pick a provider and grab an API key:

| Provider | Speed | Quality | Cost | Sign Up |
|----------|-------|---------|------|---------|
| **Groq** ⚡ | Fastest | Good | Free (1M tokens/day) | [console.groq.com](https://console.groq.com) |
| **Cerebras** | Very Fast | Good | Free (1M tokens/day) | [inference.cerebras.ai](https://inference.cerebras.ai) |
| **DeepSeek** | Fast | Excellent | $0.14/1M tokens | [platform.deepseek.com](https://platform.deepseek.com) |
| **Anthropic** | Medium | Best | $3/1M tokens | [console.anthropic.com](https://console.anthropic.com) |
| **OpenAI** | Medium | Excellent | $2.50/1M tokens | [platform.openai.com](https://platform.openai.com) |

**Quick start with Groq (free):**
```bash
export GROQ_API_KEY="gsk-..."
```

### Step 2: Install Prism

Add to `~/.claude/config.json`:

```json
{
  "mcpServers": {
    "prism": {
      "command": "uvx",
      "args": ["code-prism"],
      "env": {
        "GROQ_API_KEY": "gsk-..."
      }
    }
  }
}
```

**Or use Claude's built-in command:**
```bash
claude mcp add prism --env GROQ_API_KEY=gsk-... -- uvx code-prism
```

Done! Prism auto-detects your provider (free providers first) and works across all your projects.

## How It Works

Prism transforms isolated file reading into **structural exploration** through dependency-aware snapshots:

### 🎯 Structural Understanding
The dependency graph shows AI how your codebase is organized:
- What are the entry points (where execution begins)?
- Which files import this module? (via reverse index)
- What does this file depend on? (via forward index)
- How does code flow from user request to response? (traced through the graph)

Traditional AI: reads files one-by-one, guesses at connections
**Prism AI**: sees the dependency map, knows the actual architecture

### 🧠 AI-Powered Analysis with Full Context
When you query a file, Prism bundles it with all related code into one snapshot:
- Target file + all parents + all children + dependency relationships
- Entire bundle loaded into AI context in one shot
- AI can now ask 5-10 questions in parallel about the same context

Ask high-level questions and get architectural answers:
- "How does authentication work in this system?"
- "Where is caching implemented and why?"
- "What's the error handling strategy?"
- "How do these components communicate?"

The AI traces through actual code flow in the snapshot, not guesses.

### 📚 Smart File Recommendations
Instead of guessing which files to read, AI gets guidance from the graph:
- See code snippets in context of their dependencies
- Get ranked list of files that answer your question
- Choose to read full source only for what matters
- Suggestions based on actual imports, not keyword matching

### 🗺️ Multiple Exploration Modes
Different tools for different levels of understanding:
- **Query the structure** - Instant dependency lookups (no AI needed)
- **Ask questions** - Load snapshot + ask in parallel (bulk context)
- **Read strategically** - Only dive deep where the graph says it matters

## Example Workflows

### Understanding a New Codebase
```
You: "I need to understand how authentication works"
Claude uses Prism to:
1. Map out auth-related files and their relationships
2. Explain the high-level authentication flow
3. Identify the 3-4 key files you should read
4. Show you those files with full context
```

### Debugging a Complex Issue
```
You: "Users are getting intermittent 500 errors on checkout"
Claude uses Prism to:
1. Trace the checkout flow from API to database
2. Identify error handling at each layer
3. Find where exceptions might go unhandled
4. Point you to the specific problematic code
```

### Planning a Feature
```
You: "I want to add rate limiting"
Claude uses Prism to:
1. Show where API requests are handled
2. Identify existing middleware patterns
3. Find similar features (like auth) for reference
4. Suggest where rate limiting should be inserted
```

## What Makes Prism Different

**Traditional code search:** Find where "login" appears → read all those files → try to piece together understanding

**Prism approach:** Query authentication system → get snapshot (auth.py + all dependencies + graph) → ask 5 questions in parallel → understand the architecture

It's the difference between:
- **Bottom-up** (random access, tunnel vision, local understanding)
  - Read file A, then file B, then file C sequentially
  - AI guesses how they connect based on code alone
  - Context window fills with isolated code snippets

- **Top-down** (hierarchical, bird's eye view, global understanding)
  - Load snapshot: A + B + C + dependency map in one context
  - AI sees explicit connections via the graph
  - Ask multiple architectural questions in parallel
  - Dependency graph turns implicit imports into explicit structural knowledge


### LLM Provider Configuration

**All Supported Providers:**

| Provider | Env Variable | Default Model | Notes |
|----------|-------------|---------------|-------|
| **Groq** | `GROQ_API_KEY` | `llama-3.3-70b-versatile` | Free, fastest |
| **Cerebras** | `CEREBRAS_API_KEY` | `llama-3.3-70b` | Free |
| **SambaNova** | `SAMBANOVA_API_KEY` | `Meta-Llama-3.1-70B-Instruct` | Free tier |
| **DeepSeek** | `DEEPSEEK_API_KEY` | `deepseek-chat` | Cheap, excellent |
| **Anthropic** | `ANTHROPIC_API_KEY` | `claude-sonnet-4-20250514` | Best quality |
| **OpenAI** | `OPENAI_API_KEY` | `gpt-4o` | Excellent |
| **Google** | `GEMINI_API_KEY` | `gemini-2.0-flash-exp` | Fast |
| **xAI** | `XAI_API_KEY` | `grok-2-latest` | Large context |
| **Mistral** | `MISTRAL_API_KEY` | `mistral-large-latest` | EU-based |
| **Cohere** | `COHERE_API_KEY` | `command-r-plus` | Enterprise |
| **Perplexity** | `PERPLEXITYAI_API_KEY` | `llama-3.1-sonar-large-128k-online` | Online search |
| **Together AI** | `TOGETHERAI_API_KEY` | `meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo` | Many models |
| **Fireworks** | `FIREWORKS_AI_API_KEY` | `accounts/fireworks/models/llama-v3p1-70b-instruct` | Fast inference |
| **OpenRouter** | `OPENROUTER_API_KEY` | Any model | Meta-aggregator |
| **Replicate** | `REPLICATE_API_KEY` | Various | Community models |

**Cloud Providers:**
- **Azure OpenAI**: `AZURE_API_KEY`, `AZURE_API_BASE`, `AZURE_API_VERSION`
- **AWS Bedrock**: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION_NAME`
- **Google Vertex AI**: `GOOGLE_APPLICATION_CREDENTIALS`, `VERTEXAI_PROJECT`, `VERTEXAI_LOCATION`

**Custom Configuration:**
```bash
export PRISM_LLM_PROVIDER="groq"           # Override auto-detection
export PRISM_LLM_MODEL="llama-3.3-70b"     # Use specific model
export PRISM_PROJECT_ROOT="/path/to/code"  # Override project path
```

**Auto-Detection:** Just set an API key - Prism tries free providers first, then paid. See [LLM_SETUP.md](LLM_SETUP.md) for detailed setup.

### Multi-Project Support

The MCP server is installed **globally** but works with **multiple projects**:

- Each Claude Code session runs in its working directory (e.g., your project folder)
- Prism uses the current working directory as the project root
- Config and cache are stored in `{working_directory}/.zdeps_cache/`
- Multiple agents can run simultaneously, each analyzing their own project
- No conflicts between different projects

**Example**: If you have Claude Code open in `/Users/you/project-a` and `/Users/you/project-b`, each gets:
- Separate config: `/Users/you/project-a/.zdeps_cache/config.json` and `/Users/you/project-b/.zdeps_cache/config.json`
- Separate cache: `/Users/you/project-a/.zdeps_cache/semantic_cache.json` and `/Users/you/project-b/.zdeps_cache/semantic_cache.json`
- One shared MCP server handling both

**Advanced**: You can manually override the project root with `PRISM_PROJECT_ROOT` environment variable if needed, but this is not necessary for Claude Code users.

## Tools Available to AI

Prism exposes these capabilities:

- **`query_codebase`** - Explore any part of the codebase with AI understanding
- **`query_snapshot_batch`** - Ask multiple related questions at different levels
- **`preview_snapshot`** - Check scope before exploring (how many files, tokens, etc.)
- **`get_dependency_info`** - Quick lookup of structural relationships
- **`list_entry_points`** - See where execution begins in your project

## Features

### 🔍 Hierarchical Exploration
Understand systems from top to bottom:
- Start with architecture and patterns
- Drill down through layers
- See connections between components
- Follow execution flows

### 🤖 Intelligent Questioning
Ask conceptual questions, get architectural answers:
- No need to know file names
- Focus on what/how/why, not where
- Get explanations with supporting code
- Understand patterns across the codebase

### ⚡ Exploration Efficiency
Don't read everything, read what matters:
- AI learns which files are important
- Skip boilerplate and focus on logic
- Get recommendations at each level
- Build understanding incrementally

### 📁 Context-Aware File Reading
When you do read files, understand why they matter:
- See how files fit in the bigger picture
- Understand what calls them and what they call
- Know their role in the architecture
- Read with full context, not in isolation

### 🌐 Flexible LLM Support
Works with any LLM provider you choose:
- **Free options**: Groq, Cerebras, SambaNova (no credit card!)
- **Paid options**: Claude, GPT-4o, Gemini, Grok, and 10+ more
- **Auto-detection**: Just set an API key, Prism handles the rest
- **Local support**: Run Ollama for 100% private, offline analysis

## Supported Languages

Currently optimized for Python projects. The structural analysis works for any language, but AI-powered understanding is best with Python.