Skip to content

cli-reference.md

Latest commit

 

History

History
487 lines (337 loc) · 10.8 KB

cli-reference.md

File metadata and controls

487 lines (337 loc) · 10.8 KB

CLI Reference Guide

The MCP Foxxy Bridge CLI provides comprehensive management capabilities with facility-aware logging for better operational visibility.

Table of Contents

Global Options

Available for all commands:

foxxy-bridge [OPTIONS] COMMAND [ARGS]...
Option Description
-C, --config-dir PATH Configuration directory path (default: ~/.config/foxxy-bridge/)
-c, --config PATH Configuration file path (env: FOXXY_BRIDGE_CONFIG)
-d, --debug Enable debug logging
--no-color Disable colored output
-v, --version Show version and exit
-h, --help Show help message

Server Management

Start Bridge Server

foxxy-bridge server start [OPTIONS]

Options:

  • --port INTEGER - Server port (default: 8080)
  • --host TEXT - Server host (default: 127.0.0.1)
  • --config PATH - Configuration file path
  • --daemon - Run as background daemon
  • --log-level [debug|info|warning|error] - Logging level

Examples:

# Start server on default port
foxxy-bridge server start

# Start on custom port with specific config
foxxy-bridge server start --port 9000 --config ./prod-config.json

# Start as daemon with debug logging
foxxy-bridge server start --daemon --log-level debug

Stop Bridge Server

foxxy-bridge server stop [OPTIONS]

Options:

  • --force - Force stop without graceful shutdown

List Running Instances

foxxy-bridge server list

Shows all running bridge daemon instances with their status.

Server Status

foxxy-bridge server server-status [SERVER]

Options:

  • --format [table|json] - Output format
  • --watch, -w - Watch for status changes

Restart Server

foxxy-bridge server server-restart SERVER [OPTIONS]

Options:

  • --force - Force restart without graceful shutdown

MCP Server Management

Add MCP Server

foxxy-bridge mcp add NAME COMMAND [ARGS...] [OPTIONS]

Options:

  • --transport [stdio|sse|http] - Transport type (default: stdio)
  • --url URL - Server URL (required for SSE/HTTP)
  • --env KEY VALUE - Environment variables (repeatable)
  • --cwd PATH - Working directory
  • --tags TAG [TAG...] - Server tags for grouping
  • --oauth - Enable OAuth authentication
  • --oauth-issuer URL - OAuth issuer URL
  • --timeout INTEGER - Connection timeout in seconds
  • --retry-attempts INTEGER - Number of retry attempts
  • --retry-delay FLOAT - Delay between retries
  • --health-check - Enable health checking
  • --tool-namespace TEXT - Tool namespace prefix
  • --resource-namespace TEXT - Resource namespace prefix
  • --priority INTEGER - Server priority
  • --log-level [debug|info|warning|error] - Server log level
  • --headers KEY VALUE - HTTP headers (for HTTP/SSE transports)
  • --read-only - Enable read-only mode
  • --allow-patterns TEXT - Tool allow patterns (repeatable)
  • --block-patterns TEXT - Tool block patterns (repeatable)
  • --allow-tools TEXT - Allowed tools (repeatable)
  • --block-tools TEXT - Blocked tools (repeatable)
  • --classify-tools TOOL TYPE - Tool classifications (repeatable)

Examples:

# Add basic stdio server
foxxy-bridge mcp add github "npx" "-y" "@modelcontextprotocol/server-github" \
  --env GITHUB_TOKEN "${GITHUB_TOKEN}" \
  --tags development git

# Add SSE server with OAuth
foxxy-bridge mcp add remote-api "https://api.example.com/mcp" \
  --transport sse \
  --oauth \
  --oauth-issuer "https://auth.example.com" \
  --tags production remote

# Add server with security restrictions
foxxy-bridge mcp add restricted-fs "npx" "-y" "@modelcontextprotocol/server-filesystem" \
  --read-only \
  --allow-patterns "read_*" "list_*" \
  --block-patterns "delete_*" "remove_*"

List MCP Servers

foxxy-bridge mcp mcp-list [OPTIONS]

Options:

  • --format [table|json|yaml] - Output format

Show Server Details

foxxy-bridge mcp mcp-show [NAME] [OPTIONS]

Options:

  • --format [json|yaml] - Output format

If no name provided, shows all servers.

Remove MCP Server

foxxy-bridge mcp remove NAME [OPTIONS]

Options:

  • --force - Remove without confirmation

Enable/Disable Server

foxxy-bridge mcp enable NAME
foxxy-bridge mcp disable NAME

Restart MCP Server

foxxy-bridge mcp mcp-restart SERVER

Forces reconnection to the specified MCP server.

View Server Logs

foxxy-bridge mcp logs SERVER [OPTIONS]

Options:

  • --follow, -f - Follow log output
  • --lines, -n INTEGER - Number of lines to show (default: 50)
  • --level [debug|info|warning|error] - Filter by log level

Configuration Management

Initialize Configuration

foxxy-bridge config init [OPTIONS]

Options:

  • --force - Overwrite existing configuration

Creates a default configuration with schema reference and sample MCP server.

Show Configuration

foxxy-bridge config config-show [OPTIONS]

Options:

  • --format [json|yaml] - Output format (default: yaml)

Validate Configuration

foxxy-bridge config validate [OPTIONS]

Options:

  • --fix - Attempt to fix validation issues

Get/Set Configuration Values

foxxy-bridge config get-value KEY
foxxy-bridge config set-value KEY VALUE
foxxy-bridge config unset-value KEY

Examples:

# Get bridge port
foxxy-bridge config get-value bridge.port

# Set bridge host
foxxy-bridge config set-value bridge.host "0.0.0.0"

# Remove configuration key
foxxy-bridge config unset-value bridge.oauth_port

Security Configuration

foxxy-bridge config security show [OPTIONS]
foxxy-bridge config security set KEY VALUE
foxxy-bridge config security allow-tool TOOL_NAME
foxxy-bridge config security block-tool TOOL_NAME
foxxy-bridge config security classify-tool TOOL [read|write|unknown]

Options for show:

  • --format [json|yaml] - Output format

Examples:

# Show security settings
foxxy-bridge config security show

# Set read-only mode
foxxy-bridge config security set read_only_mode true

# Allow specific tool
foxxy-bridge config security allow-tool file_read

# Classify tool as read-only
foxxy-bridge config security classify-tool user_info read

Tool Discovery & Testing

List Tools

foxxy-bridge tool tool-list [SERVER] [OPTIONS]

Options:

  • --format [table|json] - Output format
  • --tag TAG - Filter by server tag

Examples:

# List all tools
foxxy-bridge tool tool-list

# List tools from specific server
foxxy-bridge tool tool-list github

# List tools by tag
foxxy-bridge tool tool-list --tag development

OAuth Authentication

OAuth Login

foxxy-bridge oauth login SERVER [OPTIONS]

Initiates OAuth authentication flow for a specific server.

Options:

  • --force - Force re-authentication even if tokens exist

Examples:

# Initiate OAuth flow
foxxy-bridge oauth login production-api

# Force re-authentication
foxxy-bridge oauth login production-api --force

OAuth Logout

foxxy-bridge oauth logout SERVER [OPTIONS]

Clears stored OAuth tokens for a specific server.

Options:

  • --confirm - Skip confirmation prompt

Examples:

# Clear tokens for a server
foxxy-bridge oauth logout staging-api

# Clear without confirmation
foxxy-bridge oauth logout staging-api --confirm

OAuth Status

foxxy-bridge oauth status [SERVER] [OPTIONS]

Options:

  • --format [table|json] - Output format
  • --detailed - Show additional token information

Shows OAuth authentication status for servers with OAuth enabled.

Examples:

# Show all OAuth statuses
foxxy-bridge oauth status

# Show status for specific server
foxxy-bridge oauth status remote-api

# Detailed status in JSON format
foxxy-bridge oauth status --format json --detailed

Output Example:

╭─────────────┬──────────────┬─────────────────────╮
│ Server      │ OAuth Status │ Token Expiry        │
├─────────────┼──────────────┼─────────────────────┤
│ production  │ ✓ Valid      │ 2024-01-15 14:30:00 │
│ staging     │ ⚠ Expired    │ 2024-01-10 10:15:00 │
│ development │ ✗ No tokens  │ -                   │
╰─────────────┴──────────────┴─────────────────────╯

Monitoring & Logs

MCP Server Logs

foxxy-bridge mcp logs SERVER [OPTIONS]

Options:

  • --follow, -f - Follow log output
  • --lines, -n INTEGER - Number of lines to show
  • --level [debug|info|warning|error] - Filter by log level

Examples:

# View last 50 lines
foxxy-bridge mcp logs github

# Follow logs with debug level
foxxy-bridge mcp logs github --follow --level debug

# Show last 100 lines
foxxy-bridge mcp logs filesystem --lines 100

Facility-Aware Logging

The CLI uses color-coded facility logging for better operational visibility:

Facility Color Purpose
[BRIDGE] Blue Bridge server operations
[OAUTH] Orange OAuth authentication flows
[SERVER] Magenta MCP server operations

Example Output:

[BRIDGE] Starting bridge server on 127.0.0.1:8080
[BRIDGE] Loaded configuration from /home/user/.config/foxxy-bridge/config.json
[SERVER] Connected to MCP server 'github'
[OAUTH] Initiating OAuth flow for server 'remote-api'
[OAUTH] Authentication successful for server 'remote-api'
[SERVER] Health check passed for 'filesystem'

Disable Colors:

foxxy-bridge --no-color server start

Exit Codes

  • 0 - Success
  • 1 - General error
  • 2 - Configuration error
  • 3 - Authentication error
  • 4 - Server connection error

Environment Variables

Variable Description
FOXXY_BRIDGE_CONFIG Default configuration file path
FOXXY_BRIDGE_CONFIG_DIR Default configuration directory
FOXXY_BRIDGE_LOG_LEVEL Default log level (debug, info, warning, error)
FOXXY_BRIDGE_NO_COLOR Disable colored output (any value)

Configuration File Location

Default locations (in order of precedence):

  1. --config CLI argument
  2. FOXXY_BRIDGE_CONFIG environment variable
  3. ~/.config/foxxy-bridge/config.json
  4. ./config.json (current directory)