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