# SaaS Platform MCP Server

A Model Context Protocol (MCP) server that provides LLMs with programmatic access to the self-hostable SaaS platform. This enables AI assistants to interact with user authentication, organizations, applications, deployments, and storage.

## Features

The MCP server provides tools for:

### Authentication
- `saas_login` - Login to the platform
- `saas_logout` - Logout from the platform  
- `saas_get_current_user` - Get current user info
- `saas_register_user` - Register new users

### 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 in an org
- `saas_create_application` - Create new application
- `saas_get_application` - Get application details
- `saas_deploy_application` - Deploy an 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 files in storage
- `saas_upload_file` - Upload files
- `saas_download_file` - Download files
- `saas_delete_file` - Delete files

## Installation

### Option 1: Global Install (Recommended for Claude Desktop)
```bash
cd mcp-server
npm install -g .
```

### Option 2: Local Development
```bash
cd mcp-server
npm install
npm run build
npm link
```

## Configuration

### Environment Setup
```bash
cp .env.example .env
# Edit .env with your SaaS platform URLs
```

### Claude Desktop Configuration

Add to your Claude Desktop configuration file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```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"
      }
    }
  }
}
```

Restart Claude Desktop after adding the configuration.

## Usage Examples

### Basic Authentication Flow
```bash
# Login to the platform
saas_login(email="user@example.com", password="password123")

# Get current user info
saas_get_current_user()

# Logout when done
saas_logout()
```

### Managing Organizations
```bash
# List organizations
saas_list_organizations()

# Create new organization
saas_create_organization(
  name="My Startup",
  slug="my-startup", 
  description="Building amazing things"
)
```

### Application Management
```bash
# List applications in an organization
saas_list_applications(organizationId="org-uuid")

# Create new application
saas_create_application(
  name="My App",
  slug="my-app",
  organizationId="org-uuid",
  description="A TypeScript application",
  repositoryUrl="https://github.com/user/repo.git",
  buildCommand="npm run build",
  startCommand="npm start"
)

# Deploy the application
saas_deploy_application(
  applicationId="app-uuid",
  version="1.0.0",
  commitHash="abc123"
)

# Check deployment status
saas_get_deployments(applicationId="app-uuid")
```

### File Storage
```bash
# Upload a file
saas_upload_file(
  path="/uploads/config.json",
  content='{"key": "value"}',
  contentType="application/json"
)

# List files
saas_list_files(path="/uploads")

# Download a file
saas_download_file(path="/uploads/config.json")
```

### Platform Monitoring
```bash
# Check platform health
saas_health_check()

# Get platform statistics
saas_get_platform_stats()
```

## Security Features

- **JWT Authentication**: Secure token-based authentication
- **Token Management**: Automatic token refresh and invalidation
- **Secure Storage**: Encrypted credential storage
- **Audit Logging**: All actions are logged in the platform
- **Permission Checking**: Tools respect user permissions

## Development

### Running Locally
```bash
# Install dependencies
npm install

# Build the server
npm run build

# Run in development mode
npm run dev
```

### Testing with MCP Inspector
```bash
# Install MCP Inspector globally
npm install -g @modelcontextprotocol/inspector

# Run the inspector with your server
mcp-inspector dist/index.js
```

### Adding New Tools

1. Create a new tool file in `src/tools/`
2. Register the tool in `src/index.ts`
3. Add the tool to the `ListToolsRequestSchema` handler
4. Implement the tool handler function
5. Update the README documentation

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `SAAS_API_URL` | `http://localhost` | Base URL for API Gateway |
| `SAAS_AUTH_URL` | `http://localhost/auth` | Auth service URL |
| `SAAS_STORAGE_URL` | `http://localhost/storage` | Storage service URL |
| `DEBUG` | `false` | Enable debug logging |

## Error Handling

The MCP server provides comprehensive error handling:

- **Authentication Errors**: When tokens expire or are invalid
- **Permission Errors**: When users don't have access to resources
- **Validation Errors**: For invalid input parameters
- **Network Errors**: When platform services are unavailable

All errors include detailed messages to help with debugging.

## Rate Limiting

The MCP server respects rate limits from the underlying platform services. If you encounter rate limiting, wait before retrying operations.

## Contributing

1. Fork the repository
2. Create feature branch
3. Add tests for new tools
4. Update documentation
5. Submit pull request

## License

MIT License - see parent project LICENSE file