@ulpi/codemap — Code intelligence for any codebase

Features

Everything you need to understand, navigate, and search your codebase.

Hybrid Search

Combines vector similarity with BM25 keyword scoring for accurate, context-aware code search across your entire project.

Example

$ codemap search "auth middleware"

Key capabilities

Vector similarity scoring

BM25 keyword matching

Symbol name boosting

Graph rank integration

Configurable result limits

MCP Integration

codemap serve starts an MCP server exposing 12 code intelligence tools to any compatible AI agent or editor.

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "codemap": {
      "command": "codemap",
      "args": ["serve"]
    }
  }
}

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

{
  "mcpServers": {
    "codemap": {
      "command": "codemap",
      "args": ["serve"],
      "type": "stdio"
    }
  }
}

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "codemap": {
      "command": "codemap",
      "args": ["serve"]
    }
  }
}

Add to .kiro/settings/mcp.json in your project root:

{
  "mcpServers": {
    "codemap": {
      "command": "codemap",
      "args": ["serve"]
    }
  }
}

Add to .vscode/mcp.json in your project root:

{
  "servers": {
    "codemap": {
      "command": "codemap",
      "args": ["serve"],
      "type": "stdio"
    }
  }
}

Settings > Tools > AI Assistant > MCP Servers:

{
  "mcpServers": {
    "codemap": {
      "command": "codemap",
      "args": ["serve"]
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "codemap": {
      "command": "codemap",
      "args": ["serve"]
    }
  }
}

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "codemap": {
      "command": {
        "path": "codemap",
        "args": ["serve"]
      }
    }
  }
}

12 MCP Tools

search_code

Search code using hybrid vector + BM25 scoring. Returns ranked results with file paths, line numbers, and matching snippets.

Parameters

{"query": "authentication middleware", "limit": 10}

Capabilities

Natural language queries

Hybrid vector + BM25

Configurable result limit

Project directory override

Ranked by relevance

search_symbols

Find functions, classes, types, and interfaces by name pattern. Fast symbol-level lookup across the index.

Parameters

{"query": "UserService", "limit": 20}

Capabilities

Function definitions

Class declarations

Type aliases

Pattern matching

Configurable limits

get_file_summary

Inspect

Get a file overview including exported symbols, size, and structure. Understand a file without reading it.

Parameters

{"filePath": "src/routes/auth.ts"}

Capabilities

Symbol inventory

File size metrics

Export enumeration

Quick file overview

Repo-relative paths

get_index_stats

Inspect

Get statistics about the code search index: total files, chunks, staleness, size, and last update time.

Parameters

{}

Capabilities

Total file count

Chunk count

Stale file detection

Index size (bytes)

Last update timestamp

reindex

Index

Trigger a full re-index of the project. Scans files, generates embeddings, and rebuilds the search index.

Parameters

{}

Capabilities

Full project scan

AST-aware chunking

Embedding generation

BM25 index rebuild

Dependency extraction

get_dependencies

Graph

Get files this file imports (outgoing edges). Trace what a file depends on.

Parameters

{"filePath": "src/index.ts"}

Capabilities

Import tracing

Outgoing edges

Direct dependencies

Cross-file resolution

Tree-sitter parsing

get_dependents

Graph

Get files that import this file (incoming edges). See what breaks if you change it.

Parameters

{"filePath": "src/utils/db.ts"}

Capabilities

Reverse import lookup

Incoming edges

Impact analysis

Change risk assessment

Full dependent tree

get_file_rank

Graph

Get PageRank importance scores. Without a file argument, returns the top-ranked files in the project.

Parameters

{"limit": 20}

Capabilities

PageRank algorithm

Top-N file ranking

Single file scoring

Architecture insights

Connectivity analysis

find_cycles

Graph

Detect circular dependencies in the codebase. Returns full cycle paths for resolution.

Parameters

{}

Capabilities

Circular dependency detection

Full cycle paths

Multi-file cycles

Actionable output

Build safety

get_coupling_metrics

Graph

Analyze afferent/efferent coupling and instability per file. Filter by module path.

Parameters

{"modulePath": "src/routes/"}

Capabilities

Afferent coupling (Ca)

Efferent coupling (Ce)

Instability index

Module filtering

Top-N results

get_depgraph_stats

Graph

Get aggregate dependency graph statistics: total nodes, edges, density, and connected components.

Parameters

{}

Capabilities

Node count

Edge count

Graph density

Connected components

Overview metrics

rebuild_depgraph

Index

Recompute PageRank scores and dependency metrics from the current graph data.

Parameters

{}

Capabilities

PageRank recomputation

Coupling recalculation

Cycle re-detection

Metric refresh

Graph rebuild

Provider	Models	Cost	Requires
ULPI Cloud Default	`qwen3-embedding:4b` (2048d)	Managed	`ULPI_API_KEY`
Ollama	`nomic-embed-text` `mxbai-embed-large` `all-minilm`	Free	Ollama running locally
OpenAI	`text-embedding-3-small` `text-embedding-3-large`	Paid	`OPENAI_API_KEY`

CLI Commands

Full command reference. All commands support --cwd, --json, and --help.

codemap init

Interactive first-time setup — provider, model, API key

codemap index

Index the current project for code search

codemap search <query>

Search code with hybrid vector + BM25 scoring

codemap symbols <query>

Find functions, classes, and types by name

codemap status

Show index statistics for the current project

codemap watch

Watch for file changes and re-index in real-time

codemap deps <file>

Show files this file depends on

codemap dependents <file>

Show files that depend on this file

codemap rank [file]

Show PageRank importance scores

codemap cycles

Detect circular dependencies

codemap config

Get, set, or list configuration values

codemap serve

Start MCP server over stdio

Code intelligence
for any codebase

Features

Hybrid Search

Symbol Lookup

Dependency Graph

PageRank

Cycle Detection

Coupling Metrics

Real-time Watching

MCP Server

Per-branch Indexing

Multiple Providers

MCP Integration

12 MCP Tools

search_code

search_symbols

get_file_summary

get_index_stats

reindex

get_dependencies

get_dependents

get_file_rank

find_cycles

get_coupling_metrics

get_depgraph_stats

rebuild_depgraph

Embedding Providers

CLI Commands

Get started in seconds