Dependency Context MCP Server

An MCP (Model Context Protocol) server that provides AI coding assistants with context about project dependencies by reading directly from node_modules. Solves the "dependency blindness" problem with zero network calls and no external service dependencies.

The Problem

AI coding assistants don't know what's in your node_modules. When you ask "how do I use zod for validation?", they either hallucinate outdated APIs or give generic advice. This MCP server gives them full visibility into your actual installed dependencies.

Features

• Local-First Architecture: Reads dependency metadata and types directly from node_modules
• Type Extraction: Parses .d.ts files using TypeScript compiler API to extract full public APIs
• Semantic Search (optional): Natural language search across all your dependencies using vector embeddings
• Caching: Generates compact API snapshots, cached locally and invalidated by version changes
• Handles Complex Packages: Follows re-exports, import-then-export patterns, and bundled/minified .d.ts files

Quick Start

No installation needed - MCP clients run it via npx:

1. Add to your MCP client config (see Configuration)
2. Point cwd to your project directory
3. Ask your AI about your dependencies

{
  "mcpServers": {
    "dep-context": {
      "command": "npx",
      "args": ["dep-context-mcp"],
      "cwd": "/path/to/your/project"
    }
  }
}

Then just ask:

"Show me the API for lodash" "How do I use fast-check for property testing?" "Search for functions that handle debouncing"

Available Tools

| Tool | Description | |------|-------------| | get_dependency_context | Get full API context for an installed dependency | | list_dependencies | List all dependencies with cache status | | refresh_dependency | Force regeneration of a dependency snapshot | | search_dependencies | Text-based search by name/description | | search_codebase | Semantic search across dependency APIs (auto-indexes on first use) | | get_index_status | Check vector index status | | get_package_relationships | Analyse package dependencies and relationships |

Semantic Search (Optional)

The basic tools work out of the box. For semantic search ("find functions that delay execution"), you need:

How It Works

• Auto-indexing: The first search_codebase call automatically indexes all production dependencies with type definitions
• Persistent: The index survives MCP restarts — no re-indexing on reconnect (requires ChromaDB or file-based storage)
• Incremental: Only new or updated packages are re-indexed when versions change

Option 1: Ollama (Recommended - Free & Local)

1. Install Ollama
2. Pull the embedding model:

   ollama pull nomic-embed-text

3. Enable in config:

   {
     "vectorSearch": {
       "enabled": true
     }
   }

This uses file-based storage by default - fine for small/medium projects (<50 packages). The entire index is rewritten on each update, so indexing many packages will be slow.

Option 2: Ollama + ChromaDB (Better Performance)

For larger projects, add ChromaDB for faster vector search and incremental updates.

Docker (recommended):

# Start ChromaDB container
docker run -d --name chromadb -p 8000:8000 chromadb/chroma

# Verify it's running
curl http://localhost:8000/api/v2/heartbeat

Docker Compose:

services:
  chromadb:
    image: chromadb/chroma
    ports:
      - "8000:8000"
    volumes:
      - chromadb_data:/chroma/chroma
volumes:
  chromadb_data:

Without Docker (pip):

pip install chromadb
chroma run --host localhost --port 8000

The MCP auto-detects ChromaDB on localhost:8000. No config changes needed - just start ChromaDB and reconnect the MCP.

To verify ChromaDB is being used, check the MCP logs for:

[dep-context] Using ChromaDB at http://localhost:8000

Option 3: OpenAI Embeddings

If you prefer OpenAI:

{
  "vector": {
    "enabled": true,
    "embedding": {
      "provider": "openai",
      "openai": {
        "apiKey": "${OPENAI_API_KEY}"
      }
    }
  }
}

The ${OPENAI_API_KEY} syntax references an environment variable - safe to commit to source control. Set the actual key in your environment or shell profile.

Alternatively, set the key directly (don't commit this):

"apiKey": "sk-your-actual-key"

Configuration

Create dep-context.config.json in your project root (all fields optional):

{
  "projectRoot": ".",
  "nodeModulesPath": "./node_modules",
  "cacheDir": "./.cache/dep-context",
  
  "extraction": {
    "includeReadme": true,
    "includeJsDoc": true,
    "includeExamples": true,
    "maxReadmeLength": 5000,
    "maxExamples": 10
  },
  
  "vectorSearch": {
    "enabled": false,
    "embedding": {
      "provider": "ollama",
      "ollama": {
        "baseUrl": "http://localhost:11434",
        "model": "nomic-embed-text"
      },
      "openai": {
        "apiKey": "${OPENAI_API_KEY}",
        "model": "text-embedding-3-small"
      }
    },
    "storage": {
      "type": "auto",
      "chromaHost": "http://localhost:8000"
    }
  }
}

Environment Variables

| Variable | Purpose | |----------|---------| | OPENAI_API_KEY | OpenAI API key (when using OpenAI embeddings) |

Use ${VAR_NAME} syntax in config to reference environment variables.

Variables can be set via:

• .env file in your project root (recommended - add to .gitignore)
• Shell environment / profile
• MCP client env config

Example .env:

OPENAI_API_KEY=sk-your-key-here

MCP Client Configuration

Important: This server needs to know which project to analyse. Specify the project path via cwd in your config.

Kiro

Why workspace-level config?

MCP configs can live in two places:

• User-level (~/.kiro/settings/mcp.json) — shared across all projects
• Workspace-level (.kiro/settings/mcp.json in your project) — project-specific

Since cwd must point to each project's root directory, configure this MCP at the workspace level. This way each project automatically uses its own node_modules.

Create .kiro/settings/mcp.json in your project root:

{
  "mcpServers": {
    "dep-context": {
      "command": "npx",
      "args": ["dep-context-mcp"],
      "cwd": "/path/to/your/project",
      "disabled": false,
      "autoApprove": [
        "list_dependencies", 
        "get_dependency_context", 
        "refresh_dependency", 
        "search_dependencies",
        "search_codebase",
        "get_index_status",
        "get_package_relationships"
      ]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "dep-context": {
      "command": "npx",
      "args": ["dep-context-mcp"],
      "cwd": "/path/to/your/project"
    }
  }
}

How to Use

Once configured, just ask your AI assistant naturally:

Basic queries (always work)

"Show me the API for lodash" "What functions does axios export?" "List all my dependencies"

Semantic search (requires Ollama or OpenAI)

"Find functions that handle rate limiting" "Search for validation utilities" "What can I use for debouncing?"

Package relationships

"What does axios depend on?" "Which packages depend on lodash?"

What You Get

When you ask about a dependency, the AI receives a comprehensive snapshot:

# lodash v4.17.21

A modern JavaScript utility library delivering modularity, performance & extras.

## Functions

### debounce
function debounce<T extends (...args: any) => any>(
  func: T,
  wait?: number,
  options?: DebounceSettings
): DebouncedFunc<T>

Creates a debounced function that delays invoking func...

### chunk
function chunk<T>(array: ArrayLike<T>, size?: number): T[][]

Creates an array of elements split into groups the length of size.

[... all exported functions, classes, interfaces, types ...]

Development

npm install
npm run build
npm test

Troubleshooting

Log Levels

Set the LOG_LEVEL environment variable to control verbosity:

| Level | What you'll see | |-------|-----------------| | error | Fatal errors only — service failures that prevent operation | | warn | Warnings — fallback storage activated, recoverable failures | | info | Lifecycle events — startup, connections, index loaded (default) | | debug | Operational state — configuration details, cache statistics | | trace | Everything — tool calls, timing, cache hits/misses, per-package indexing |

In your MCP config:

{
  "mcpServers": {
    "dep-context": {
      "command": "npx",
      "args": ["dep-context-mcp"],
      "cwd": "/path/to/your/project",
      "env": {
        "LOG_LEVEL": "trace"
      }
    }
  }
}

Example output at each level:

info (default):

[dep-context] [INFO] Dependency Context MCP Server v1.1.0
[dep-context] [INFO] © 2026 J Jarecsni (TARS & Cooper) | MIT | Build abc1234@main 2026-01-22 07:00:00Z
[dep-context] [INFO] Using Ollama embeddings (nomic-embed-text)
[dep-context] [INFO] Using ChromaDB at http://localhost:8000
[dep-context] [INFO] Index loaded from storage (12 packages, 847 chunks)
[dep-context] [INFO] Dependency Context MCP Server running

warn (when things degrade):

[dep-context] [WARN] Primary storage failed, switching to file-based fallback
[dep-context] [WARN] Failed to initialize from storage, starting fresh

trace (full detail):

[dep-context] [TRACE] Tool called: get_dependency_context {"packageName":"lodash"}
[dep-context] [TRACE] Cache miss, extracting types {"packageName":"lodash","version":"4.17.21"}
[dep-context] [TRACE] Type extraction complete {"functions":312,"classes":0,"interfaces":45,"types":89,"extractionMs":234}
[dep-context] [TRACE] Tool completed: get_dependency_context {"cached":false,"snapshotSize":45678,"durationMs":267}

Common Issues

"Package not found in node_modules"

• Ensure cwd in your MCP config points to the project root (where package.json lives)
• Run npm install to ensure dependencies are installed

"No TypeScript declarations found"

• The package doesn't ship .d.ts files
• Try installing @types/package-name if available

Vector search not working

• Check Ollama is running: curl http://localhost:11434/api/tags
• Check ChromaDB (if using): curl http://localhost:8000/api/v2/heartbeat
• Enable trace logging to see what's happening

Licence

MIT

Kiro Power

This project includes a Kiro Power definition in the power/ folder. To use it:

1. Copy the power/ folder to .kiro/powers/dep-context/ in your project
2. Edit mcp.json to update the paths to match your local setup

Note: The mcp.json contains hardcoded paths due to current Kiro limitations with environment variable expansion in power configs. You'll need to update these paths manually after copying.