of-mcp 0.1.2
CLI and Python SDK for managing MCP Gateway workspaces, backends, and agents
License: MIT
Requires Python: >=3.9
Keywords: mcp, gateway, cli, workspace

# MCP Gateway CLI & SDK

> Enterprise-grade Model Context Protocol management for Claude Desktop

[![PyPI version](https://badge.fury.io/py/of-mcp.svg)](https://pypi.org/project/of-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Manage MCP servers, workspaces, and configurations for Claude Desktop with enterprise security features.

**Two ways to use:**
- 🖥️ **CLI**: Command-line tool for interactive management
- 🐍 **SDK**: Python library for programmatic integration

## 🚀 Quick Start

### Installation

```bash
pip install of-mcp
```

**Note:** Package name is `of-mcp`, CLI command is `mcpgw`

After installation, add to your PATH (if needed):
```bash
# Add to ~/.zshrc or ~/.bashrc
export PATH="$HOME/Library/Python/3.12/bin:$PATH"
```

Requirements: Python 3.9+

## CLI Usage

### 1. Login

```bash
mcpgw auth login
# Enter your email and password
```

### 2. List Workspaces

```bash
mcpgw workspace list
```

### 3. Create Workspace

```bash
mcpgw workspace create --name "Production"
```

### 4. Add Backend

```bash
mcpgw backend add WORKSPACE_ID --name "Gmail" --url "http://gmail-mcp:9000"
```

### 5. Create Agent

```bash
mcpgw agent create WORKSPACE_ID --name "My Agent"
# Save the API key shown!
```

## SDK Usage

Use `of-mcp` as a Python library in your applications:

```python
from of_mcp import MCPGatewayClient

# Initialize client
client = MCPGatewayClient(token="your-token")

# Or login with email/password
client = MCPGatewayClient()
client.login(email="user@example.com", password="password")

# List workspaces
workspaces = client.workspaces.list()
print(workspaces)

# Create workspace
workspace = client.workspaces.create(name="Production", description="Prod environment")
print(f"Created workspace: {workspace['id']}")

# Add backend
backend = client.backends.add(
    workspace_id=workspace['id'],
    name="Gmail",
    url="http://gmail-mcp:9000"
)

# List backends
backends = client.backends.list(workspace['id'])

# Create agent
agent = client.agents.create(
    workspace_id=workspace['id'],
    name="Email Agent",
    description="Handles email operations"
)
print(f"Agent API key: {agent['api_key']}")

# Browse catalog
catalog = client.catalog.list(category="email")

# Enable catalog backend
enabled = client.catalog.enable(
    workspace_id=workspace['id'],
    backend_id="backend_gmail"
)
```

### SDK Error Handling

```python
from of_mcp import MCPGatewayClient, AuthenticationError, APIError

try:
    client = MCPGatewayClient()
    client.login(email="user@example.com", password="wrong-password")
except AuthenticationError as e:
    print(f"Login failed: {e}")
except APIError as e:
    print(f"API error ({e.status_code}): {e}")
```

### SDK with Environment Variables

```python
import os
from of_mcp import MCPGatewayClient

# Uses MCPGW_API_URL and MCPGW_TOKEN from environment
os.environ['MCPGW_API_URL'] = 'http://localhost:8000/api/v1'
os.environ['MCPGW_TOKEN'] = 'your-token'

client = MCPGatewayClient()
workspaces = client.workspaces.list()
```

## CLI Commands

### Authentication

```bash
mcpgw auth login              # Login
mcpgw auth logout             # Logout
mcpgw auth whoami             # Show current user
```

### Workspaces

```bash
mcpgw workspace list                    # List all workspaces
mcpgw workspace get WORKSPACE_ID        # Get workspace details
mcpgw workspace create                  # Create new workspace
mcpgw workspace delete WORKSPACE_ID     # Delete workspace
```

### Backends

```bash
mcpgw backend list WORKSPACE_ID                           # List backends
mcpgw backend add WORKSPACE_ID --name X --url Y           # Add backend
mcpgw backend remove WORKSPACE_ID BACKEND_ID              # Remove backend
```

### Backend Catalog

```bash
mcpgw catalog list                                  # Browse catalog
mcpgw catalog list --category email                 # Filter by category
mcpgw catalog enable WORKSPACE_ID BACKEND_ID        # Enable from catalog
```

### Agents

```bash
mcpgw agent list WORKSPACE_ID                 # List agents
mcpgw agent create WORKSPACE_ID --name X      # Create agent
```

## Configuration

Config stored in `~/.mcpgw/config.json`

### Environment Variables

- `MCPGW_API_URL` - API base URL (default: https://api.mcpgw.io/api/v1)
- `MCPGW_PROFILE` - Configuration profile to use
- `MCPGW_TOKEN` - Authentication token (for CI/CD)

### Profiles

Manage multiple environments:

```bash
# Create profiles for different environments
mcpgw profile create staging --api-url https://staging.mcpgw.io/api/v1
mcpgw profile create local --api-url http://localhost:8000/api/v1

# List profiles
mcpgw profile list

# Switch between profiles
mcpgw profile use staging

# Show current profile
mcpgw profile current
```

## Examples

### Setup a new workspace

```bash
# Login
mcpgw auth login

# Create workspace
mcpgw workspace create --name "Production"

# Enable Gmail backend
WORKSPACE_ID="ws_abc123"
mcpgw catalog enable $WORKSPACE_ID backend_gmail

# Create an agent
mcpgw agent create $WORKSPACE_ID --name "Email Agent"
```

### Get workspace info as JSON

```bash
mcpgw workspace list --json-output | jq '.[0]'
```

## Development

```bash
# Install in development mode
cd cli
pip install -e .

# Run tests
pytest

# Build distribution
pipx run build

# Upload to PyPI
pipx run twine upload dist/*
```

## 📖 Documentation

- **Environment Guide**: [ENVIRONMENT_GUIDE.md](ENVIRONMENT_GUIDE.md) - Complete guide for multi-environment management
- **Publishing Guide**: [PUBLISHING.md](PUBLISHING.md) - How to publish to PyPI
- **Distribution**: [DISTRIBUTION.md](DISTRIBUTION.md) - Homebrew and package distribution

## 🔗 Links

- **PyPI Package**: https://pypi.org/project/of-mcp/
- **Documentation**: https://docs.mcpgw.io
- **Website**: https://mcpgw.io
- **GitHub**: https://github.com/orangefennec/mcp-gateway
- **Support**: support@mcpgw.io

## 📝 License

MIT License - see [LICENSE](../LICENSE) for details

## 🤝 Contributing

Contributions welcome! See [CONTRIBUTING.md](../CONTRIBUTING.md)

---

**Made with ❤️ by [Orange Fennec](https://orangefennec.com)**