Dep Scope

dep-scope

[CI] [npm version] [MCP Registry] [License: MIT] [Node.js]

Symbol-level dependency analysis + LLM-ready migration prompts for TypeScript/JavaScript projects.

"Knip tells you what's unused. dep-scope tells you how you use what you keep, and generates the prompt to remove it."

When to use dep-scope

Good use cases:

• Legacy project audit: Finding lodash functions that now have native equivalents
• Library consolidation: Do we really need 3 icon libraries?
• Migration: Generate a context-aware prompt and let Claude Code do the refactoring
• Curiosity: "Which symbols from this 50KB library do we actually use?"

Not the right tool if:

• You just want unused deps → use Knip instead
• Your codebase is already well-maintained → dep-scope will mostly say "KEEP"

Quick Example

$ dep-scope scan
═══════════════════════════════════════════  dep-scope Analysis Report═══════════════════════════════════════════
Summary:  Total dependencies: 45  ✓ Keep:          38  ↻ Recode Native: 3  ✗ Remove:        2  ⊕ Peer Dep:      4
Action Items:  Remove (unused):    ✗ moment    ✗ has-flag
  Recode to native:    ↻ lodash.debounce (1 symbol) → custom debounce function    ↻ array-includes (1 symbol) → Array.prototype.includes    ↻ left-pad (1 symbol) → String.prototype.padStart

How it compares

Recommendation: Use Knip for unused detection, dep-scope for deeper analysis and migration. They work well together (dep-scope auto-detects Knip if installed).

Installation

CLI (global):

npm install -g @florianbruniaux/dep-scope

Without installation:

npx @florianbruniaux/dep-scope scan

MCP Server (AI editors — no CLI needed):

Add to your editor's MCP config and the server runs on demand via npx. See the MCP Server section below for per-editor config snippets.

From source:

git clone https://github.com/FlorianBruniaux/node-dep-scope.gitcd node-dep-scopenpm install && npm run build && npm install -g .

Quick Start

cd /path/to/your/project
dep-scope init                        # configure dep-scope for your project (interactive)dep-scope scan                        # full scandep-scope scan --root                 # scan full project, including scripts/ tools/ bin/dep-scope scan --check-duplicates     # include duplicate detectiondep-scope scan --check-transitive     # surface transitive polyfills (e18e database)dep-scope scan --each-workspace       # monorepo: scan each package individuallydep-scope migrate                     # generate migration prompts for all candidatesdep-scope migrate lodash              # target a specific packagedep-scope report -o ./audit.md        # markdown report

Setup: dep-scope init

Run dep-scope init before your first scan. The wizard detects your project and generates a config in 4 questions:

dep-scope init
  Detected: Next.js project  Found dirs: src/, scripts/, app/
? Source directories to scan:  ● Auto-detected: src/, scripts/, app/  (recommended)  ○ Full project root (.) — includes everything  ○ Choose directories manually...
? Include devDependencies in scan? (y/N)? Symbol threshold for RECODE_NATIVE verdict: (5)? Config format:  ● .depscoperc.json  (simple JSON, recommended)  ○ depscope.config.ts  (TypeScript with autocomplete)
✓ Created .depscoperc.json  Preset: react  |  Dirs: src, scripts, app  |  Threshold: 5

Use -y to skip prompts in CI: dep-scope init --yes.

Getting accurate results

Auto-detection covers: src, app, lib, pages, components, hooks, server, scripts, tools, bin, cli. If your project has code elsewhere, pass --root to scan everything, or set srcPaths explicitly in .depscoperc.json:

{  "srcPaths": ["src", "app", "scripts", "tools"]}

False positive "unused" verdict? The package may be used in a directory outside the scan scope (scripts/, tools/, etc.). Run dep-scope scan --root to verify before removing anything. When a removal recommendation appears with a narrow scan scope, dep-scope will warn you.

Config file detection

dep-scope automatically scans config files at the project root to avoid false "unused" verdicts for packages referenced as strings — a common pattern for CLI tools, test runners, and framework plugins.

Detected automatically:

These packages will appear as INVESTIGATE (or KEEP if well-used) rather than REMOVE.

Opt-out — disable specific detectors in .depscoperc.json:

{  "stringReferences": {    "disable": ["storybook-config"]  }}

Available detector IDs: package-json-scripts, vitest-config, vite-config, next-config, storybook-config. Use "disable": "all" to turn off config scanning entirely.

Extend with custom detectors — in depscope.config.ts:

import { defineConfig, defineDetector } from "@florianbruniaux/dep-scope";
export default defineConfig({  stringReferences: {    detectors: [      defineDetector({        id: "my-tool-config",        label: "my-tool.config.json",        filePatterns: ["my-tool.config.json"],        async detect(filePath, ctx) {          // return StringReference[] for packages found in this file          return [];        },      }),    ],  },});

MCP Server

dep-scope exposes a Model Context Protocol server so AI editors (Claude Code, Cursor, Windsurf) can query your dependencies inline — no CLI, no markdown files, no copy-paste.

Listed on the official MCP Registry: io.github.FlorianBruniaux/dep-scope

Available tools

Setup

Add the following mcpServers entry to your editor's config. The server runs on demand via npx — no global install required.

Claude Code — ~/.claude.json:

{  "mcpServers": {    "dep-scope": {      "command": "npx",      "args": ["--package=@florianbruniaux/dep-scope", "-y", "dep-scope-mcp"]    }  }}

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json:

{  "mcpServers": {    "dep-scope": {      "command": "npx",      "args": ["--package=@florianbruniaux/dep-scope", "-y", "dep-scope-mcp"]    }  }}

Cursor — ~/.cursor/mcp.json:

{  "mcpServers": {    "dep-scope": {      "command": "npx",      "args": ["--package=@florianbruniaux/dep-scope", "-y", "dep-scope-mcp"]    }  }}

Windsurf — ~/.codeium/windsurf/mcp_config.json:

{  "mcpServers": {    "dep-scope": {      "command": "npx",      "args": ["--package=@florianbruniaux/dep-scope", "-y", "dep-scope-mcp"]    }  }}

Once connected, you can ask your AI editor to call scan_project or generate_migration_prompt directly mid-session without running any CLI command.

Documentation

• Commands reference
• Configuration
• AI prompts + Claude Code slash command
• MCP Server setup
• Programmatic API
• Architecture & internals

Requirements

• Node.js >= 18.0.0
• TypeScript/JavaScript project with package.json

Explore the ecosystem

These projects extend the workflow without duplicating this tool:

• Automate with claude-code-plugins: add symbol-level dependency analysis to code-quality workflows.
• Learn with Claude Code Ultimate Guide: choose between CLI and MCP and frame the quality check.

Browse the complete open-source galaxy

License

MIT