UX: CLI Management Commands #54

🎯 Overview

Implement user-facing CLI commands for MCP server setup and adapter management. This provides a seamless developer experience for configuring dev-agent per-project.

Part of Epic: #31
Depends on: #52 (Foundation: Storage + Config), #53 (Adapters: Discovery + Loading)

🚀 User Experience

Installation Flow

# One-time global install
npm install -g @lytics/dev-agent

# Per-project setup
cd my-project
dev-agent init              # Create config + index repository
dev-agent mcp init         # Add to Cursor MCP config
dev-agent adapter install @company/mcp-adapter-jira  # Install custom adapter

📋 Commands

Repository Initialization

dev-agent init

Initialize repository and create configuration:

dev-agent init

? Languages to index: typescript, javascript
? Enable built-in adapters: search, github, plan, explore, status
✓ Created .dev-agent/config.json
✓ Indexed 243 files, 1,847 components

Implementation:

• Create .dev-agent/config.json with defaults
• Run initial repository indexing
• Store indexes in centralized location (~/.dev-agent/indexes/{hash}/)

MCP Server Management

dev-agent mcp init

Add current project to Cursor's MCP configuration:

dev-agent mcp init

? Add to Cursor MCP config? (Y/n) y
? MCP server name: (dev-agent-my-project)

✓ Added 'dev-agent-my-project' to ~/.cursor/mcp.json
✓ Restart Cursor to enable MCP tools

Implementation:

• Read ~/.cursor/mcp.json (or create if missing)
• Add new MCP server entry with:
  • Command: dev-agent-mcp
  • Args: []
  • Env: REPOSITORY_PATH = absolute path to current directory
• Write updated config back

dev-agent mcp list

List all MCP servers in Cursor config:

dev-agent mcp list

MCP Servers in ~/.cursor/mcp.json:

  dev-agent-my-project
    Repository: /Users/you/workspace/my-project
    Status: Active
  
  dev-agent-backend
    Repository: /Users/you/workspace/backend
    Status: Active

dev-agent mcp remove

Remove project from Cursor MCP config:

dev-agent mcp remove

? Remove 'dev-agent-my-project' from Cursor config? (Y/n) y
✓ Removed 'dev-agent-my-project' from ~/.cursor/mcp.json

Adapter Management

dev-agent adapter list

List all adapters for current project:

dev-agent adapter list

Adapters in my-project:
  ✅ search (built-in)
  ✅ github (built-in)
  ✅ plan (built-in)
  ✅ explore (built-in)
  ✅ jira (@company/mcp-adapter-jira)
  ✅ datadog (./adapters/datadog)
  ❌ status (disabled)

dev-agent adapter install <package>

Install and configure custom adapter:

dev-agent adapter install @company/mcp-adapter-jira

? Configure adapter:
  Base URL: https://company.atlassian.net
  API Key: (from env) JIRA_API_KEY

✓ Added to package.json
✓ Updated .dev-agent/config.json
✓ Run 'npm install' to install dependencies
✓ Restart Cursor to apply changes

Implementation:

• Add package to package.json dependencies (if exists)
• Update .dev-agent/config.json with adapter config
• Prompt for adapter-specific settings
• Support environment variable references (${VAR_NAME})

dev-agent adapter enable <name>

Enable a disabled adapter:

dev-agent adapter enable status

✓ Enabled 'status' adapter
✓ Restart Cursor to apply changes

dev-agent adapter disable <name>

Disable an enabled adapter:

dev-agent adapter disable github

✓ Disabled 'github' adapter
✓ Restart Cursor to apply changes

dev-agent adapter create <name>

Scaffold new local adapter:

dev-agent adapter create my-adapter

? Adapter description: My custom adapter
? Add tool? (Y/n) y
? Tool name: my_tool
? Tool description: Does something useful

✓ Created .dev-agent/adapters/my-adapter/
  - index.ts (template)
  - package.json
  - README.md
✓ Updated .dev-agent/config.json

Implementation:

• Create adapter directory structure
• Generate TypeScript template with proper types
• Add to config automatically
• Include README with development guide

Storage Management (Bonus)

dev-agent storage info

Show storage usage and repository list:

dev-agent storage info

Storage Location: ~/.dev-agent/indexes/
Total Size: 230 MB

Repositories:
  ID        Repository          Size    Last Indexed    Last Accessed
  a1b2c3d4  company/frontend    50 MB   2 hours ago     Active
  e5f6g7h8  company/backend     80 MB   5 mins ago      Active

dev-agent storage clean

Clean stale indexes:

dev-agent storage clean

? Clean indexes not accessed in: (Select)
  ○ 7 days
  ○ 30 days
  ● 90 days

Found 1 stale index:
  x9y8z7w6  old-project  100 MB  Last accessed: 90 days ago

? Remove stale indexes? (Y/n) y
✓ Removed 1 index (100 MB freed)

📋 Implementation Tasks

MCP Commands

• Implement dev-agent mcp init command
  • Read/create ~/.cursor/mcp.json
  • Add MCP server entry
  • Handle existing entries (update vs. create new)
• Implement dev-agent mcp list command
• Implement dev-agent mcp remove command
• Add error handling for missing Cursor config directory

Adapter Commands

• Implement dev-agent adapter list command
• Implement dev-agent adapter install <package> command
  • Add to package.json
  • Update config.json
  • Interactive configuration prompts
• Implement dev-agent adapter enable/disable commands
• Implement dev-agent adapter create command
  • Scaffold directory structure
  • Generate TypeScript template
  • Update config.json

Init Command Updates

• Update dev-agent init to create MCP config section
• Add interactive prompts for adapter selection
• Use centralized storage for indexes

Storage Commands (Optional)

• Implement dev-agent storage info command
• Implement dev-agent storage clean command
• Implement dev-agent storage migrate command (from Foundation: Storage + Config System #52)

✅ Acceptance Criteria

• dev-agent init creates config with MCP section
• dev-agent mcp init adds project to Cursor config
• dev-agent mcp list shows all configured servers
• dev-agent mcp remove removes project from config
• dev-agent adapter list shows all adapters (enabled/disabled)
• dev-agent adapter install adds adapter to config + package.json
• dev-agent adapter enable/disable updates config
• dev-agent adapter create scaffolds new adapter
• All commands provide helpful error messages
• Commands handle missing config files gracefully

🧪 Testing

• Unit tests for MCP config reading/writing
• Unit tests for adapter config updates
• Integration tests for full init flow
• Integration tests for adapter install flow
• Test error handling (missing files, invalid configs)

🔗 Dependencies

• Depends on: Foundation: Storage + Config System #52 (Foundation: Storage + Config) - needs config system
• Depends on: Adapters: Discovery + Loading System #53 (Adapters: Discovery + Loading) - needs discovery system

Estimate: 1-1.5 days
Priority: High (user-facing functionality)