@ironclads/incus-mcp 0.1.0

package/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "enabledMcpjsonServers": [
+    "context7",
+    "sequential-thinking",
+    "playwright",
+    "cloudflare",
+    "podman",
+    "incus"
+  ]
+}

package/.eslintrc.json

@@ -0,0 +1,23 @@
+{
+  "env": {
+    "node": true,
+    "es2022": true
+  },
+  "extends": [
+    "eslint:recommended",
+    "@typescript-eslint/recommended"
+  ],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": 2022,
+    "sourceType": "module"
+  },
+  "plugins": ["@typescript-eslint"],
+  "rules": {
+    "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
+    "@typescript-eslint/explicit-function-return-type": "off",
+    "@typescript-eslint/no-explicit-any": "warn",
+    "prefer-const": "error",
+    "no-var": "error"
+  }
+}

package/.mcp.json

@@ -0,0 +1,38 @@
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
+    },
+    "sequential-thinking": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-sequential-thinking"
+      ]
+    },
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@playwright/mcp"
+      ],
+      "env": {}
+    },
+    "cloudflare": {
+	    "command": "npx",
+	    "args": ["mcp-remote", "https://docs.mcp.cloudflare.com/sse"]
+    },
+    "podman": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "podman-mcp-server@latest"
+      ]
+    },
+    "incus": {
+        "command": "node",
+        "args": ["/Users/kaffa/mcp-servers/incus-mcp/build/index.js"]
+      }
+  }
+}

package/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false
+}

package/CLAUDE.md

@@ -0,0 +1,127 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is the **Incus MCP Server** - a complete Model Context Protocol implementation for managing Incus containers and virtual machines. This repository contains both the MCP server implementation and configuration files for integration with Claude Code and other MCP clients.
+
+## Project Structure
+
+### Core Implementation
+- **Source Code**: TypeScript implementation in `src/` directory
+  - `index.ts`: Main MCP server with all tool and resource handlers
+  - `incus.ts`: Incus command execution utilities and error handling
+  - `schemas.ts`: Tool and resource schema definitions for MCP protocol
+- **Build Output**: Compiled JavaScript in `build/` directory
+- **Tests**: Comprehensive test suite in `test/` directory
+
+### Configuration Files
+- **package.json**: Node.js project configuration with TypeScript build system
+- **tsconfig.json**: TypeScript compiler configuration
+- **.mcp.json**: MCP server configuration for local development and testing
+
+## MCP Server Configuration
+
+### Available Servers
+The `.mcp.json` file configures six MCP servers:
+
+- **context7**: Documentation and code examples lookup using `@upstash/context7-mcp`
+- **sequential-thinking**: Complex multi-step analysis using `@modelcontextprotocol/server-sequential-thinking`  
+- **playwright**: Browser automation and E2E testing using `@playwright/mcp`
+- **cloudflare**: Cloudflare documentation access via remote MCP endpoint
+- **podman**: Container management using `podman-mcp-server`
+- **incus**: Local Incus container management (this project's main server)
+
+### Claude Code Integration
+The `.claude/settings.local.json` file enables all configured MCP servers for Claude Code sessions in this directory.
+
+## Incus MCP Server Capabilities
+
+### Tools (10 available)
+1. **incus_list_instances**: List all instances with status (supports remote servers)
+2. **incus_show_instance**: Show detailed instance configuration and state
+3. **incus_start_instance**: Start stopped instances
+4. **incus_stop_instance**: Stop running instances (with force option)
+5. **incus_restart_instance**: Restart instances (with force option)
+6. **incus_create_instance**: Create new instances from images
+7. **incus_delete_instance**: Delete instances (with force option)
+8. **incus_exec_command**: Execute commands inside running instances
+9. **incus_list_remotes**: List all configured remote servers
+10. **incus_info**: Show Incus system information
+
+### Resources (2 available)
+- **incus://instances/list**: JSON list of all instances across all remotes
+- **incus://remotes/list**: JSON list of all configured remote servers
+
+### Remote Server Support
+The server automatically works with all configured Incus remotes:
+- **jp1**: Primary remote server (current)
+- **kr1**: Secondary remote server
+- **lambda**: Additional remote server
+- **local**: Local Incus daemon
+- **images**: LinuxContainers.org image server
+- **docker**: Docker Hub OCI registry
+- **ghcr**: GitHub Container Registry
+
+## Common Operations
+
+### Development Workflow
+```bash
+# Install dependencies
+npm install
+
+# Development mode with auto-reload
+npm run dev
+
+# Build TypeScript to JavaScript
+npm run build
+
+# Run the MCP server
+npm start
+
+# Run tests
+node test/simple-test.js
+node test/resource-test.js
+```
+
+### Production Deployment
+```bash
+# Build for production
+npm run build
+
+# Run the server directly
+node build/index.js
+```
+
+### Configuration Updates
+- Modify `src/schemas.ts` to add new tools or resources
+- Update `src/index.ts` to implement new functionality
+- Rebuild with `npm run build` after changes
+- Test with provided test scripts
+
+## Architecture Notes
+
+This is a full-featured MCP server implementation with:
+
+- **Protocol Layer**: Complete MCP protocol implementation using official SDK
+- **Command Layer**: Safe Incus command execution with proper error handling
+- **Validation Layer**: Zod schema validation for all tool arguments
+- **Transport Layer**: Standard stdio transport for MCP communication
+- **Security Layer**: Input validation and command sanitization
+
+The server is designed for:
+- **Local Development**: Direct integration with local Incus daemon
+- **Remote Management**: Support for multiple Incus remotes
+- **Production Use**: Robust error handling and logging
+- **Claude Integration**: Optimized for Claude Code and Claude Desktop
+
+## Testing and Validation
+
+The repository includes comprehensive tests:
+- **Integration Tests**: Full MCP protocol communication tests
+- **Tool Tests**: Individual tool execution validation
+- **Resource Tests**: Resource reading and JSON parsing verification
+- **Error Tests**: Proper error handling for invalid inputs
+
+All tests validate against real Incus installations with multiple configured remotes.

package/README.md

@@ -0,0 +1,315 @@
+# Incus MCP Server
+
+A comprehensive Model Context Protocol (MCP) server for managing Incus containers and virtual machines. This server provides a complete set of tools and resources to interact with Incus instances locally and across remote servers through the MCP protocol.
+
+## ⭐ Key Features
+
+### 🛠 Tools (10 Available)
+- **incus_list_instances**: List all instances with their current status (supports remote servers)
+- **incus_show_instance**: Show detailed information about a specific instance
+- **incus_start_instance**: Start stopped instances
+- **incus_stop_instance**: Stop running instances (with optional force flag)
+- **incus_restart_instance**: Restart instances (with optional force flag)
+- **incus_create_instance**: Create new instances from images with custom configuration
+- **incus_delete_instance**: Delete instances (with optional force flag)
+- **incus_exec_command**: Execute commands inside running instances
+- **incus_list_remotes**: List all configured remote servers
+- **incus_info**: Show comprehensive Incus system information
+
+### 📚 Resources (2 Available)
+- **incus://instances/list**: JSON list of all instances across all remotes
+- **incus://remotes/list**: JSON list of all configured remote servers with connection details
+
+### 🌐 Multi-Remote Support
+Seamlessly works with all your configured Incus remotes:
+- **Local instances**: Direct access to local Incus daemon
+- **Remote servers**: Full support for TLS-authenticated remote Incus servers
+- **Image sources**: Integration with LinuxContainers.org, Docker Hub, GitHub Container Registry
+- **Automatic discovery**: Automatically detects and works with existing remote configurations
+
+## 📋 Prerequisites
+
+- **Node.js 18+**: Required for running the TypeScript/JavaScript server
+- **Incus installed**: Working Incus installation with daemon running
+- **Proper permissions**: User must be in `incus` group or have appropriate file access
+- **Remote configuration**: Pre-configured remote servers (optional but recommended)
+
+## 🚀 Quick Start
+
+### Installation from Source
+```bash
+# Clone the repository
+git clone https://github.com/your-username/incus-mcp.git
+cd incus-mcp
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Test the installation
+npm test
+```
+
+### Verify Incus Setup
+```bash
+# Check Incus is working
+incus version
+incus list
+incus remote list
+```
+
+## 💻 Usage
+
+### Standalone MCP Server
+```bash
+# Run the server directly
+node build/index.js
+
+# Development mode with auto-reload
+npm run dev
+
+# Production mode
+npm start
+```
+
+### Integration with Claude Desktop
+
+Add to your Claude Desktop MCP configuration (`~/.config/claude-desktop/config.json`):
+
+```json
+{
+  "mcpServers": {
+    "incus": {
+      "command": "node",
+      "args": ["/absolute/path/to/incus-mcp/build/index.js"],
+      "env": {
+        "PATH": "/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin"
+      }
+    }
+  }
+}
+```
+
+### Integration with Claude Code
+
+The repository includes `.mcp.json` for local development:
+
+```json
+{
+  "mcpServers": {
+    "incus": {
+      "command": "node",
+      "args": ["/Users/kaffa/mcp-servers/incus-mcp/build/index.js"]
+    }
+  }
+}
+```
+
+## 🔧 Development
+
+### Development Workflow
+```bash
+# Install dependencies
+npm install
+
+# Development mode with auto-reload
+npm run dev
+
+# Build TypeScript to JavaScript
+npm run build
+
+# Run comprehensive tests
+node test/simple-test.js
+node test/resource-test.js
+
+# Code quality
+npm run lint
+npm run format
+```
+
+### Project Structure
+```
+incus-mcp/
+├── src/
+│   ├── index.ts          # Main MCP server implementation
+│   ├── incus.ts          # Incus command execution utilities  
+│   └── schemas.ts        # MCP tool/resource schema definitions
+├── test/
+│   ├── simple-test.js    # Basic functionality tests
+│   └── resource-test.js  # Resource reading tests
+├── build/                # Compiled JavaScript output
+├── .mcp.json            # Local MCP server configuration
+└── mcp-config-example.json  # Claude Desktop config template
+```
+
+## ⚙️ Configuration
+
+### System Requirements
+The server automatically uses your existing Incus configuration:
+
+1. **Incus daemon running**: `systemctl status incus` (Linux) or check process list
+2. **User permissions**: Member of `incus` group or appropriate file access
+3. **Remote servers**: Pre-configured remotes work automatically
+
+### Setting up Remote Servers
+```bash
+# Add a remote Incus server
+incus remote add myserver https://server.example.com:8443
+
+# Add with custom certificate
+incus remote add myserver https://server.example.com:8443 --password
+
+# List all configured remotes
+incus remote list
+
+# Test remote connection
+incus list myserver:
+```
+
+### Environment Variables
+```bash
+# Optional: Custom PATH for incus binary
+export PATH="/opt/incus/bin:$PATH"
+
+# Optional: Debug MCP communication
+export MCP_DEBUG=1
+```
+
+## 📖 Usage Examples
+
+### Basic Instance Management
+```bash
+# Via MCP tools (conceptual - actual usage through MCP client)
+incus_list_instances: {}
+# Returns: List of all instances across all remotes
+
+incus_create_instance: {
+  "name": "webserver", 
+  "image": "ubuntu:22.04",
+  "config": {"limits.cpu": "2", "limits.memory": "2GB"}
+}
+
+incus_start_instance: {"name": "webserver"}
+```
+
+### Remote Operations
+```bash
+incus_list_instances: {"remote": "jp1"}
+# Lists instances only from the jp1 remote server
+
+incus_show_instance: {"name": "myapp", "remote": "kr1"}  
+# Shows details for 'myapp' instance on kr1 server
+```
+
+### Command Execution
+```bash
+incus_exec_command: {
+  "instance": "webserver",
+  "command": "apt update && apt install -y nginx",
+  "remote": "jp1"
+}
+```
+
+### Resource Access
+- `incus://instances/list` → JSON array of all instances with full metadata
+- `incus://remotes/list` → JSON object with remote server configurations
+
+## 🛡️ Security & Error Handling
+
+### Security Features
+- **Input validation**: All arguments validated with Zod schemas
+- **Command sanitization**: No shell injection vulnerabilities
+- **Permission isolation**: Uses existing Incus user permissions
+- **Remote auth**: Leverages configured TLS certificates
+- **Audit trail**: All commands logged through Incus
+
+### Error Handling
+- **Graceful failures**: Comprehensive error messages without exposing internals
+- **Network timeouts**: Proper handling of remote server connectivity issues
+- **Permission errors**: Clear guidance for permission-related problems
+- **Invalid arguments**: Detailed validation error messages
+
+## 🐛 Troubleshooting
+
+### Common Issues & Solutions
+
+#### 1. Permission Denied
+```bash
+# Add user to incus group
+sudo usermod -a -G incus $USER
+newgrp incus
+
+# Verify permissions
+id | grep incus
+incus list  # Should work without sudo
+```
+
+#### 2. Incus Not Found
+```bash
+# Check installation
+which incus
+incus version
+
+# Install on Ubuntu/Debian
+curl -fsSL https://packagecloud.io/install/repositories/candid/incus/script.deb.sh | sudo bash
+sudo apt install incus
+
+# Install on macOS
+brew install incus
+```
+
+#### 3. Remote Connection Issues
+```bash
+# Verify remote configuration
+incus remote list
+
+# Test connectivity
+incus info remote-name:
+
+# Re-add problematic remote
+incus remote remove old-remote
+incus remote add old-remote https://server:8443
+```
+
+#### 4. MCP Server Issues
+```bash
+# Test MCP server directly
+node build/index.js
+# Should show: "Incus MCP server running on stdio"
+
+# Check build output
+npm run build
+ls -la build/
+
+# Run test suite
+node test/simple-test.js
+```
+
+### Debug Mode
+```bash
+# Enable verbose logging
+DEBUG=mcp* node build/index.js
+
+# Test individual tools
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node build/index.js
+```
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature-name`
+3. Make your changes and add tests
+4. Run the test suite: `node test/*.js`
+5. Submit a pull request
+
+## 📄 License
+
+MIT License - see LICENSE file for details.
+
+---
+
+**Built with ❤️ for the Incus and MCP communities**
+
+For support, please open an issue on GitHub or check the [MCP documentation](https://modelcontextprotocol.io/).

package/build/incus.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Execute an incus command and return the output
+ */
+export declare function execIncusCommand(args: string[]): Promise<string>;
+/**
+ * Parse incus JSON output safely
+ */
+export declare function parseIncusOutput<T = any>(output: string): T;
+/**
+ * Check if incus is available and accessible
+ */
+export declare function checkIncusAvailability(): Promise<boolean>;
+/**
+ * Get incus version information
+ */
+export declare function getIncusVersion(): Promise<string>;
+//# sourceMappingURL=incus.d.ts.map

package/build/incus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"incus.d.ts","sourceRoot":"","sources":["../src/incus.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA8BtE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,GAAG,EAAE,MAAM,EAAE,MAAM,GAAG,CAAC,CAM3D;AAED;;GAEG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,OAAO,CAAC,CAO/D;AAED;;GAEG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CAMvD"}

package/build/incus.js

@@ -0,0 +1,66 @@
+import { spawn } from 'child_process';
+/**
+ * Execute an incus command and return the output
+ */
+export async function execIncusCommand(args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('incus', args, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env },
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout?.on('data', (data) => {
+            stdout += data.toString();
+        });
+        child.stderr?.on('data', (data) => {
+            stderr += data.toString();
+        });
+        child.on('close', (code) => {
+            if (code === 0) {
+                resolve(stdout.trim());
+            }
+            else {
+                reject(new Error(`Incus command failed (exit code ${code}): ${stderr || stdout}`));
+            }
+        });
+        child.on('error', (error) => {
+            reject(new Error(`Failed to execute incus command: ${error.message}`));
+        });
+    });
+}
+/**
+ * Parse incus JSON output safely
+ */
+export function parseIncusOutput(output) {
+    try {
+        return JSON.parse(output);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse incus output as JSON: ${error}`);
+    }
+}
+/**
+ * Check if incus is available and accessible
+ */
+export async function checkIncusAvailability() {
+    try {
+        await execIncusCommand(['version']);
+        return true;
+    }
+    catch (error) {
+        return false;
+    }
+}
+/**
+ * Get incus version information
+ */
+export async function getIncusVersion() {
+    try {
+        return await execIncusCommand(['version']);
+    }
+    catch (error) {
+        throw new Error(`Failed to get incus version: ${error}`);
+    }
+}
+//# sourceMappingURL=incus.js.map

package/build/incus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"incus.js","sourceRoot":"","sources":["../src/incus.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAGtC;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAc;IACnD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE;YACjC,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC;YACjC,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE;SACxB,CAAC,CAAC;QAEH,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,MAAM,GAAG,EAAE,CAAC;QAEhB,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;YAChC,MAAM,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC5B,CAAC,CAAC,CAAC;QAEH,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;YAChC,MAAM,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC5B,CAAC,CAAC,CAAC;QAEH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;YACzB,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;gBACf,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;YACzB,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,IAAI,KAAK,CAAC,mCAAmC,IAAI,MAAM,MAAM,IAAI,MAAM,EAAE,CAAC,CAAC,CAAC;YACrF,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YAC1B,MAAM,CAAC,IAAI,KAAK,CAAC,oCAAoC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QACzE,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAU,MAAc;IACtD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,yCAAyC,KAAK,EAAE,CAAC,CAAC;IACpE,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB;IAC1C,IAAI,CAAC;QACH,MAAM,gBAAgB,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;QACpC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe;IACnC,IAAI,CAAC;QACH,OAAO,MAAM,gBAAgB,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;IAC7C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,gCAAgC,KAAK,EAAE,CAAC,CAAC;IAC3D,CAAC;AACH,CAAC"}

package/build/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}