📋 RFC-001: Solid CLI Architecture for Humans and AI Agents

[Dumbris]

We're designing a comprehensive CLI architecture for mcpproxy v1.0 that works great for both human developers and AI agents. This follows the proven "gh CLI model" with hierarchical discovery.

Why CLI-First Architecture?

The CLI is designed to be the primary interface for both humans AND AI agents. This unlocks powerful workflows:

AI Agent Debugging & Development

When AI agents (like Claude) work with mcpproxy, they can use the CLI to:

• Debug upstream MCP servers: mcpproxy upstream logs github --follow
• Diagnose issues: mcpproxy doctor --json
• Inspect tool schemas: mcpproxy tools info github:create_issue --json

This means agents can help develop and test mcpproxy itself - using the CLI to verify changes, run diagnostics, and troubleshoot issues.

Developing MCP Servers & Other Projects

When using mcpproxy as your MCP aggregator while building:

• Your own MCP servers: Test tools, check logs, restart servers instantly
• AI-powered applications: Agents can manage their own tool ecosystem
• Any project with MCP integration: Single proxy, full visibility

---

Key Features

🎯 Hierarchical Discovery via --help-json

mcpproxy --help-json              # Top-level commands (~150 tokens)
mcpproxy upstream --help-json     # Subcommands (~100 tokens)
mcpproxy upstream add --help-json # Detailed flags (~150 tokens)

This is 10x more token-efficient than MCP tool discovery.

🔧 Universal Output Formatting

mcpproxy upstream list --json                    # JSON output
mcpproxy upstream list --json name,health.level  # Field selection
mcpproxy upstream list --jq '.[] | select(...)'  # Built-in jq filtering
mcpproxy upstream list --names-only              # Minimal output

🚀 Agent-Friendly Error Messages

{
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "Not authenticated for server 'github'",
    "recovery_command": "mcpproxy auth login --server github"
  }
}

---

New Commands Overview

Command	Description
mcpproxy history list	View tool call history with risk scores
mcpproxy integrate import claude	Import servers from Claude config
mcpproxy completion bash	Shell completion scripts
mcpproxy watch calls	Live tool call monitoring

---

Questions for Community

1. mcpproxy api command: Should we add direct REST API access like gh api? Or is CLI coverage sufficient?

2. JQ library: Should we bundle jq-like filtering (gojq) or keep it external?

3. Exit codes: Are semantic exit codes (3=auth, 4=server not found) useful for your scripts?

4. Integration priority: Which MCP clients should we prioritize for import/export? (Claude, Cursor, Goose, etc.)

---

📄 Full proposal: docs/proposals/001-cli-architecture.md