mcp-ShellGateway: Instructions file for Claude Code

CLAUDE.md

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

Common Development Commands

Testing

# Run all tests
python -m pytest tests/

# Run tests with coverage
python -m pytest tests/ --cov=linux_shell_server --cov-report=html

# Run specific test file
python -m pytest tests/test_main.py -v

Code Quality

# Format code
black linux_shell_server/ tests/

# Check code style
ruff check linux_shell_server/ tests/

# Sort imports
isort linux_shell_server/ tests/

# Type checking
mypy linux_shell_server/

Running the Server

# Test server directly
python -m linux_shell_server.main

Architecture Overview

This is an MCP (Model Context Protocol) server that provides Linux shell command execution capabilities to Claude Desktop.

Core Components

ShellExecutor (linux_shell_server/main.py:68-293):

• Manages command execution with async subprocess calls
• Handles timeouts (30s default, 120s for long commands)
• Maintains working directory state
• Implements command result caching for performance
• Truncates output at 10KB to prevent memory issues

MCP Protocol Implementation (linux_shell_server/main.py:297-428):

• Three tools: execute_command, change_directory, get_current_directory
• Implements required MCP endpoints: list_tools, list_resources, list_prompts, call_tool
• Uses stdio for communication with Claude Desktop

Key Design Patterns

1. Process Management: Creates process groups for proper cleanup on timeout
2. Error Handling: All operations return structured error responses
3. Path Validation: Directory changes are validated before execution
4. Async Architecture: Built on asyncio for non-blocking operations

Testing Approach

Tests in tests/test_main.py cover:

• Command execution success/failure cases
• Directory operations and validation
• MCP protocol handler responses
• Edge cases (empty commands, invalid paths, timeouts)