oxidex-mcp

swack-tools/oxidex-mcp

3.2

If you are the rightful owner of oxidex-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

OxiDex MCP Server is a standalone implementation of the Model Context Protocol, designed to facilitate metadata operations for AI assistants.

Tools
5
Resources
0
Prompts
0

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

  • - Integration with AI clients
  • - Architecture and design decisions
  • - Development roadmap
  • - 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

Built with ❤️ in Rust