Files

kappa 31d0e9b97f Fix npm package deployment and usage documentation

🔧 Resolve npmjs deployment issue:
- Add npm global installation guide (npm install -g @ironclads/incus-mcp)
- Update Claude Desktop configuration with two options
- Fix mcp-config-example.json to use global binary
- Update CLAUDE.md with correct remote server list (removed lambda)

✅ npm package now works correctly with global installation
📚 Documentation updated with clear installation options

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-08-10 21:53:37 +09:00

4.7 KiB

Raw Permalink Blame History

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)

incus_list_instances: List all instances with status (supports remote servers)
incus_show_instance: Show detailed instance configuration and state
incus_start_instance: Start stopped instances
incus_stop_instance: Stop running instances (with force option)
incus_restart_instance: Restart instances (with force option)
incus_create_instance: Create new instances from images
incus_delete_instance: Delete instances (with force option)
incus_exec_command: Execute commands inside running instances
incus_list_remotes: List all configured remote servers
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: Japan remote server (100.109.123.1:8443)
kr1: Korea remote server (100.84.111.28:8443)
local: Local Incus daemon
images: LinuxContainers.org image server
docker: Docker Hub OCI registry
ghcr: GitHub Container Registry

Common Operations

Development Workflow

# 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

# 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.

4.7 KiB Raw Permalink Blame History