AgentUp CLI Redesign Proposal

[lukehinds]

AgentUp CLI Redesign Proposal

Understanding the YAML Structure

The system manages two types of Tool like systems we support in AgentUp, Plugins and MCP Servers.

Plugins are essentially "Tools" or "Function Calling" to use the OpenAI term, and MCP is a sort of
extension of Tools to becoming a standardised approach to "Tools".

Over time we may want to repurpose "Plugins" to become more like adapters for customized code,
rather then doing an xkcd.com/927 and creating another beast.

Also MCP is on fire, there are so many MCP servers, its silly not to lean into the area more. AgentUp
works remarkably well with MCP servers, providing a seamless integration experience. I found myself
creating a pretty decent Calendar agent in less than an hour.

So this doc seeks to band together this bunch and figure out what it might look like on the CLI.

Top level points, all things become providers, this gives room for whatever the next gizmo to be,
that arrives in the scene sometime in the future.

AgentUp CLI Redesign Proposal

Understanding the YAML Structure

The system manages two types of providers:

1. Plugins - Python packages with capabilities that have scopes
2. MCP Servers - External servers with tools that have scopes

Both can be enabled/disabled at multiple levels and have scope-based permissions.

Updated YAML Structure:

# Plugins
plugins:
  agentup_systools:
    enabled: true
    capabilities:
      delete_file:
        enabled: true
        scopes:
          - files:admin

# MCP - now matches plugin structure exactly!
mcp:
  enabled: true
  servers:
    - name: weather
      enabled: true
      transport: stdio
      command: python
      args:
        - scripts/mcp/weather_server.py
        - --transport
        - stdio
      capabilities:
        weather:get_alerts:
          enabled: true
          scopes: 
            - alerts:read
        weather:get_forecast:
          enabled: true
          scopes: 
            - weather:read

Redesigned Command Structure

1. Provider Management (unified view)

# List all providers (plugins + MCP servers)
uv run agentup provider list
┌──────────────────┬─────────┬─────────┬─────────────────┐
│ Provider         │ Type    │ Status  │ Capabilities    │
├──────────────────┼─────────┼─────────┼─────────────────┤
│ agentup_systools │ plugin  │ ●active │ 11 capabilities │
│ agentup_brave    │ plugin  │ ●active │ 1 capability    │
│ weather          │ mcp     │ ●active │ 2 capabilities  │
│ google-calendar  │ mcp     │ ●active │ 9 capabilities  │
└──────────────────┴─────────┴─────────┴─────────────────┘

# Output formats
uv run agentup provider list --format json
uv run agentup provider list --format yaml

# Filter by type
uv run agentup provider list --type plugin --format json
uv run agentup provider list --type mcp --format yaml

# Provider actions
uv run agentup provider enable <provider_name>
uv run agentup provider disable <provider_name>

2. Plugin Management (focused on plugins)

# List plugins with their capabilities
uv run agentup plugin list
┌──────────────────┬─────────┬─────────────┐
│ Plugin           │ Status  │ Capabilities│
├──────────────────┼─────────┼─────────────┤
│ agentup_systools │ ●active │ 11 active   │
│ agentup_brave    │ ●active │ 1 active    │
└──────────────────┴─────────┴─────────────┘

# Output formats
uv run agentup plugin list --format json
uv run agentup plugin list --format yaml

# Show plugin capabilities
uv run agentup plugin show agentup_systools
uv run agentup plugin show agentup_systools --format json
uv run agentup plugin show agentup_systools --format yaml
Plugin: agentup_systools (●active)
┌───────────────────┬─────────┬─────────────┐
│ Capability        │ Status  │ Scopes      │
├───────────────────┼─────────┼─────────────┤
│ create_directory  │ ●active │ files:write │
│ delete_file       │ ●active │ files:admin │
│ execute_command   │ ●active │ system:admin│
│ file_exists       │ ●active │ files:read  │
│ file_hash         │ ●active │ files:read  │
│ file_info         │ ●active │ files:read  │
│ file_read         │ ●active │ files:read  │
│ file_write        │ ●active │ files:write │
│ list_directory    │ ●active │ files:read  │
│ system_info       │ ●active │ system:read │
│ working_directory │ ●active │ system:read │
└───────────────────┴─────────┴─────────────┘

# Plugin capability management
uv run agentup plugin capability enable agentup_systools delete_file
uv run agentup plugin capability disable agentup_systools execute_command

3. MCP Server Management (focused on MCP)

# List MCP servers
uv run agentup mcp list
┌─────────────────┬─────────┬───────────┬─────────┬─────────────┐
│ Server          │ Status  │ Transport │ Command │ Capabilities│
├─────────────────┼─────────┼───────────┼─────────┼─────────────┤
│ weather         │ ●active │ sse       │ http.   │ 2 active    │
│ google-calendar │ ●active │ stdio     │ npx     │ 9 active    │
└─────────────────┴─────────┴───────────┴─────────┴─────────────┘

# Output formats
uv run agentup mcp list --format json
uv run agentup mcp list --format yaml

# Show MCP server details
uv run agentup mcp show google-calendar
uv run agentup mcp show google-calendar --format json
uv run agentup mcp show google-calendar --format yaml
Server: google-calendar (●active)
Transport: stdio
Command: npx @cocal/google-calendar-mcp
Environment:
  GOOGLE_OAUTH_CREDENTIALS: /Users/lhinds/dev/agentup-ws/...
Timeout: 30s
Expose as skills: true

┌──────────────────────────────────┬──────────┬────────────────┐
│ Capability                       │ Status   │ Scopes         │
├──────────────────────────────────┼──────────┼────────────────┤
│ google-calendar:list-calendars   │  ●active │ calendar:read  │
│ google-calendar:list-events      │  ●active │ calendar:read  │
│ google-calendar:search-events    │  ●active │ calendar:read  │
│ google-calendar:list-colors      │  ●active │ calendar:read  │
│ google-calendar:create-event     │  ●active │ calendar:write │
│ google-calendar:update-event     │  ●active │ calendar:write │
│ google-calendar:delete-event     │  ●active │ calendar:write │
│ google-calendar:get-freebusy     │  ●active │ calendar:read  │
│ google-calendar:get-current-time │  ●active │ calendar:read  │
└──────────────────────────────────┴──────────┴────────────────┘

# MCP server management
uv run agentup mcp enable <server_name>
uv run agentup mcp disable <server_name>
uv run agentup mcp capability enable <server_name> <capability_name>
uv run agentup mcp capability disable <server_name> <capability_name>

# MCP configuration
uv run agentup mcp configure <server_name> --timeout 60
uv run agentup mcp configure <server_name> --env KEY=value
uv run agentup mcp configure <server_name> --expose-skills false

4. Unified Capability Management

# List all capabilities across providers
uv run agentup capability list
┌──────────────────────────────┬──────────────────┬─────────┬────────────────┐
│ Capability                   │ Provider         │ Status  │ Scopes         │
├──────────────────────────────┼──────────────────┼─────────┼────────────────┤
│ create_directory             │ agentup_systools │ ●active │ files:write    │
│ delete_file                  │ agentup_systools │ ●active │ files:admin    │
│ search_internet              │ agentup_brave    │ ●active │ api:read       │
│ weather:get_alerts           │ weather          │ ●active │ alerts:read    │
│ weather:get_forecast         │ weather          │ ●active │ weather:read   │
│ google-calendar:list-events  │ google-calendar  │ ●active │ calendar:read  │
│ google-calendar:create-event │ google-calendar  │ ●active │ calendar:write │
└──────────────────────────────┴──────────────────┴─────────┴────────────────┘

# Output formats
uv run agentup capability list --format json
uv run agentup capability list --format yaml

# Filter by provider type with format
uv run agentup capability list --type plugin --format json
uv run agentup capability list --type mcp --format yaml

# Filter by scope with format
uv run agentup capability list --scope files:* --format json
uv run agentup capability list --scope calendar:* --format yaml

# Quick enable/disable (works across both plugins and MCP)
uv run agentup capability enable <capability_name>
uv run agentup capability disable <capability_name>

5. Scope Management (unified across providers)

# List all scopes and their usage
uv run agentup scope list
┌──────────────────────────────┬───────────────┬─────────────┬──────────────────┐
│ Capability                   │ Scope         │ Granted     │ Provider         │
├──────────────────────────────┼───────────────┼─────────────┼──────────────────┤
│ create_directory             │ files:write   │ ●granted    │ agentup_systools │
│ file_write                   │ files:write   │ ●granted    │ agentup_systools │
│ delete_file                  │ files:admin   │ ○denied     │ agentup_systools │
│ execute_command              │ system:admin  │ ○denied     │ agentup_systools │
│ search_internet              │ api:read      │ ●granted    │ agentup_brave    │
│ weather:get_alerts           │ alerts:read   │ ●granted    │ weather          │
│ google-calendar:list-events  │ calendar:read │ ●granted    │ google-calendar  │
│ google-calendar:create-event │ calendar:write│ ●granted    │ google-calendar  │
└──────────────────────────────┴───────────────┴─────────────┴──────────────────┘

# Output formats
uv run agentup scope list --format json
uv run agentup scope list --format yaml

# Filter with format
uv run agentup scope list --granted --format json
uv run agentup scope list --not-granted --format yaml

# Scope operations (works across both YAML structures)
uv run agentup scope grant <capability_name>     # grants the scope for this capability
uv run agentup scope revoke <capability_name>    # revokes the scope for this capability

# Bulk operations
uv run agentup scope grant --scope files:*
uv run agentup scope revoke --scope system:admin

# Show impact with format
uv run agentup scope revoke --scope calendar:write --dry-run
uv run agentup scope revoke --scope calendar:write --dry-run --format json
⚠️  Revoking scope 'calendar:write' would disable:
   • google-calendar:create-event (google-calendar MCP)
   • google-calendar:update-event (google-calendar MCP)
   • google-calendar:delete-event (google-calendar MCP)

6. Status and Health Commands

# Overall status
uv run agentup status
AgentUp Status:
┌─────────────┬───────────────────────┐
│ Plugins     │ 2 active              │
│ MCP Servers │ 2 active              │
│ Capabilities│ 22 active, 2 inactive │
│ Scopes      │ 18 granted, 4 revoked │
└─────────────┴───────────────────────┘

⚠️  MCP client is enabled
⚠️  Inactive tools: delete_file, execute_command
⚠️  Missing scopes: files:admin, system:admin

# Health check
uv run agentup doctor
✓ All active plugins are properly loaded
✓ MCP client is enabled and configured
⚠️ Capability 'delete_file' disabled due to missing scope 'files:admin'
⚠️ Capability 'execute_command' requires scope 'system:admin'
⚠️ MCP server 'google-calendar' env var GOOGLE_OAUTH_CREDENTIALS not found

# Global MCP settings
uv run agentup mcp status
MCP Status:
  Client: ●enabled
  Servers: 2 active, 0 inactive
  Capabilities: 11 active, 0 inactive
  
uv run agentup mcp enable   # enables MCP client globally
uv run agentup mcp disable  # disables MCP client globally

Summary / Wrap up

1. Unified Interface

• provider and tool commands work across both plugins and MCP servers
• Same scope management regardless of source type
• Consistent status indicators everywhere

2. Hierarchical Control

• Plugin level: enable/disable entire plugin
• Capability level: enable/disable individual plugin capabilities
• Server level: enable/disable entire MCP server
• Tool level: enable/disable individual MCP tools
• Scope level: grant/revoke permissions for any tool/capability

3. Type-Aware Commands

• plugin commands understand plugin-specific concepts (capabilities, required_scopes)
• mcp commands understand MCP-specific concepts (transport, command, env, tool_scopes)
• Both feed into unified tool and scope views

4. YAML Structure Awareness

The commands directly map to YAML operations:

• plugins.{name}.enabled ← provider enable/disable
• plugins.{name}.capabilities.{cap}.enabled ← plugin capability enable/disable
• mcp.servers[].enabled ← mcp enable/disable
• mcp.servers[].capabilities.{cap}.enabled ← mcp capability enable/disable
• Both use identical capabilities.{name}.scopes structure for scope management

This design scales naturally as both plugin and MCP ecosystems grow, while providing the abstraction for more providder types as they appear.