supervisord-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

Supervisord MCP is a process management system that integrates Supervisord with the Model Context Protocol (MCP). It enables AI agents to control production and development processes through standardized MCP tools and resources.

Architecture

The system follows a clean architecture pattern:

CLI → Manager → Supervisord XML-RPC API
MCP Server → Manager → Supervisord XML-RPC API

Key components:

• SupervisordManager: Core business logic for Supervisord operations via XML-RPC
• SupervisordMCPServer: MCP protocol implementation for AI agent communication
• CLI: Command-line interface using Click framework
• Async Architecture: All operations are async for better performance

Development Commands

Installation and Setup

# Install dependencies with uv
uv sync

# Install development dependencies
uv sync --extra dev

# Install in development mode
uv pip install -e .

Running the Application

# Start MCP server (main application for AI agents)
uv run supervisord-mcp mcp

# Use CLI interface
uv run supervisord-mcp start myapp
uv run supervisord-mcp list-processes
uv run supervisord-mcp logs myapp

# With custom server URL
uv run supervisord-mcp --server-url http://remote:9001/RPC2 info

Testing

# Run all tests
uv run pytest tests/ -v

# Run with coverage
uv run pytest tests/ --cov=supervisord_mcp --cov-report=html

# Run integration tests (requires running Supervisord)
uv run pytest tests/ -m integration

Code Quality

# Format code
uv run ruff format src/ tests/

# Lint code
uv run ruff check src/ tests/

# Type checking
uv run mypy src/

Configuration

Supervisord Setup

The system requires a running Supervisord instance with XML-RPC interface enabled:

[inet_http_server]
port=127.0.0.1:9001

[rpcinterface:supervisor]
supervisor.rpcinterface_factory = supervisor.rpcinterface:make_main_rpcinterface