mcp-imagemagick: 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

This is an MCP (Model Context Protocol) server for image conversion, primarily focused on converting DNG (Digital Negative) files to WebP format using ImageMagick and darktable. The server implements the MCP protocol with stdio transport and provides tools for image conversion.

Common Development Commands

Building

# Development build
cargo build

# Release build (optimized)
cargo build --release

Testing

# Run unit tests
cargo test

# Run integration tests
python3 test_mcp.py

# Test MCP protocol manually
./test_protocol.py

# Quick server test
./test_server.sh

Running and Debugging

# Run with debug logging
RUST_LOG=debug cargo run

# Run release binary
./target/release/mcp-imagemagick

# Test with MCP Inspector (if installed)
mcp-inspector ./target/release/mcp-imagemagick

Code Quality

# Format code
cargo fmt

# Run linter
cargo clippy

# Check for issues without building
cargo check

High-Level Architecture

The codebase follows a modular architecture with clear separation of concerns:

Core Components

1. MCP Server Layer (src/server.rs)

   • Handles JSON-RPC protocol implementation
   • Routes requests to appropriate handlers
   • Manages the message loop and response formatting
   • Implements MCP methods: initialize, tools/list, tools/call

2. Transport Layer (src/transport.rs)

   • Manages stdio communication (stdin/stdout)
   • Handles async message passing between threads
   • Buffers and parses JSON-RPC messages

3. Converter System (src/converters/)

   • Trait-based Design: All converters implement the ImageConverter trait
   • Auto-selection: AutoConverter automatically selects the best available converter based on priority
   • ImageMagick Converter: Priority 60, uses convert7 or magick command
   • Darktable Converter: Priority 40, uses darktable-cli for better RAW processing
   • Converters are checked for availability using the which crate