# Claude Desktop Configuration for SaaS Platform MCP

This guide shows how to configure Claude Desktop to use the SaaS Platform MCP server for programmatic access to your self-hosted SaaS platform.

## Prerequisites

1. Your SaaS platform must be running (`npm run start`)
2. Node.js and npm installed on your host machine
3. Claude Desktop installed

## Installation Steps

### 1. Install MCP Server Globally

```bash
cd mcp-server
npm install -g .
```

This installs the `mcp-saas-server` command globally.

### 2. Configure Claude Desktop

#### macOS
Edit this file: `~/Library/Application Support/Claude/claude_desktop_config.json`

#### Windows
Edit this file: `%APPDATA%\Claude\claude_desktop_config.json`

#### Linux
Edit this file: `~/.config/Claude/claude_desktop_config.json`

Add the following configuration:

```json
{
  "mcpServers": {
    "saas-platform": {
      "command": "mcp-saas-server",
      "env": {
        "SAAS_API_URL": "http://localhost",
        "SAAS_AUTH_URL": "http://localhost/auth", 
        "SAAS_STORAGE_URL": "http://localhost/storage",
        "DEBUG": "false"
      }
    }
  }
}
```

### 3. Restart Claude Desktop

Completely quit and restart Claude Desktop for the configuration to take effect.

## Usage in Claude

Once configured, you can ask Claude to interact with your SaaS platform:

### Authentication Examples

```
Please login to my SaaS platform using email: admin@saas.local and password: admin123
```

```
Show me my current user information
```

```
Register a new user with email test@example.com and password password123
```

### Organization Management

```
List all my organizations
```

```
Create a new organization called "My Startup" with slug "my-startup"
```

### Application Management

```
Show me all applications in the default organization
```

```
Create a new TypeScript application with name "My App" and slug "my-app" in the default org
```

```
Deploy the application with ID app-uuid-here
```

### File Storage

```
List all files in the storage
```

```
Upload a configuration file with JSON content: {"api_key": "secret123", "timeout": 30}
```

### Platform Monitoring

```
Check the health of all platform services
```

```
Show me platform statistics
```

## Available Tools

The MCP server provides these tools to Claude:

### Authentication
- `saas_login` - Authenticate with the platform
- `saas_logout` - Logout current session
- `saas_get_current_user` - Get current user details
- `saas_register_user` - Register new user account

### Organizations  
- `saas_list_organizations` - List user's organizations
- `saas_create_organization` - Create new organization
- `saas_get_organization` - Get organization details

### Applications
- `saas_list_applications` - List applications
- `saas_create_application` - Create new application
- `saas_get_application` - Get application details
- `saas_deploy_application` - Deploy application
- `saas_get_deployments` - Get deployment history

### System
- `saas_health_check` - Check platform health
- `saas_get_platform_stats` - Get platform statistics

### Storage
- `saas_list_files` - List storage files
- `saas_upload_file` - Upload files
- `saas_download_file` - Download files
- `saas_delete_file` - Delete files

## Security Notes

- Your credentials are stored locally in the MCP session only
- Authentication tokens are not persisted
- All operations are logged in the platform's audit logs
- Use strong passwords and change defaults in production

## Troubleshooting

### MCP Server Not Found
```bash
# Verify installation
which mcp-saas-server

# Reinstall if needed
cd mcp-server
npm install -g .
```

### Connection Errors
1. Ensure SaaS platform is running (`npm run start`)
2. Check URLs in your Claude config match your platform URLs
3. Verify network connectivity between Claude and the platform

### Authentication Issues
1. Verify credentials are correct
2. Check that user exists in the platform
3. Try registering a new user if login fails

### Debug Mode
Enable debug logging by setting `"DEBUG": "true"` in your Claude Desktop config:

```json
{
  "mcpServers": {
    "saas-platform": {
      "command": "mcp-saas-server",
      "env": {
        "SAAS_API_URL": "http://localhost",
        "SAAS_AUTH_URL": "http://localhost/auth", 
        "SAAS_STORAGE_URL": "http://localhost/storage",
        "DEBUG": "true"
      }
    }
  }
}
```

## Development Setup

If you want to modify the MCP server:

```bash
cd mcp-server
npm install
npm run dev

# Test with MCP Inspector
npm install -g @modelcontextprotocol/inspector
mcp-inspector dist/index.js
```

## Production Usage

For production environments:

1. Use HTTPS URLs in configuration
2. Change default passwords
3. Enable audit logging
4. Use environment-specific configurations
5. Consider running MCP server in Docker

## Support

If you encounter issues:

1. Check the MCP server logs
2. Verify platform service health
3. Review the configuration syntax
4. Check network connectivity
5. Create an issue in the repository