OxiDex MCP Server

MCP (Model Context Protocol) server for OxiDex metadata operations, enabling AI assistants to extract, search, analyze, and modify file metadata through a standardized protocol.

Overview

OxiDex MCP Server is a standalone implementation of the Model Context Protocol that exposes OxiDex's powerful metadata extraction and manipulation capabilities to AI assistants like Claude, Cline, and other MCP-compatible clients.

Parent Project: OxiDex - A high-performance Rust implementation of ExifTool with 32,677+ metadata tags across 140+ format families.

Features

Available Tools

• extract_metadata - Extract metadata from files (supports glob patterns)
• write_metadata - Write or update metadata tags (with dry-run support)
• search_metadata - Search files by metadata criteria with flexible filters
• analyze_metadata - Generate statistical summaries of metadata across files
• copy_metadata - Copy metadata between files or to multiple destinations

Key Capabilities

• Glob Pattern Support - Process multiple files with *.jpg, photos/**/*.png, etc.
• Dry-Run Mode - Preview changes before applying them
• Rich Filtering - Search with operators: =, >, <, ~ (contains)
• Batch Operations - Efficiently process large file collections
• Security - Path validation, no arbitrary command execution
• JSON-RPC 2.0 - Standard protocol over stdin/stdout

Installation

Prerequisites

• Rust 1.70+ (install from rustup.rs)
• Just command runner (optional but recommended)

Quick Install

# Clone the repository
git clone https://github.com/swack-tools/oxidex-mcp.git
cd oxidex-mcp

# Build and install to ~/.local/bin
just install

# Or install to a custom location
just install-to /usr/local/bin

Manual Build

cargo build --release
cp target/release/oxidex-mcp ~/.local/bin/

Configuration

Claude Desktop (macOS)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "oxidex": {
      "command": "/Users/your-username/.local/bin/oxidex-mcp",
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}

Show config template with your actual paths:

just claude-desktop-config

Generic MCP Client

{
  "mcpServers": {
    "oxidex": {
      "command": "/path/to/oxidex-mcp",
      "args": [],
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}

Usage Examples

Extract Metadata

Extract from a single file:

{
  "name": "extract_metadata",
  "arguments": {
    "path": "photo.jpg"
  }
}

Extract from multiple files:

{
  "name": "extract_metadata",
  "arguments": {
    "path": "photos/*.jpg"
  }
}

Write Metadata

Preview changes (dry-run):

{
  "name": "write_metadata",
  "arguments": {
    "path": "*.jpg",
    "tags": {
      "Artist": "John Doe",
      "Copyright": "© 2024"
    },
    "dry_run": true
  }
}

Apply changes:

{
  "name": "write_metadata",
  "arguments": {
    "path": "photo.jpg",
    "tags": {
      "Artist": "John Doe"
    },
    "dry_run": false
  }
}

Search by Metadata

Find files matching criteria:

{
  "name": "search_metadata",
  "arguments": {
    "directory": "photos",
    "filters": ["Make=Canon", "DateTimeOriginal>2024-01-01"]
  }
}

Filter Operators:

• = Equals (e.g., Make=Canon)
• > Greater than (e.g., FileSize>1000000)
• < Less than (e.g., FileSize<1000000)
• ~ Contains (e.g., Model~R5)

Analyze Metadata

Generate statistics:

{
  "name": "analyze_metadata",
  "arguments": {
    "path": "photos/*.jpg"
  }
}

Copy Metadata

Copy to a single file:

{
  "name": "copy_metadata",
  "arguments": {
    "source": "template.jpg",
    "destination": "photo.jpg",
    "dry_run": true
  }
}

Copy to multiple files:

{
  "name": "copy_metadata",
  "arguments": {
    "source": "template.jpg",
    "destination": "photos/*.jpg"
  }
}

Development

Available Commands

just                 # Show all available commands
just build           # Build release binary
just build-debug     # Build debug binary
just test            # Run all tests
just test-debug      # Run tests in debug mode
just check           # Check code without building
just fmt             # Format code
just lint            # Run clippy lints
just ci              # Run full CI suite (fmt + lint + test)
just clean           # Clean build artifacts

Running Tests

# Run all tests
just test

# Run specific test suite
just test-suite integration_tests

# Run with debug output
cargo test -- --nocapture

Testing the Server Manually

# Test initialize
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | cargo run --quiet

# Test tools/list
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | cargo run --quiet

# Test extract_metadata
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"extract_metadata","arguments":{"path":"Cargo.toml"}}}' | cargo run --quiet

Architecture

Protocol Flow

1. Client sends JSON-RPC 2.0 request via stdin
2. Server parses and routes to appropriate handler
3. Tool processes request (expand globs, validate, execute)
4. Results formatted as human-readable text
5. Response sent via stdout as JSON-RPC

Tool Implementation Pattern

Each tool in src/tools/ follows:

1. Parse arguments from JSON
2. Validate input paths (security)
3. Expand glob patterns if needed
4. Process files using OxiDex
5. Format results as text
6. Return JSON-RPC response

Security

• Path validation prevents directory traversal
• Glob patterns validated and constrained
• Dry-run support for destructive operations
• No arbitrary command execution
• All operations sandboxed to file system

Documentation

• MCP Integration Guide - Integration with AI clients
• Server Design - Architecture and design decisions
• Implementation Plan - Development roadmap
• Expansion Plan - Future enhancements

Project Status

Current Version: 0.1.0

This is a standalone breakout from the main OxiDex repository, providing independent versioning, documentation, and release cycles for the MCP server.

Roadmap

• ✅ Core MCP protocol implementation
• ✅ Five essential metadata tools
• ✅ Glob pattern support
• ✅ Dry-run safety mode
• ⏳ Full OxiDex library integration (currently using placeholders)
• ⏳ Format-specific metadata handlers (EXIF, IPTC, XMP)
• ⏳ Advanced search and filtering
• ⏳ Streaming support for large files

License

GPL-3.0 - Same as OxiDex

Contributing

Contributions welcome! Please see the parent OxiDex project for contribution guidelines.

See Also

• OxiDex - Main metadata extraction library
• MCP Specification - Model Context Protocol docs
• ExifTool - Original Perl implementation

---

Built with ❤️ in Rust