31d0e9b97f
🔧 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>
126 lines
4.7 KiB
Markdown
126 lines
4.7 KiB
Markdown
# 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**: 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
|
|
```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. |