# Box MCP Proxy Server

A proxy server that bridges STDIO-based MCP clients with Box's remote MCP server over HTTP. This proxy handles Box OAuth 2.0 authentication and forwards MCP messages between clients and the Box remote server.

## Quick Setup

**New users should run the interactive setup:**

```bash
python setup.py
```

This will:
- Create virtual environment and install dependencies
- Guide you through entering Box API credentials securely
- Configure secure token storage (keychain, memory, or encrypted)
- Set appropriate file permissions
- Provide Claude Desktop configuration with correct Python path

## Manual Setup

1. **Create Virtual Environment and Install Dependencies**
   ```bash
   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   pip install -r requirements.txt
   ```

2. **Configure Credentials**
   Either run `python setup.py` (recommended) or manually create `.env`:

   Required variables:
   - `BOX_CLIENT_ID`: Your Box application's client ID  
   - `BOX_CLIENT_SECRET`: Your Box application's client secret (or stored in keychain via setup)
   - `TOKEN_STORAGE_TYPE`: Security option (see Security section)

3. **Box Application Setup**
   - Create a Box application at https://developer.box.com
   - Configure OAuth 2.0 with redirect URI: `http://localhost:8080/callback`
   - Ensure your application has the necessary scopes

## Usage

### As a Standalone Server
```bash
python main.py
```

### With MCP Clients
Configure your MCP client to use this proxy as an STDIO server:

```json
{
  "mcpServers": {
    "box-remote-mcp-proxy": {
      "command": "/path/to/box-remote-mcp-proxy/.venv/bin/python",
      "args": ["/path/to/box-remote-mcp-proxy/main.py"]
    }
  }
}
```

## Authentication Flow

1. On first run, the proxy will open a browser for Box OAuth authorization
2. After successful authorization, tokens are saved locally
3. Tokens are automatically refreshed when expired
4. Re-authentication is triggered when refresh fails

## Architecture

- **STDIO Interface**: Receives JSON-RPC messages from MCP clients
- **OAuth Manager**: Handles Box authentication and token management  
- **HTTP Client**: Sends authenticated requests to Box MCP server
- **Proxy Logic**: Forwards messages between STDIO and HTTP transports

## Security

The proxy supports multiple secure credential and token storage options:

- **Keyring** (default): Uses OS keychain for tokens and optionally client secrets (macOS Keychain, Windows Credential Manager)
- **Memory**: Stores tokens only in memory, requires re-auth on restart (most secure)
- **Encrypted**: Encrypts tokens with random keys stored in keychain
- **Plaintext**: Plain JSON file (development only)

Key security features:
- Client secrets can be stored in keychain (via setup script) 
- Tokens use secure storage separate from credentials
- File permissions automatically set to 600 (owner read/write only)
- Credential format validation prevents typos

See `SECURITY.md` for detailed security configuration options.

## Files

- `main.py`: Entry point and signal handling
- `setup.py`: Interactive setup script for new users
- `config.py`: Environment variable configuration
- `auth/oauth.py`: Box OAuth 2.0 implementation
- `auth/secure_storage.py`: OS keychain token storage
- `auth/memory_storage.py`: Memory-only token storage  
- `auth/encrypted_storage.py`: Encrypted file token storage
- `transport/http_client.py`: Streamable HTTP client for Box MCP server
- `proxy/server.py`: Main proxy server logic
- `stdio_reader.py`: Async STDIO message reader
- `logger.py`: Logging configuration
- `SECURITY.md`: Security configuration guide