appserver/mcp-server

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)

cd mcp-server
npm install -g .

Option 2: Local Development

cd mcp-server
npm install
npm run build
npm link

Configuration

Environment Setup

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):

{
  "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

# 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

# List organizations
saas_list_organizations()

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

Application Management

# 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

# 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

# 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

# Install dependencies
npm install

# Build the server
npm run build

# Run in development mode
npm run dev

Testing with MCP Inspector

# 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