Skip to content

TESTING.md

Latest commit

 

History

History
348 lines (255 loc) · 8.91 KB

TESTING.md

File metadata and controls

348 lines (255 loc) · 8.91 KB
Raw

Cloudron MCP Server - Integration Testing Guide

Phase 2.3: Real Instance Testing

This guide walks through testing the Cloudron MCP Server against a real Cloudron instance.

Project Status

Phase: 2.2 Complete - MCP Server Implementation Build: ✅ Successful (all TypeScript compiled) Tests Created: ✅ Integration test suite ready

Implemented Tools

  1. cloudron_list_apps - List all installed applications
  2. cloudron_status - Get system status and health metrics
  3. cloudron_restart_app - Restart a specific application

Prerequisites

What You Need

  • A running Cloudron instance (self-hosted or managed)
  • API token with read/write permissions
  • Bash or compatible shell environment
  • Node.js 18+ (already installed for development)

Get Your Credentials

Step 1: Get Your Cloudron Instance URL

Typical formats:

  • https://my.serenichron.com (custom domain)
  • https://my.cloudron.io (Cloudron's hosted platform)
  • https://cloudron.yourdomain.com (your own domain)

Step 2: Create API Token

  1. Log into your Cloudron Admin Panel
  2. Navigate to Admin → API Tokens
  3. Click "Create API Token"
  4. Give it a meaningful name (e.g., "MCP Testing")
  5. Ensure it has read and write permissions
  6. Copy the generated token (secure this! It's like a password)

Important: Treat your API token like a password. Never commit it to version control.

Configuration

Option A: Environment Variables (Recommended for Testing)

export CLOUDRON_BASE_URL="https://your-cloudron-instance.com"
export CLOUDRON_API_TOKEN="your-api-token-here"

Option B: .env File (Local Development)

  1. Copy the template:

    cp .env.example .env

  2. Edit .env with your credentials:

    CLOUDRON_BASE_URL=https://my.serenichron.com
CLOUDRON_API_TOKEN=your-api-token-here

  3. Note: .env is already in .gitignore - safe to use for secrets

Running Tests

Build the Project

npm run build

Expected output:

> @blackthorne/mcp-cloudron@0.1.0 build
> tsc

No errors should appear.

Run Integration Tests

# Using environment variables
CLOUDRON_BASE_URL="https://your-instance.com" \
CLOUDRON_API_TOKEN="your-token" \
npm run dev src/test-integration.ts

Or if using .env:

npm run dev src/test-integration.ts

Test Execution Flow

The integration test suite runs the following tests in order:

  1. Connection Validation (30-60ms)

    • Verifies the API token is valid
    • Confirms the Cloudron instance is accessible
    • Fails fast if credentials are invalid

  2. Get System Status (50-150ms)

    • Fetches system health metrics
    • Displays Cloudron version and uptime
    • Validates response structure

  3. List Applications (100-300ms)

    • Retrieves all installed apps
    • Shows first 3 apps with ID and status
    • Counts total number of applications

  4. Restart Application (200-500ms)

    • Attempts safe restart of first application
    • Skipped if no apps exist
    • Includes safety confirmation output

Example Test Output

╔════════════════════════════════════════╗
║  Cloudron MCP Integration Tests        ║
║  Phase 2.3: Real Instance Testing      ║
╚════════════════════════════════════════╝

Configuration:
  Base URL: https://my.serenichron.com
  Token: tmpt_abc12345...

✓ Client initialized successfully

════════════════════════════════════════
Running Tests
════════════════════════════════════════

▶ Testing: Connection Validation
✓ PASSED (45ms): Connection Validation

▶ Testing: Get System Status
  Version: 7.2.1
  Uptime: 168 hours
✓ PASSED (82ms): Get System Status

▶ Testing: List Applications
  Found 5 application(s)
    - Nextcloud (app-abc123) [running]
    - WordPress (app-def456) [running]
    - Mailu (app-ghi789) [running]
    ... and 2 more
✓ PASSED (156ms): List Applications

▶ Testing: Restart Application (Safety Test)
  ⚠  Attempting to restart: Nextcloud (app-abc123)
  Note: In production, this would require confirmation
  Restart initiated for Nextcloud
✓ PASSED (312ms): Restart Application (Safety Test)

════════════════════════════════════════
Test Summary
════════════════════════════════════════

✓ Connection Validation (45ms)
✓ Get System Status (82ms)
✓ List Applications (156ms)
✓ Restart Application (Safety Test) (312ms)

Results: 4 passed, 0 failed, 0 skipped / 4 total
Total Duration: 595ms

SUCCESS: All tests passed!

Troubleshooting

"Missing required environment variables"

Symptom: Test exits with this error message

Solution:

# Set environment variables
export CLOUDRON_BASE_URL="https://your-instance.com"
export CLOUDRON_API_TOKEN="your-token"

# Try again
npm run dev src/test-integration.ts

"Invalid API token"

Symptom: Connection Validation test fails with 401 error

Cause: Token is invalid, expired, or doesn't have required permissions

Solution:

  1. Log into your Cloudron Admin Panel
  2. Go to API Tokens
  3. Check if the token is still active
  4. Create a new token if necessary
  5. Update your environment/configuration

"Failed to connect to Cloudron instance"

Symptom: Connection error to your base URL

Causes:

  • Base URL is incorrect or unreachable
  • Network connectivity issue
  • Cloudron instance is down
  • SSL certificate issue

Solution:

  1. Verify the URL is correct: curl -I https://your-instance.com
  2. Check internet connectivity: ping google.com
  3. Verify Cloudron is running: Visit URL in browser
  4. Check for SSL cert issues: curl -v https://your-instance.com

"Timeout waiting for response"

Symptom: Test hangs for 30+ seconds then fails

Causes:

  • Cloudron instance is slow or unresponsive
  • Network latency is high

Solution:

  • Increase timeout: export CLOUDRON_TIMEOUT=60000 (60 seconds)
  • Check Cloudron's server health
  • Try again during off-peak hours

Next Steps After Successful Testing

1. MCP Server Integration

The compiled MCP server is ready at dist/index.js:

# Start the MCP server
node dist/index.js

The server expects:

  • CLOUDRON_BASE_URL environment variable
  • CLOUDRON_API_TOKEN environment variable
  • Listens on stdin/stdout (MCP protocol)

2. Docker MCP Gateway Integration

To add this to your Docker MCP Gateway configuration:

mcpServers:
  cloudron:
    env:
      CLOUDRON_BASE_URL: "https://your-instance.com"
      CLOUDRON_API_TOKEN: "your-token"
    command: node
    args:
      - /path/to/dist/index.js

3. Expand Tool Coverage

Phase 2.2 implements the core 3 tools. Phase 3 will add:

  • Domain management (list, add, configure)
  • User/Group management
  • Backup operations
  • App installation/removal
  • System updates

Security Best Practices

  1. Never commit credentials

    • Use .env files (in .gitignore)
    • Use environment variables in CI/CD
    • Use secrets management tools

  2. Rotate tokens regularly

    • Generate new tokens periodically
    • Revoke old tokens
    • Monitor token usage

  3. Limit token permissions

    • Create tokens with minimum required permissions
    • Use separate tokens for different integrations
    • Document which token is used where

  4. Monitor API usage

    • Check Cloudron's API usage logs
    • Alert on unusual patterns
    • Review successful and failed requests

Testing Against Multiple Instances

To test against multiple Cloudron instances:

# Test instance 1
CLOUDRON_BASE_URL="https://instance1.com" \
CLOUDRON_API_TOKEN="token1" \
npm run dev src/test-integration.ts

# Test instance 2
CLOUDRON_BASE_URL="https://instance2.com" \
CLOUDRON_API_TOKEN="token2" \
npm run dev src/test-integration.ts

Continuous Integration

For CI/CD pipeline testing:

# GitHub Actions example
env:
  CLOUDRON_BASE_URL: ${{ secrets.CLOUDRON_BASE_URL }}
  CLOUDRON_API_TOKEN: ${{ secrets.CLOUDRON_API_TOKEN }}

- name: Run Integration Tests
  run: npm run dev src/test-integration.ts

Reporting Issues

If tests fail, please include:

  1. Test output (full output from test run)
  2. Your Cloudron version (from test output or Admin panel)
  3. Network details (are you behind a firewall/proxy?)
  4. Environment (OS, Node.js version)
  5. Reproduction steps

Questions or Issues?

Last Updated: 2025-12-11 Phase: 2.3 - Integration Testing Status: Ready for User Testing