Skip to content

UX: CLI Management Commands #54

Description

@prosdev

🎯 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)

✅ 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

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Fields

    No fields configured for Feature.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions