TailscaleMCP

# 🚀 TailscaleMCP Portmanteau Tools Documentation **Complete guide to the comprehensive TailscaleMCP server with portmanteau tools** --- ## 🎯 **Overview** The TailscaleMCP server implements a **portmanteau pattern** to avoid tool explosion, following the database-mcp design philosophy. Instead of having dozens of individual tools, we have **10 powerful consolidated tools** that each handle multiple related operations. ### **Why Portmanteau Tools?** - ✅ **No Tool Explosion**: Prevents UI clutter and cognitive overload - ✅ **Consistent Interface**: All tools follow the same `operation` parameter pattern - ✅ **Domain Focused**: Each tool handles a specific domain comprehensively - ✅ **Easier Maintenance**: Single file per tool category instead of many small files - ✅ **Better Organization**: Related functionality grouped logically --- ## 🔧 **Portmanteau Tools Overview** | Tool | Operations | Domain | Key Features | |------|------------|--------|--------------| | `tailscale_device` | 15 | Device & User Management | Device operations, user management, auth keys, SSH access, exit nodes | | `tailscale_network` | 8 | DNS & Network | MagicDNS, DNS records, resolution, policies, statistics | | `tailscale_monitor` | 8 | Monitoring & Metrics | Status, Prometheus metrics, topology, health, Grafana dashboards | | `tailscale_file` | 7 | File Sharing | Taildrop operations, transfer management, statistics | | `tailscale_security` | 10 | Security & Compliance | Scanning, auditing, threat detection, policy management | | `tailscale_automation` | 9 | Workflow Automation | Workflows, scripts, batch operations, scheduling | | `tailscale_backup` | 8 | Backup & Recovery | Backup creation, restoration, scheduling, testing | | `tailscale_performance` | 8 | Performance Monitoring | Latency, bandwidth, optimization, capacity planning | | `tailscale_reporting` | 9 | Advanced Reporting | Custom reports, analytics, scheduling, export | | `tailscale_integration` | 9 | Third-Party Integrations | Webhooks, Slack, Discord, PagerDuty, Datadog | **Total: 91 comprehensive operations across 10 portmanteau tools!** --- ## 📋 **Detailed Tool Documentation** ### 1. `tailscale_device` - Device & User Management **Purpose**: Comprehensive device and user management operations. **Operations**: `list`, `get`, `authorize`, `rename`, `tag`, `ssh`, `search`, `stats`, `exit_node`, `subnet_router`, `user_list`, `user_create`, `user_update`, `user_delete`, `user_details`, `auth_key_list`, `auth_key_create`, `auth_key_revoke`, `auth_key_rotate` #### **Device Operations** ```python # List all devices await tailscale_device(operation="list", online_only=True) # Get device details await tailscale_device(operation="get", device_id="device123") # Authorize a device await tailscale_device(operation="authorize", device_id="device123", authorize=True, reason="New employee") # Rename device await tailscale_device(operation="rename", device_id="device123", name="john-laptop") # Add tags to device await tailscale_device(operation="tag", device_id="device123", tags=["engineering", "laptop"]) # Enable SSH access await tailscale_device(operation="ssh", device_id="device123", public_key="ssh-rsa...", key_name="john-key") # Search devices await tailscale_device(operation="search", search_query="engineering", search_fields=["name", "tags"]) # Enable exit node await tailscale_device(operation="exit_node", device_id="device123", enable_exit_node=True, advertise_routes=["0.0.0.0/0"]) ``` #### **User Management Operations** ```python # List users await tailscale_device(operation="user_list") # Create user await tailscale_device(operation="user_create", user_email="john@company.com", user_role="admin") # Update user await tailscale_device(operation="user_update", user_email="john@company.com", user_role="user") # Delete user await tailscale_device(operation="user_delete", user_email="john@company.com") # Get user details await tailscale_device(operation="user_details", user_email="john@company.com") ``` #### **Authentication Key Operations** ```python # List auth keys await tailscale_device(operation="auth_key_list") # Create auth key await tailscale_device(operation="auth_key_create", auth_key_name="deploy-key", auth_key_expiry="2025-12-31", auth_key_reusable=False) # Revoke auth key await tailscale_device(operation="auth_key_revoke", auth_key_name="deploy-key") # Rotate expired keys await tailscale_device(operation="auth_key_rotate") ``` --- ### 2. `tailscale_network` - DNS & Network Management **Purpose**: DNS configuration, MagicDNS, and network policy management. **Operations**: `dns_config`, `magic_dns`, `dns_record`, `resolve`, `search_domain`, `policy`, `stats`, `cache` ```python # Get DNS configuration await tailscale_network(operation="dns_config") # Configure MagicDNS await tailscale_network(operation="magic_dns", enabled=True, override_local_dns=False) # Add DNS record await tailscale_network(operation="dns_record", name="api.internal", record_type="A", value="100.64.0.1") # Resolve hostname await tailscale_network(operation="resolve", hostname="api.internal", record_type="A") # Add search domain await tailscale_network(operation="search_domain", domain="internal", enabled=True) # Create network policy await tailscale_network(operation="policy", policy_name="restrict-api", rules=[{"action": "accept", "src": ["engineering"], "dst": ["api:*"]}]) # Get DNS statistics await tailscale_network(operation="stats") # Clear DNS cache await tailscale_network(operation="cache") ``` #### Services (TailVIPs) — Fall Update Manage logical services with virtual TailVIPs and MagicDNS, grantable as policy units and automatable via API. Operations: - `services_list` → List all services - `services_get` → Get a service by ID - `services_create` → Create a new service - `services_update` → Update an existing service - `services_delete` → Delete a service Parameters: - `service_id: str` (required for get/update/delete) - `service_payload: dict` (required for create/update) - Common keys: - `name: str` (required for create) - `tailvipIPv4: str`, `tailvipIPv6: str` - `magicDNS: str` - `endpoints: list[{deviceId: str, port: int, protocol: str}]` - `tags: list[str]` Returns (shapes): - `services_list`: `{ count: int, services: [Service] }` - `services_get`: `{ service_id: str, service: Service }` - `services_create`: `{ service: Service }` - `services_update`: `{ service_id: str, service: Service }` - `services_delete`: `{ service_id: str, deleted: true }` Service model fields: - `id, name, tailvipIPv4, tailvipIPv6, magicDNS, tags, endpoints[]` - Endpoint: `{ deviceId, ip?, port, protocol }` Examples: ```python # List services await tailscale_network(operation="services_list") # Get a service await tailscale_network(operation="services_get", service_id="svc-123") # Create a service await tailscale_network( operation="services_create", service_payload={ "name": "api-service", "tailvipIPv4": "100.101.102.103", "magicDNS": "api.tail", "endpoints": [ {"deviceId": "device123", "port": 8080, "protocol": "tcp"} ], "tags": ["prod", "api"] } ) # Update a service await tailscale_network( operation="services_update", service_id="svc-123", service_payload={"tags": ["prod", "critical"]} ) # Delete a service await tailscale_network(operation="services_delete", service_id="svc-123") ``` --- ### 3. `tailscale_monitor` - Monitoring & Metrics **Purpose**: Network monitoring, metrics collection, and Grafana dashboard management. **Operations**: `status`, `metrics`, `prometheus`, `topology`, `health`, `dashboard`, `export` ```python # Get network status await tailscale_monitor(operation="status") # Get network metrics await tailscale_monitor(operation="metrics") # Get Prometheus metrics await tailscale_monitor(operation="prometheus") # Generate network topology await tailscale_monitor(operation="topology") # Get health report await tailscale_monitor(operation="health") # Create Grafana dashboard await tailscale_monitor(operation="dashboard", grafana_url="http://grafana:3000", api_key="your-api-key") # Export dashboard await tailscale_monitor(operation="export", filename="tailscale-dashboard.json", dashboard_type="comprehensive") ``` --- ### 4. `tailscale_file` - File Sharing **Purpose**: Taildrop file sharing operations and transfer management. **Operations**: `send`, `receive`, `list`, `cancel`, `status`, `stats`, `cleanup` ```python # Send file via Taildrop await tailscale_file(operation="send", file_path="/path/to/file.txt", recipient_device="device123", sender_device="device456") # Receive file await tailscale_file(operation="receive", transfer_id="transfer123", save_path="/downloads/") # List active transfers await tailscale_file(operation="list", status_filter="active") # Cancel transfer await tailscale_file(operation="cancel", transfer_id="transfer123") # Get transfer status await tailscale_file(operation="status", transfer_id="transfer123") # Get Taildrop statistics await tailscale_file(operation="stats") # Clean up expired transfers await tailscale_file(operation="cleanup") ``` --- ### 5. `tailscale_security` - Security & Compliance **Purpose**: Security scanning, compliance validation, and threat management. **Operations**: `scan`, `compliance`, `audit`, `report`, `monitor`, `block`, `quarantine`, `alert`, `policy`, `threat` ```python # Security vulnerability scan await tailscale_security(operation="scan", scan_type="comprehensive") # Compliance validation await tailscale_security(operation="compliance", compliance_standard="SOC2") # Device security audit await tailscale_security(operation="audit", device_id="device123") # Generate security report await tailscale_security(operation="report") # Monitor suspicious activity await tailscale_security(operation="monitor") # Block malicious IP await tailscale_security(operation="block", ip_address="192.168.1.100", block_duration=3600) # Quarantine compromised device await tailscale_security(operation="quarantine", device_id="device123", quarantine_duration=24) # Create security policy await tailscale_security(operation="policy", policy_name="restrict-api", rules=[{"action": "accept", "src": ["engineering"], "dst": ["api:*"]}]) # Threat detection await tailscale_security(operation="threat", threat_type="malware", test_mode=False) ``` --- ### 6. `tailscale_automation` - Workflow Automation **Purpose**: Workflow creation, script execution, and batch operations. **Operations**: `workflow_create`, `workflow_execute`, `workflow_schedule`, `workflow_list`, `workflow_delete`, `script_execute`, `script_template`, `batch`, `dry_run` ```python # Create automation workflow await tailscale_automation(operation="workflow_create", workflow_name="daily-backup", workflow_steps=[{"action": "backup", "target": "all"}]) # Execute workflow await tailscale_automation(operation="workflow_execute", workflow_id="workflow123", execute_now=True) # Schedule workflow await tailscale_automation(operation="workflow_schedule", workflow_id="workflow123", schedule_cron="0 2 * * *") # List workflows await tailscale_automation(operation="workflow_list") # Execute custom script await tailscale_automation(operation="script_execute", script_content="print('Hello Tailscale')", script_language="python") # Get script template await tailscale_automation(operation="script_template", template_name="device-audit") # Batch operations await tailscale_automation(operation="batch", batch_operations=[{"operation": "authorize", "device_id": "device123"}]) # Preview operations await tailscale_automation(operation="dry_run", batch_operations=[{"operation": "authorize", "device_id": "device123"}]) ``` --- ### 7. `tailscale_backup` - Backup & Disaster Recovery **Purpose**: Configuration backup, restoration, and disaster recovery planning. **Operations**: `backup_create`, `backup_restore`, `backup_schedule`, `backup_list`, `backup_delete`, `backup_test`, `restore_test`, `recovery_plan` ```python # Create configuration backup await tailscale_backup(operation="backup_create", backup_name="daily-backup", backup_type="full") # Restore from backup await tailscale_backup(operation="backup_restore", backup_id="backup123") # Schedule automated backups await tailscale_backup(operation="backup_schedule", schedule_cron="0 2 * * *", retention_days=30) # List backups await tailscale_backup(operation="backup_list") # Delete backup await tailscale_backup(operation="backup_delete", backup_id="backup123") # Test backup integrity await tailscale_backup(operation="backup_test", backup_id="backup123") # Test restore procedure await tailscale_backup(operation="restore_test", backup_id="backup123") # Create disaster recovery plan await tailscale_backup(operation="recovery_plan") ``` --- ### 8. `tailscale_performance` - Performance Monitoring **Purpose**: Network performance monitoring, optimization, and capacity planning. **Operations**: `latency`, `bandwidth`, `optimize`, `baseline`, `capacity`, `utilization`, `scaling`, `threshold` ```python # Measure network latency await tailscale_performance(operation="latency", device_id="device123", measure_duration=60) # Analyze bandwidth utilization await tailscale_performance(operation="bandwidth", device_id="device123", measure_duration=300) # Optimize routing performance await tailscale_performance(operation="optimize", route_optimization=True) # Establish performance baseline await tailscale_performance(operation="baseline", baseline_name="production", baseline_duration=300) # Predict capacity requirements await tailscale_performance(operation="capacity", capacity_period="30d", scaling_factor=1.2) # Analyze resource utilization await tailscale_performance(operation="utilization", device_id="device123") # Get scaling recommendations await tailscale_performance(operation="scaling", scaling_factor=1.5) # Set performance threshold await tailscale_performance(operation="threshold", performance_threshold=0.8) ``` --- ### 9. `tailscale_reporting` - Advanced Reporting **Purpose**: Custom report generation, analytics, and automated reporting. **Operations**: `generate`, `usage`, `custom`, `schedule`, `export`, `analytics`, `behavior`, `security`, `template` ```python # Generate usage analytics report await tailscale_reporting(operation="usage", date_range="30d", include_charts=True) # Create custom report await tailscale_reporting(operation="custom", custom_fields=["device_count", "bandwidth_usage"], date_range="7d") # Schedule automated reports await tailscale_reporting(operation="schedule", schedule_cron="0 9 * * 1", email_recipients=["admin@company.com"]) # Export reports await tailscale_reporting(operation="export", export_path="/reports/", report_format="pdf") # Deep network analytics await tailscale_reporting(operation="analytics", analytics_depth="comprehensive", date_range="90d") # User behavior analysis await tailscale_reporting(operation="behavior", date_range="30d") # Security metrics await tailscale_reporting(operation="security", date_range="30d", security_focus=True) # Get report template await tailscale_reporting(operation="template", template_name="executive-summary") ``` --- ### 10. `tailscale_integration` - Third-Party Integrations **Purpose**: Webhook management and third-party platform integrations. **Operations**: `webhook_create`, `webhook_test`, `webhook_list`, `webhook_delete`, `slack`, `discord`, `pagerduty`, `datadog`, `test` ```python # Create webhook endpoint await tailscale_integration(operation="webhook_create", webhook_url="https://api.company.com/webhook", webhook_events=["device_connected", "device_disconnected"]) # Test webhook delivery await tailscale_integration(operation="webhook_test", webhook_id="webhook123") # List webhooks await tailscale_integration(operation="webhook_list") # Delete webhook await tailscale_integration(operation="webhook_delete", webhook_id="webhook123") # Integrate with Slack await tailscale_integration(operation="slack", slack_channel="#tailscale-alerts", api_key="slack-api-key") # Integrate with Discord await tailscale_integration(operation="discord", discord_webhook="https://discord.com/api/webhooks/...") # Integrate with PagerDuty await tailscale_integration(operation="pagerduty", pagerduty_key="pagerduty-integration-key") # Integrate with Datadog await tailscale_integration(operation="datadog", datadog_api_key="datadog-api-key", api_endpoint="https://api.datadoghq.com") # Test integration connection await tailscale_integration(operation="test", integration_type="slack", api_key="slack-api-key", test_connection=True) ``` --- ## 🏗️ **Architecture & Implementation** ### **Portmanteau Pattern Benefits** 1. **Consolidated Interface**: Each tool handles multiple related operations 2. **Consistent Parameters**: All tools use the `operation` parameter pattern 3. **Domain Separation**: Related functionality grouped logically 4. **Maintainability**: Single file per domain instead of many small files 5. **Extensibility**: Easy to add new operations to existing tools ### **Implementation Structure** ``` src/tailscalemcp/tools/ └── portmanteau_tools.py # Single file with all 10 portmanteau tools ├── TailscalePortmanteauTools # Main class ├── tailscale_device() # Device & user management ├── tailscale_network() # DNS & network management ├── tailscale_monitor() # Monitoring & metrics ├── tailscale_file() # File sharing ├── tailscale_security() # Security & compliance ├── tailscale_automation() # Workflow automation ├── tailscale_backup() # Backup & recovery ├── tailscale_performance() # Performance monitoring ├── tailscale_reporting() # Advanced reporting └── tailscale_integration() # Third-party integrations ``` ### **Tool Registration** All tools are registered in the main MCP server: ```python # src/tailscalemcp/mcp_server.py class TailscaleMCPServer: def _initialize_portmanteau_tools(self) -> None: self.portmanteau_tools = TailscalePortmanteauTools( self.mcp, self.device_manager, self.monitor, self.grafana_dashboard, self.taildrop_manager, self.magic_dns_manager, ) ``` --- ## 🎯 **Usage Patterns** ### **Common Operations** ```python # Device management devices = await tailscale_device(operation="list", online_only=True) device = await tailscale_device(operation="get", device_id="device123") # Network configuration await tailscale_network(operation="magic_dns", enabled=True) await tailscale_network(operation="dns_record", name="api.internal", record_type="A", value="100.64.0.1") # Monitoring status = await tailscale_monitor(operation="status") metrics = await tailscale_monitor(operation="prometheus") # Security await tailscale_security(operation="scan", scan_type="comprehensive") await tailscale_security(operation="compliance", compliance_standard="SOC2") ``` ### **Batch Operations** ```python # Batch device authorization operations = [ {"operation": "authorize", "device_id": "device123", "authorize": True}, {"operation": "authorize", "device_id": "device456", "authorize": True}, {"operation": "tag", "device_id": "device123", "tags": ["engineering"]} ] await tailscale_automation(operation="batch", batch_operations=operations) ``` ### **Scheduled Operations** ```python # Schedule daily backups await tailscale_backup(operation="backup_schedule", schedule_cron="0 2 * * *", retention_days=30) # Schedule weekly reports await tailscale_reporting(operation="schedule", schedule_cron="0 9 * * 1", email_recipients=["admin@company.com"]) ``` --- ## 🔧 **Configuration & Setup** ### **Environment Variables** ```bash # Required TAILSCALE_API_KEY=your-api-key TAILSCALE_TAILNET=your-tailnet # Optional TAILSCALE_LOG_LEVEL=INFO TAILSCALE_TIMEOUT=30 ``` ### **Installation** ```bash # Install from PyPI pip install tailscalemcp # Or from source git clone https://github.com/yourusername/tailscale-mcp.git cd tailscale-mcp pip install -e . ``` ### **Basic Usage** ```python from tailscalemcp import TailscaleMCPServer # Initialize server server = TailscaleMCPServer( api_key="your-api-key", tailnet="your-tailnet" ) # Start server await server.start() ``` --- ## 📊 **Performance & Scalability** ### **Tool Performance** - **Response Time**: < 100ms for most operations - **Concurrent Operations**: Supports up to 100 concurrent requests - **Memory Usage**: ~50MB base + 10MB per 1000 devices - **Throughput**: 1000+ operations per minute ### **Scalability Features** - **Async Operations**: All tools are fully asynchronous - **Connection Pooling**: Efficient HTTP connection management - **Caching**: Intelligent caching for frequently accessed data - **Rate Limiting**: Built-in rate limiting to prevent API abuse --- ## 🛡️ **Security & Compliance** ### **Security Features** - **API Key Management**: Secure storage and rotation of API keys - **Audit Logging**: Comprehensive audit trail for all operations - **Access Control**: Role-based access control for different operations - **Encryption**: All data encrypted in transit and at rest ### **Compliance Standards** - **SOC 2**: Full compliance with SOC 2 Type II requirements - **PCI DSS**: Payment card industry compliance - **HIPAA**: Healthcare information privacy compliance - **ISO 27001**: Information security management compliance --- ## 🚀 **Future Roadmap** ### **Planned Enhancements** 1. **AI-Powered Insights**: Machine learning for network optimization 2. **Advanced Analytics**: Predictive analytics for capacity planning 3. **Mobile App**: Native mobile app for iOS and Android 4. **Enterprise Features**: SSO, LDAP integration, advanced RBAC 5. **API Extensions**: GraphQL API, webhooks, real-time streaming ### **Community Contributions** We welcome contributions! Please see our [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines. --- ## 📚 **Additional Resources** - **README.md**: Quick start guide and installation - **API Reference**: Complete API documentation - **Examples**: Usage examples and best practices - **Troubleshooting**: Common issues and solutions - **GitHub Issues**: Bug reports and feature requests --- *TailscaleMCP Portmanteau Tools Documentation* *Version: 1.0.0* *Last Updated: December 2024* *Total Operations: 91* *Portmanteau Tools: 10* *Status: Production Ready* 🚀