dependency-buster

# dependency-buster > Universal dependency analyzer for any codebase • MCP Server implementations in TypeScript, Go, and Rust [](https://opensource.org/licenses/MIT) [](https://modelcontextprotocol.io) **Latest Release:** [v1.1.1](./RELEASE_NOTES.md) - Documentation Rendering Fixes (TypeScript & Go) 📖 **Documentation:** - [Release Notes](./RELEASE_NOTES.md) - What's new in v1.1.0 - [Changelog](./CHANGELOG.md) - Complete version history - [Roadmap](./ROADMAP.md) - Planned features (v2.0 includes auto-documentation updates) --- ## Features - **Universal Language Support** - Analyze PHP, JavaScript, TypeScript, Python, Go, Rust, Java, Ruby, C# and more - **Dependency Analysis** - Production & development dependency tracking with version resolution - **Security Auditing** - Vulnerability detection across package ecosystems - **License Compliance** - Track and verify dependency licenses for legal compliance - **Namespace Detection** - Code structure and module analysis - **Triple Implementation** - Choose TypeScript (easy), Go (fast), or Rust (fastest) - **Beautiful Dashboard** - Bauhaus-inspired visualization with charts and trees - **CLI Reports** - ASCII-styled terminal output for CI/CD pipelines --- ## Quick Start ### 1. Clone and Build ```bash git clone https://github.com/your-username/dependency-buster.git cd dependency-buster # Build all implementations ./build-all.sh ``` **Repository Selection:** The build script will prompt you to choose a test repository: ```bash # Interactive mode (will prompt) ./build-all.sh # Enter repository URL or press Enter for default (AzuraCast) # Non-interactive mode (uses environment variable) TEST_REPO_URL=https://github.com/myorg/myproject.git ./build-all.sh # Non-interactive mode (uses default) echo "" | ./build-all.sh # Pipes empty input to auto-select default ``` **Or build individually:** ```bash # TypeScript cd dpb-mcp-typescript && npm install && npm run build # Go cd dpb-mcp-go && make build # Rust cd dpb-mcp-rust && cargo build --release ``` ### 2. Run Analysis ```bash # Analyze current directory cd your-project /path/to/dependency-buster/dpb-benchmark/scripts/run-benchmark.sh . # Analyze specific project /path/to/dependency-buster/dpb-benchmark/scripts/run-benchmark.sh /path/to/project ``` ### 3. View Results ```bash # Open the generated dashboard open dpb-benchmark/dashboard/index.html # Or view terminal report (generated automatically) ``` --- ## Implementations | Implementation | Speed | Size | Best For | |----------------|-------|------|----------| | **TypeScript** | ★★★ | 0.01 MB | Quick setup, familiar ecosystem | | **Go** | ★★★★★ | 6 MB | Production workloads, Go shops | | **Rust** | ★★★★★ | 2.6 MB | Maximum performance, memory safety | ### Performance Benchmarks | Metric | TypeScript | Go | Rust | |--------|-----------|-----|------| | Startup Time | ~430ms | ~177ms | ~176ms | | Dependencies Analysis | ~570ms | ~164ms | ~140ms | | Namespace Detection | ~1160ms | ~389ms | ~381ms | | Security Audit | ~709ms | ~206ms | ~191ms | --- ## IDE Integration dependency-buster works with any MCP-compatible IDE or tool: ### Cursor IDE ```json { "mcpServers": { "dependency-buster": { "command": "node", "args": ["/path/to/dpb-mcp-typescript/build/server.js"] } } } ``` ### Claude Code CLI ```json { "dependency-buster": { "command": "/path/to/dpb-mcp-go/build/dpb-mcp" } } ``` ### Cline Extension ```json { "mcpServers": { "dependency-buster": { "command": "/path/to/dpb-mcp-rust/target/release/dpb-mcp" } } } ``` **See [IDE_INTEGRATION.md](./IDE_INTEGRATION.md) for complete setup instructions** --- ## Available Tools (15 Total) ### Core Analysis Tools | # | Tool | Description | |---|------|-------------| | 1 | `analyze_dependencies` | Comprehensive dependency analysis with production/dev breakdown and tree visualization | | 2 | `analyze_psr4` | PSR-4 autoloading analysis and namespace compliance validation | | 3 | `detect_namespaces` | Detect all namespaces and module structure in the codebase | | 4 | `analyze_namespace_usage` | Analyze usage of a specific namespace across the codebase | | 5 | `generate_dependency_graph` | Generate Mermaid diagram of dependency relationships | | 6 | `audit_security` | Audit dependencies for security vulnerabilities and outdated packages | | 7 | `analyze_licenses` | Analyze license distribution and compatibility across dependencies | | 8 | `find_circular_dependencies` | Find circular dependency chains in the package graph | | 9 | `analyze_multi_repo` | Analyze dependencies across multiple repositories | | 10 | `generate_comprehensive_docs` | Generate comprehensive markdown documentation for a repository | | 11 | `generate_mkdocs_docs` | Generate MkDocs-compatible documentation site with multi-file structure, navigation, and changelog | ### Tracking & AI Agent Tools | # | Tool | Description | |---|------|-------------| | 11 | `track_dependencies` | Create timestamped snapshot of dependencies for tracking changes over time | | 12 | `get_dependency_history` | Get dependency history with timestamps, recently added/updated, and stale packages | | 13 | `check_compliance` | Check dependencies for compliance issues (licenses, outdated, deprecated) | | 14 | `get_agent_suggestions` | Get structured suggestions for AI agents (Cursor, Cline, Claude Code) about dependency issues | ### MCP Tool Annotations All tools include enterprise annotations: ```typescript { readOnlyHint: true, // Doesn't modify files idempotentHint: true, // Same result on repeated calls cacheTtlSeconds: 300, // Cache results for 5 minutes tags: ["analysis", "dependencies", "security"] } ``` --- ## Architecture ``` dependency-buster/ ├── dpb-mcp-typescript/ # TypeScript implementation │ ├── src/ │ │ ├── server.ts # MCP server entry │ │ ├── tools/ # Analysis tools │ │ ├── errors.ts # Typed errors │ │ ├── annotations.ts # Tool annotations │ │ └── auth.ts # Authentication │ └── build/ │ ├── dpb-mcp-go/ # Go implementation │ ├── cmd/server/main.go │ └── pkg/ │ ├── mcp/ # MCP protocol │ └── analyzer/ # Analysis tools │ ├── dpb-mcp-rust/ # Rust implementation │ └── src/ │ ├── main.rs │ ├── mcp/ # MCP protocol │ └── analyzer/ # Analysis tools │ └── dpb-benchmark/ # Benchmark suite ├── scripts/run-benchmark.sh # Main runner ├── dashboard/index.html # Visualization └── results/ # Generated reports ``` --- ## Enterprise Features All implementations support: | Feature | Description | |---------|-------------| | **Typed Errors** | NotFoundError, ValidationError, AuthenticationError | | **Authentication** | Static tokens via `MCP_TOKEN` environment variable | | **HTTP Transport** | SSE streaming for remote access | | **Request Context** | Credentials and request tracking | | **Tool Annotations** | Caching, read-only hints, tags | ### Configuration ```bash # Enable authentication export MCP_AUTH_ENABLED=true export MCP_TOKEN=your-secret-token # Use HTTP transport export MCP_TRANSPORT=http export MCP_HTTP_PORT=3000 # Run server ./build/dpb-mcp ``` --- ## Dashboard The benchmark suite generates a beautiful Bauhaus-inspired dashboard: - **Performance Metrics** - Startup time, binary size, tool execution times - **Dependency Tree** - Interactive D3.js visualization - **Security Summary** - Vulnerability breakdown by severity - **License Matrix** - License distribution across packages - **Namespace Map** - Code structure visualization - **Smoke Tests** - Run tests directly from the dashboard ### Local Dashboard Server A lightweight Go server with hot-reload for local development: ```bash # Build and serve (opens browser automatically) cd dpb-benchmark make serve # Development mode with Air hot-reload make dev # Install Air (first time only) make install-air ``` The server runs on `http://localhost:8080` by default. **Check if server is running:** ```bash # Check port 8080 lsof -ti:8080 && echo "Server is running" || echo "Server is not running" # Or check process ps aux | grep dashboard-server ``` --- ## Documentation Generation The `generate_mkdocs_docs` tool creates comprehensive documentation from your dependency analysis data. ### Manual Usage **Via Cursor IDE (Recommended):** ```bash @dependency-buster generate_mkdocs_docs repo_path=/path/to/repo ``` **With Options:** ```bash @dependency-buster generate_mkdocs_docs repo_path=/path/to/repo output_dir=./docs include_changelog=true format=mkdocs site_name="My Project" site_description="Project Documentation" ``` **Via Command Line (TypeScript):** ```bash echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"generate_mkdocs_docs","arguments":{"repo_path":"/path/to/repo","output_dir":"./docs","include_changelog":true,"format":"mkdocs"}},"id":1}' | node dpb-mcp-typescript/build/server.js ``` **Via Command Line (Go):** ```bash echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"generate_mkdocs_docs","arguments":{"repo_path":"/path/to/repo","output_dir":"./docs"}},"id":1}' | ./dpb-mcp-go/build/dpb-mcp ``` **Via Command Line (Rust):** ```bash echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"generate_mkdocs_docs","arguments":{"repo_path":"/path/to/repo","output_dir":"./docs"}},"id":1}' | ./dpb-mcp-rust/target/release/dpb-mcp ``` ### Parameters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `repo_path` | string | **required** | Absolute path to repository | | `output_dir` | string | `docs/` | Output directory for generated documentation | | `include_changelog` | boolean | `true` | Include dependency changelog based on snapshots | | `format` | string | `mkdocs` | Output format: `mkdocs`, `html`, or `markdown` | | `site_name` | string | auto-detected | Site name for mkdocs.yml | | `site_description` | string | auto-detected | Site description for mkdocs.yml | ### Viewing Generated Documentation **Option 1: MkDocs (Recommended)** ```bash cd docs pip install mkdocs mkdocs-material mkdocs serve # Opens at http://127.0.0.1:8000 ``` **Option 2: View Markdown Directly** ```bash # Open in your editor code docs/index.md ``` **Option 3: HTML Output** ```bash # Generate with format=html # Then open docs/index.html in browser ``` ### When Documentation is Generated **Auto-Generation (First Run):** - When the dashboard server starts for the first time, documentation is automatically generated with all available implementations (TypeScript, Go, Rust) - This happens only once - if `docs/index.md` already exists, auto-generation is skipped - Benchmark results for all three implementations are displayed in the console **Manual Generation:** Use the `@dependency-buster generate_mkdocs_docs` command whenever you need to regenerate documentation: ```bash # Basic usage @dependency-buster generate_mkdocs_docs repo_path=/path/to/repo # With custom output directory @dependency-buster generate_mkdocs_docs repo_path=/path/to/repo output_dir=./custom-docs # Without changelog (faster) @dependency-buster generate_mkdocs_docs repo_path=/path/to/repo include_changelog=false # HTML format instead of MkDocs @dependency-buster generate_mkdocs_docs repo_path=/path/to/repo format=html ``` **CI/CD Integration:** Add to your GitHub Actions/GitLab CI workflow: ```yaml - name: Generate Documentation run: | # Call generate_mkdocs_docs tool echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"generate_mkdocs_docs","arguments":{"repo_path":"${{ github.workspace }}"}},"id":1}' | node dpb-mcp-typescript/build/server.js # Commit docs/ directory to repository ``` **Note**: Documentation generation is now included in benchmarks. When you run `run-benchmark.sh`, it will benchmark `generate_mkdocs_docs` for all three implementations. --- ## CI/CD Integration ### GitHub Actions ```yaml name: Dependency Analysis on: [push] jobs: analyze: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '20' - name: Run dependency-buster run: | git clone https://github.com/your-username/dependency-buster.git /tmp/dpb cd /tmp/dpb/dpb-mcp-typescript npm install && npm run build cd $GITHUB_WORKSPACE /tmp/dpb/dpb-benchmark/scripts/run-benchmark.sh . - name: Upload Dashboard uses: actions/upload-artifact@v4 with: name: dependency-report path: /tmp/dpb/dpb-benchmark/dashboard/index.html ``` --- ## Development ### Prerequisites - Node.js 18+ (TypeScript) - Go 1.21+ (Go) - Rust 1.70+ (Rust) - jq (for JSON processing) ### Running Tests ```bash # TypeScript cd dpb-mcp-typescript npm test # Go cd dpb-mcp-go go test ./... # Rust cd dpb-mcp-rust cargo test ``` ### Building All ```bash ./build-all.sh ``` --- ## Contributing Contributions are welcome! Please read our [Contributing Guide](./CONTRIBUTING.md) first. 1. Fork the repository 2. Create your feature branch (`git checkout -b feature/amazing-feature`) 3. Commit your changes (`git commit -m 'Add amazing feature'`) 4. Push to the branch (`git push origin feature/amazing-feature`) 5. Open a Pull Request --- ## License MIT License - see [LICENSE](./LICENSE) for details. --- ## Acknowledgments - [Model Context Protocol](https://modelcontextprotocol.io) - The protocol that powers this - [Backstage](https://backstage.io) - Inspiration for enterprise features - [AzuraCast](https://azuracast.com) - Test repository for benchmarking