MCP ACS Verdaccio

Manage a local Verdaccio npm registry directly from VS Code with full AI agent integration through MCP. Part of the Digital Defiance AI Capabilities Suite.

Features

🚀 Server Lifecycle Management

Start/Stop/Restart: Control Verdaccio from the command palette or status bar
Status Bar Indicator: See server state and port at a glance
Graceful Shutdown: Automatic cleanup on VS Code close with 5-second SIGTERM→SIGKILL escalation
Error Reporting: Last 20 lines of server output captured on unexpected exit

📦 Cache and Package Management

Cache Browser: Browse cached packages grouped by scope with version details
Package Metadata: View name, version, description, tarball size for any cached version
Delete Packages: Remove packages from storage with confirmation prompts
Auto-Refresh: FileSystemWatcher detects new packages within 5 seconds

📊 Storage Analytics

Disk Usage Monitoring: Total storage size with configurable warning thresholds
Stale Package Detection: Identify packages not accessed within configurable days
Prune Old Versions: Keep the N most recent versions, delete the rest
Bulk Cleanup: Multi-select stale packages for batch deletion
Top 5 Largest Packages: Quick visibility into storage hogs

🔧 Configuration Panel

Webview UI: Edit listen port, storage path, max body size, log level
Uplink Settings: URL, timeout, max retries, cache strategy per uplink
Cache Strategies: Cache-first (maxage=9999d) or proxy-first (maxage=0) per uplink
Offline Mode: Toggle offline mode with automatic uplink snapshot/restore
Proxy Settings: Global and per-uplink HTTP/HTTPS proxy with no-proxy list

🔒 Scoped Registries and Auth Tokens

Scoped Registries: Route @fortawesome, @myorg etc. to private registries
Auth Token Management: Add, rotate, remove, reveal tokens with VS Code SecretStorage
Validation: Scope names must start with @, URLs must be valid HTTP/HTTPS
Round-Trip Safety: All .npmrc mutations preserve unrelated lines

📤 Publish Workflow

Publish to Verdaccio: One-click publish from workspace with duplicate detection
Promote Package: Re-publish tarballs to upstream registries
Version Bumping: Semver bump (patch/minor/major/prerelease) via npm version
Monorepo Support: Detect workspace packages, publish all in dependency order (topological sort)
Partial Failure Handling: Continue on failure, show summary of successes and failures

🌐 Registry Health Dashboard

Uplink Latency: Periodic pings with response time in milliseconds
Cache Hit Rate: Percentage of requests served from cache vs proxied
Failed Request Counter: Track connectivity issues per uplink
Health Status: Healthy / Degraded / Unreachable classification
Auto-Suggest Offline Mode: When all uplinks are unreachable

📋 .npmrc Profiles

Named Profiles: Save "local-dev", "ci", "offline" configurations
Quick Switching: Switch profiles with a single command
Status Bar: Active profile name displayed in VS Code status bar
JSON Storage: Profiles stored in .verdaccio/profiles/ as JSON

🚀 Project Onboarding

Auto-Detection: Detects .verdaccio/config.yaml on workspace open
One-Click Bootstrap: Start server, set registry, mirror dependencies
Persistent State: Won't re-prompt after initial onboarding

✈️ Dependency Mirroring

Mirror All Dependencies: Cache entire lockfile for offline development
Lockfile Support: Both package-lock.json and yarn.lock
Progress Indicator: Shows mirroring progress
Summary Report: Newly cached vs already available counts

🤖 MCP Server (22 AI-Accessible Tools)

AI coding agents can programmatically control the registry through structured MCP tool calls:

Tool	Description
`verdaccio_start`	Start the Verdaccio server
`verdaccio_stop`	Stop the server
`verdaccio_status`	Get server state, port, uptime
`verdaccio_publish`	Publish a package from a directory
`verdaccio_publish_all`	Publish all workspace packages in dependency order
`verdaccio_list_packages`	List all cached packages with versions
`verdaccio_search`	Search packages by name pattern
`verdaccio_get_package`	Get full package details (all versions)
`verdaccio_get_version`	Get version metadata with dependencies
`verdaccio_check_cached`	Batch check which packages are cached
`verdaccio_cache_diff`	Compare cache vs lockfile (up-to-date/outdated/missing)
`verdaccio_cache_stats`	Quick cache summary stats
`verdaccio_package_deps`	Dependency tree with cache status flags
`verdaccio_walk_cache`	Detailed cache inspection with filtering, sorting, pagination
`verdaccio_set_registry`	Configure .npmrc for Verdaccio
`verdaccio_reset_registry`	Reset .npmrc to defaults
`verdaccio_add_scoped_registry`	Add scoped registry entry
`verdaccio_set_offline_mode`	Toggle offline mode
`verdaccio_get_config`	Read Verdaccio configuration
`verdaccio_update_config`	Patch Verdaccio configuration
`verdaccio_storage_analytics`	Get storage usage metrics
`verdaccio_cleanup`	Prune stale packages or old versions

Requirements

Verdaccio installed (npm i -g verdaccio)
Node.js 18+
VS Code 1.85+

Installation

Install from VS Code Marketplace:

code --install-extension DigitalDefiance.mcp-acs-verdaccio

Configuration

General Settings

{
  "verdaccio.configPath": ".verdaccio/config.yaml",
  "verdaccio.autoSetRegistry": false,
  "verdaccio.storageWarningThresholdMb": 500,
  "verdaccio.stalenessThresholdDays": 90,
  "verdaccio.mcp.autoStart": true,
  "verdaccio.healthPingIntervalMs": 30000
}

Support

Issues: GitHub Issues
Documentation: GitHub Repository
Email: info@digitaldefiance.org

License

MIT License - see LICENSE file for details.

Part of AI Capabilities Suite

This extension is part of the Digital Defiance AI Capabilities Suite, which includes:

MCP ACS Process Manager: Process management with security boundaries
MCP ACS Screenshot: Cross-platform screenshot capture
MCP ACS Debugger: Advanced debugging capabilities
MCP ACS Filesystem Manager: Advanced file operations
MCP ACS Verdaccio: Local npm registry management (this extension)

Visit Digital Defiance for more information.