{ "markdown": "# dep-scope\n\n\n \n \n \n \n
\n \"Florian\n \n Florian BRUNIAUX · AI Founding Engineer @ Méthode Aristote
\n 13 years from developer to CTO / VP Eng · Blog ↗ · Projects ↗\n
\n\n[![CI](https://github.com/FlorianBruniaux/node-dep-scope/actions/workflows/ci.yml/badge.svg)](https://github.com/FlorianBruniaux/node-dep-scope/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/@florianbruniaux/dep-scope.svg)](https://www.npmjs.com/package/@florianbruniaux/dep-scope)\n[![MCP Registry](https://img.shields.io/badge/MCP-registry.modelcontextprotocol.io-6366f1)](https://registry.modelcontextprotocol.io)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)\n\n**Symbol-level dependency analysis + LLM-ready migration prompts** for TypeScript/JavaScript projects.\n\n> *\"Knip tells you what's unused. dep-scope tells you how you use what you keep, and generates the prompt to remove it.\"*\n\n## When to use dep-scope\n\n**Good use cases:**\n- **Legacy project audit**: Finding lodash functions that now have native equivalents\n- **Library consolidation**: Do we really need 3 icon libraries?\n- **Migration**: Generate a context-aware prompt and let Claude Code do the refactoring\n- **Curiosity**: \"Which symbols from this 50KB library do we actually use?\"\n\n**Not the right tool if:**\n- You just want unused deps → use [Knip](https://knip.dev) instead\n- Your codebase is already well-maintained → dep-scope will mostly say \"KEEP\"\n\n## Quick Example\n\n```bash\n$ dep-scope scan\n\n═══════════════════════════════════════════\n dep-scope Analysis Report\n═══════════════════════════════════════════\n\nSummary:\n Total dependencies: 45\n ✓ Keep: 38\n ↻ Recode Native: 3\n ✗ Remove: 2\n ⊕ Peer Dep: 4\n\nAction Items:\n Remove (unused):\n ✗ moment\n ✗ has-flag\n\n Recode to native:\n ↻ lodash.debounce (1 symbol) → custom debounce function\n ↻ array-includes (1 symbol) → Array.prototype.includes\n ↻ left-pad (1 symbol) → String.prototype.padStart\n```\n\n## How it compares\n\n| Feature | Knip | Depcheck | Moderne | dep-scope |\n|---------|------|----------|---------|-----------|\n| Unused detection | ✅ Excellent | ✅ Good | ❌ | ⚠️ Basic |\n| Config file scanning | ✅ | ✅ | ❌ | ✅ |\n| Symbol-level analysis | ❌ | ❌ | ✅ | ✅ |\n| Native alternatives database | ❌ | ❌ | ✅ (lodash) | ✅ 195 packages |\n| e18e micro-utilities coverage | ❌ | ❌ | ❌ | ✅ |\n| Transitive graph analysis | ❌ | ❌ | ❌ | ✅ |\n| Monorepo workspace support | ⚠️ | ❌ | ❌ | ✅ |\n| Duplicate detection | ❌ | ❌ | ❌ | ✅ |\n| LLM migration prompt | ❌ | ❌ | ❌ | ✅ |\n| MCP Server (AI editors) | ❌ | ❌ | ❌ | ✅ |\n| OSS / free | ✅ | ✅ | ❌ enterprise | ✅ |\n\n**Recommendation**: Use Knip for unused detection, dep-scope for deeper analysis and migration. They work well together (dep-scope auto-detects Knip if installed).\n\n## Installation\n\n**CLI (global):**\n\n```bash\nnpm install -g @florianbruniaux/dep-scope\n```\n\n**Without installation:**\n\n```bash\nnpx @florianbruniaux/dep-scope scan\n```\n\n**MCP Server (AI editors — no CLI needed):**\n\nAdd to your editor's MCP config and the server runs on demand via npx. See the [MCP Server](#mcp-server) section below for per-editor config snippets.\n\n**From source:**\n\n```bash\ngit clone https://github.com/FlorianBruniaux/node-dep-scope.git\ncd node-dep-scope\nnpm install && npm run build && npm install -g .\n```\n\n## Quick Start\n\n```bash\ncd /path/to/your/project\n\ndep-scope init # configure dep-scope for your project (interactive)\ndep-scope scan # full scan\ndep-scope scan --root # scan full project, including scripts/ tools/ bin/\ndep-scope scan --check-duplicates # include duplicate detection\ndep-scope scan --check-transitive # surface transitive polyfills (e18e database)\ndep-scope scan --each-workspace # monorepo: scan each package individually\ndep-scope migrate # generate migration prompts for all candidates\ndep-scope migrate lodash # target a specific package\ndep-scope report -o ./audit.md # markdown report\n```\n\n## Setup: `dep-scope init`\n\nRun `dep-scope init` before your first scan. The wizard detects your project and generates a config in 4 questions:\n\n```\ndep-scope init\n\n Detected: Next.js project\n Found dirs: src/, scripts/, app/\n\n? Source directories to scan:\n ● Auto-detected: src/, scripts/, app/ (recommended)\n ○ Full project root (.) — includes everything\n ○ Choose directories manually...\n\n? Include devDependencies in scan? (y/N)\n? Symbol threshold for RECODE_NATIVE verdict: (5)\n? Config format:\n ● .depscoperc.json (simple JSON, recommended)\n ○ depscope.config.ts (TypeScript with autocomplete)\n\n✓ Created .depscoperc.json\n Preset: react | Dirs: src, scripts, app | Threshold: 5\n```\n\nUse `-y` to skip prompts in CI: `dep-scope init --yes`.\n\n## Getting accurate results\n\nAuto-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`:\n\n```json\n{\n \"srcPaths\": [\"src\", \"app\", \"scripts\", \"tools\"]\n}\n```\n\n> **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.\n\n## Config file detection\n\ndep-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.\n\n**Detected automatically:**\n\n| Config file | Examples detected |\n|---|---|\n| `package.json` scripts | `\"lint\": \"oxlint .\"`, `\"format\": \"oxfmt .\"` |\n| `vitest.config.*` | `environment: \"jsdom\"`, `setupFiles: [\"@testing-library/jest-dom\"]` |\n| `vite.config.*` | `plugins: [\"@vitejs/plugin-vue\"]` |\n| `next.config.*` | `turbo.rules[\"*.svg\"].loaders: [\"@svgr/webpack\"]` |\n| `.storybook/main.*` | `addons: [\"@storybook/addon-mcp\"]` |\n\nThese packages will appear as INVESTIGATE (or KEEP if well-used) rather than REMOVE.\n\n**Opt-out** — disable specific detectors in `.depscoperc.json`:\n\n```json\n{\n \"stringReferences\": {\n \"disable\": [\"storybook-config\"]\n }\n}\n```\n\nAvailable detector IDs: `package-json-scripts`, `vitest-config`, `vite-config`, `next-config`, `storybook-config`. Use `\"disable\": \"all\"` to turn off config scanning entirely.\n\n**Extend with custom detectors** — in `depscope.config.ts`:\n\n```ts\nimport { defineConfig, defineDetector } from \"@florianbruniaux/dep-scope\";\n\nexport default defineConfig({\n stringReferences: {\n detectors: [\n defineDetector({\n id: \"my-tool-config\",\n label: \"my-tool.config.json\",\n filePatterns: [\"my-tool.config.json\"],\n async detect(filePath, ctx) {\n // return StringReference[] for packages found in this file\n return [];\n },\n }),\n ],\n },\n});\n```\n\n## MCP Server\n\ndep-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.\n\n> Listed on the [official MCP Registry](https://registry.modelcontextprotocol.io): **`io.github.FlorianBruniaux/dep-scope`**\n\n### Available tools\n\n| Tool | Params | What it does |\n|---|---|---|\n| `scan_project` | `projectPath`, `srcPaths`, `threshold`, `includeDev`, `checkDuplicates`, `checkTransitive`, `withKnip` | Full dependency scan with verdicts |\n| `analyze_package` | `packageName`, `projectPath`, `srcPaths` | Symbol-level breakdown of one package |\n| `get_migration_candidates` | `projectPath` | List all RECODE_NATIVE + CONSOLIDATE packages |\n| `generate_migration_prompt` | `packageName`, `projectPath` | Generate a migration prompt inline |\n| `find_duplicates` | `projectPath` | Detect overlapping libraries |\n\n### Setup\n\nAdd the following `mcpServers` entry to your editor's config. The server runs on demand via `npx` — no global install required.\n\n**Claude Code** — `~/.claude.json`:\n\n```json\n{\n \"mcpServers\": {\n \"dep-scope\": {\n \"command\": \"npx\",\n \"args\": [\"--package=@florianbruniaux/dep-scope\", \"-y\", \"dep-scope-mcp\"]\n }\n }\n}\n```\n\n**Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"dep-scope\": {\n \"command\": \"npx\",\n \"args\": [\"--package=@florianbruniaux/dep-scope\", \"-y\", \"dep-scope-mcp\"]\n }\n }\n}\n```\n\n**Cursor** — `~/.cursor/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"dep-scope\": {\n \"command\": \"npx\",\n \"args\": [\"--package=@florianbruniaux/dep-scope\", \"-y\", \"dep-scope-mcp\"]\n }\n }\n}\n```\n\n**Windsurf** — `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"dep-scope\": {\n \"command\": \"npx\",\n \"args\": [\"--package=@florianbruniaux/dep-scope\", \"-y\", \"dep-scope-mcp\"]\n }\n }\n}\n```\n\nOnce connected, you can ask your AI editor to call `scan_project` or `generate_migration_prompt` directly mid-session without running any CLI command.\n\n## Documentation\n\n- [Commands reference](docs/commands.md)\n- [Configuration](docs/configuration.md)\n- [AI prompts + Claude Code slash command](docs/ai-prompts.md)\n- [MCP Server setup](#mcp-server)\n- [Programmatic API](docs/api.md)\n- [Architecture & internals](docs/architecture.md)\n\n## Requirements\n\n- Node.js >= 18.0.0\n- TypeScript/JavaScript project with `package.json`\n\n\n\n## Explore the ecosystem\n\nThese projects extend the workflow without duplicating this tool:\n\n- **Automate with [claude-code-plugins](https://github.com/FlorianBruniaux/claude-code-plugins)**: add symbol-level dependency analysis to code-quality workflows.\n- **Learn with [Claude Code Ultimate Guide](https://github.com/FlorianBruniaux/claude-code-ultimate-guide)**: choose between CLI and MCP and frame the quality check.\n\n[Browse the complete open-source galaxy](https://github.com/FlorianBruniaux#open-source-galaxy)\n\n\n## License\n\nMIT\n", "bytes": 11128, "sha": "744489b5986d196f1c19a73080489ff127e178eded22ec381b20278a6e6e6828", "repo_slug": "florianbruniaux/node-dep-scope", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_florianbruniaux_dep_scope_fbcd7714/readme" }