vps-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MCP VPS Manager is a secure, production-ready Model Context Protocol (MCP) server that enables Large Language Models to safely manage Virtual Private Servers via SSH. The project provides comprehensive VPS management capabilities with built-in security controls, connection pooling, and audit logging.

Development Commands

Testing

# Run all tests
./run_tests.sh

# Run specific test suites
./run_tests.sh unit          # Unit tests only
./run_tests.sh integration   # Integration tests only
./run_tests.sh coverage      # Tests with coverage report
./run_tests.sh lint          # Linting and code quality checks
./run_tests.sh format        # Code formatting

# Run tests with Poetry
poetry run pytest

# Run specific test with verbose output
poetry run pytest tests/unit/test_security.py -v

# Run tests with coverage
poetry run pytest --cov=src/vps_manager --cov-report=html

Code Quality

# Format code
make format
# Or with individual tools
poetry run black src/ tests/
poetry run isort src/ tests/

# Run linting
make lint
# Or with individual tools
poetry run flake8 src/ tests/
poetry run mypy src/

# Run all quality checks
make check

Development Server

# Run development server with debug logging
make dev-server
# Or directly
python bin/mcp-vps-manager --config config/servers.yaml --log-level DEBUG

# Run with Poetry
poetry run mcp-vps-manager --config config/servers.yaml

Package Management

# Install in development mode
make install-dev
# Or with Poetry
poetry install

# Build package
make build
# Or with Poetry
poetry build

# Clean build artifacts
make clean

Architecture Overview

Core Components

The project follows a layered architecture with clear separation of concerns:

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Claude/LLM    │───▶│  MCP VPS Server  │───▶│  VPS Servers    │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                              ▼
                    ┌──────────────────┐
                    │  Security Layer  │
                    │  Connection Pool │
                    │  Command Queue   │
                    │  Audit Logging   │
                    └──────────────────┘