tuxcare-eportal-mcp

Revmagi/tuxcare-eportal-mcp

3.2

If you are the rightful owner of tuxcare-eportal-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The TuxCare ePortal MCP Server is a Model Context Protocol server designed to integrate with the TuxCare ePortal API, providing tools for managing various aspects of server and user administration.

Tools

  1. list_servers

    List servers with filtering options.

  2. register_host

    Register a new host.

  3. unregister_host

    Unregister a host by hostname, IP, or server ID.

  4. bulk_unregister_hosts

    Bulk unregister inactive hosts.

  5. set_server_tags

    Set tags for a server.

TuxCare ePortal MCP Server

A Model Context Protocol (MCP) server for integrating with TuxCare ePortal API. This server provides MCP tools for managing servers, feeds, registration keys, patchsets, and users through the ePortal API.

Features

  • Server Management: List, register, and unregister servers with advanced filtering
  • Feed Management: Create, modify, and delete feeds
  • Key Management: Manage registration keys for server enrollment
  • Patchset Management: List and manage patchset deployments
  • User Management: List ePortal users
  • Server Tagging: Set and manage server tags
  • Flexible Authentication: Support for basic auth and API keys

Installation Options

Option 1: NPM Global Installation (Recommended)

# Install globally from npm
npm install -g tuxcare-eportal-mcp

# Verify installation
tuxcare-eportal-mcp --help

Option 2: NPX (No Installation Required)

# Run directly with npx
npx tuxcare-eportal-mcp --help

# Use in MCP configuration with npx
npx tuxcare-eportal-mcp --url https://your-eportal.com --auth-type basic --username admin --password secret

Option 3: GitHub Installation

# Install directly from GitHub
npm install -g github:Revmagi/tuxcare-eportal-mcp

# Or clone and install locally
git clone https://github.com/Revmagi/tuxcare-eportal-mcp.git
cd tuxcare-eportal-mcp
npm install
npm run build
npm link

Configuration Guide

Configuration Methods

You can configure the MCP server in three ways:

  1. Configuration File (recommended for permanent setups)
  2. Command Line Arguments (good for testing and Claude Code)
  3. Environment Variables (for containerized deployments)

Method 1: Configuration File

Create a configuration file in JSON format:

Basic Authentication Example (config.json):

{
  "eportal_url": "https://your-eportal.com",
  "auth": {
    "type": "basic",
    "username": "admin",
    "password": "your-password"
  }
}

API Key Authentication Example (config.json):

{
  "eportal_url": "https://your-eportal.com",
  "auth": {
    "type": "api_key",
    "api_key": "your-api-key",
    "header_name": "X-Api-Key"
  }
}
Configuration File Locations

The server looks for configuration files in the following order:

  1. Specified path: --config /path/to/config.json
  2. Current directory: ./config.json
  3. Home directory: ~/.tuxcare-eportal-mcp/config.json
  4. System directory: /etc/tuxcare-eportal-mcp/config.json

Method 2: Command Line Arguments

You can pass all configuration via command line arguments:

# Basic authentication
tuxcare-eportal-mcp \
  --url https://your-eportal.com \
  --auth-type basic \
  --username admin \
  --password your-password

# API key authentication
tuxcare-eportal-mcp \
  --url https://your-eportal.com \
  --auth-type api_key \
  --api-key your-api-key \
  --header-name X-Api-Key

Method 3: Environment Variables

Set environment variables for secure configuration:

export TUXCARE_EPORTAL_URL="https://your-eportal.com"
export TUXCARE_AUTH_TYPE="basic"
export TUXCARE_USERNAME="admin"
export TUXCARE_PASSWORD="your-password"

# Or for API key
export TUXCARE_AUTH_TYPE="api_key"
export TUXCARE_API_KEY="your-api-key"
export TUXCARE_HEADER_NAME="X-Api-Key"

MCP Client Configuration

Claude Code Configuration

Method 1: Using Configuration File

  1. Create a config file in your project directory:

    {
  "eportal_url": "https://your-eportal.com",
  "auth": {
    "type": "basic",
    "username": "admin",
    "password": "your-password"
  }
}

  2. Add to your Claude Code MCP settings:

    {
  "mcpServers": {
    "tuxcare-eportal": {
      "command": "npx",
      "args": ["tuxcare-eportal-mcp", "--config", "./config.json"]
    }
  }
}
Method 2: Using Command Line Arguments (No Config File)

Basic Authentication:

{
  "mcpServers": {
    "tuxcare-eportal": {
      "command": "npx",
      "args": [
        "tuxcare-eportal-mcp@1.0.4",
        "--url", "https://your-eportal.com",
        "--auth-type", "basic",
        "--username", "admin",
        "--password", "your-password"
      ]
    }
  }
}

API Key Authentication:

{
  "mcpServers": {
    "tuxcare-eportal": {
      "command": "npx",
      "args": [
        "tuxcare-eportal-mcp@1.0.4",
        "--url", "https://your-eportal.com",
        "--auth-type", "api_key",
        "--api-key", "your-api-key"
      ]
    }
  }
}

API Key with Custom Header:

{
  "mcpServers": {
    "tuxcare-eportal": {
      "command": "npx",
      "args": [
        "tuxcare-eportal-mcp@1.0.4",
        "--url", "https://your-eportal.com",
        "--auth-type", "api_key",
        "--api-key", "your-api-key",
        "--header-name", "X-API-Key"
      ]
    }
  }
}
Method 3: Using Environment Variables (Most Secure)

Basic Authentication:

{
  "mcpServers": {
    "tuxcare-eportal": {
      "command": "npx",
      "args": ["tuxcare-eportal-mcp@1.0.4"],
      "env": {
        "TUXCARE_EPORTAL_URL": "https://your-eportal.com",
        "TUXCARE_AUTH_TYPE": "basic",
        "TUXCARE_USERNAME": "admin",
        "TUXCARE_PASSWORD": "your-password"
      }
    }
  }
}

API Key Authentication:

{
  "mcpServers": {
    "tuxcare-eportal": {
      "command": "npx",
      "args": ["tuxcare-eportal-mcp@1.0.4"],
      "env": {
        "TUXCARE_EPORTAL_URL": "https://your-eportal.com",
        "TUXCARE_AUTH_TYPE": "api_key",
        "TUXCARE_API_KEY": "your-api-key"
      }
    }
  }
}

API Key with Custom Header:

{
  "mcpServers": {
    "tuxcare-eportal": {
      "command": "npx",
      "args": ["tuxcare-eportal-mcp@1.0.4"],
      "env": {
        "TUXCARE_EPORTAL_URL": "https://your-eportal.com",
        "TUXCARE_AUTH_TYPE": "api_key",
        "TUXCARE_API_KEY": "your-api-key",
        "TUXCARE_HEADER_NAME": "X-API-Key"
      }
    }
  }
}

Continue.dev Configuration

Add to your continue.json:

{
  "mcpServers": {
    "tuxcare-eportal": {
      "command": "npx",
      "args": ["tuxcare-eportal-mcp", "--config", "./config.json"]
    }
  }
}

Cline Configuration

Add to your MCP settings:

{
  "mcpServers": {
    "tuxcare-eportal": {
      "command": "tuxcare-eportal-mcp",
      "args": [
        "--url", "https://your-eportal.com",
        "--auth-type", "basic",
        "--username", "admin",
        "--password", "your-password"
      ]
    }
  }
}

Generic MCP Client Configuration

For any MCP client, use this format:

{
  "mcpServers": {
    "tuxcare-eportal": {
      "command": "tuxcare-eportal-mcp",
      "args": ["--config", "/path/to/config.json"]
    }
  }
}

Configuration Setup Commands

Quick Setup Command

Generate a configuration file interactively:

# Create config file with prompts
npx tuxcare-eportal-mcp --setup

# Create config file with basic auth
npx tuxcare-eportal-mcp --setup --url https://your-eportal.com --auth-type basic

# Create config file with API key
npx tuxcare-eportal-mcp --setup --url https://your-eportal.com --auth-type api_key

Test Configuration

Verify your configuration works:

# Test with config file
tuxcare-eportal-mcp --config ./config.json --test

# Test with command line args
tuxcare-eportal-mcp --url https://your-eportal.com --auth-type basic --username admin --password secret --test

Available Tools

Server Management

  • list_servers: List servers with filtering options
  • register_host: Register a new host
  • unregister_host: Unregister a host by hostname, IP, or server ID
  • bulk_unregister_hosts: Bulk unregister inactive hosts
  • set_server_tags: Set tags for a server

Feed Management

  • list_feeds: List all feeds
  • create_feed: Create or modify a feed
  • delete_feed: Delete a feed

Key Management

  • list_keys: List registration keys
  • create_key: Create or modify a registration key
  • delete_key: Delete a registration key

Patchset Management

  • list_patchsets: List patchsets for a feed and product
  • manage_patchsets: Enable, disable, or manage patchset deployments

User Management

  • list_users: List all ePortal users

Tool Usage Examples

List Servers

// List all servers
await callTool("list_servers", {});

// List servers with filtering
await callTool("list_servers", {
  hostname: "web%",
  tag: "env:production",
  limit: 50
});

// Get server count only
await callTool("list_servers", {
  only_count: true
});

Register Host

await callTool("register_host", {
  key: "production-key",
  hostname: "web-server-01"
});

Manage Patchsets

// Enable a patchset
await callTool("manage_patchsets", {
  patchset: "K20240101_01",
  feed: ["main", "staging"],
  action: "enable",
  product: "kernel"
});

// Enable all patchsets up to a specific one
await callTool("manage_patchsets", {
  patchset: "K20240101_01",
  feed: ["main"],
  action: "enable-upto",
  product: "kernel"
});

Set Server Tags

await callTool("set_server_tags", {
  server_id: "abc123",
  tags: "env:production;team:platform;ubuntu"
});

Authentication

Basic Authentication

{
  "auth": {
    "type": "basic",
    "username": "your-username",
    "password": "your-password"
  }
}

API Key Authentication

{
  "auth": {
    "type": "api_key",
    "api_key": "your-api-key",
    "header_name": "X-Api-Key"
  }
}

Security Best Practices

  1. Never commit credentials to version control
  2. Use environment variables for sensitive data
  3. Restrict file permissions on config files: chmod 600 config.json
  4. Use API keys instead of passwords when possible
  5. Rotate credentials regularly
  6. Use HTTPS for all ePortal connections

Troubleshooting

Common Issues

Connection Errors
# Test connection
curl -v https://your-eportal.com/api/v1/servers

# Check DNS resolution
nslookup your-eportal.com
Authentication Failures
# Test basic auth
curl -u username:password https://your-eportal.com/api/v1/servers

# Test API key
curl -H "X-Api-Key: your-key" https://your-eportal.com/api/v1/servers
Configuration Issues
# Validate configuration file
npx tuxcare-eportal-mcp --config ./config.json --validate

# Show current configuration
npx tuxcare-eportal-mcp --config ./config.json --show-config

Debug Mode

Enable debug logging:

# Debug mode
DEBUG=tuxcare:* tuxcare-eportal-mcp --config ./config.json

# Verbose output
tuxcare-eportal-mcp --config ./config.json --verbose

Error Handling

The server provides comprehensive error handling:

  • Authentication errors: Clear messages for credential issues
  • API errors: Detailed error messages from the ePortal API
  • Validation errors: Input validation with helpful error messages
  • Network errors: Timeout and connection error handling

Development

Setup

git clone https://github.com/Revmagi/tuxcare-eportal-mcp.git
cd tuxcare-eportal-mcp
npm install

Build

npm run build

Development Mode

npm run dev

Testing

npm test

Linting

npm run lint
npm run lint:fix

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Run linting and tests
  6. Submit a pull request

License

MIT License - see file for details.

Support

Version History

  • 1.0.0: Initial release with full ePortal API support