InkTag

A lightweight, robust C# utility, CLI tool, MCP Server, and desktop application designed to bulk-edit ComicInfo.xml metadata embedded inside comic book archives (.cbz and .cbr).

The project contains a core domain library (InkTag.Core), an AI-agent-friendly CLI (InkTag.Cli), a Model Context Protocol server (InkTag.Mcp), and an Avalonia desktop GUI interface (InkTag.Gui).

---

🚀 Key Features

• Dual-Format Processing: Supports reading both .cbz (ZIP-based) and .cbr (RAR/RAR-like) archives using random-access ArchiveFactory.OpenArchive().
• Cross-Platform MenuBar & NativeMenu: Full File, Edit, View, Tools, and Help navigation with hotkeys (Ctrl+O, Ctrl+S, F5, Ctrl+Q) and native macOS screen top MenuBar integration.
• Velopack Auto-Updater & Fallback: Cross-platform auto-updates via Velopack with direct GitHub API release checking fallback for portable builds (Linux AppImages / macOS DMGs).
• AI Agent Native: Built-in Model Context Protocol (MCP) server (InkTag.Mcp) over stdio and structured CLI (InkTag.Cli) with --json output mode and --dry-run safety checks.
• Multimodal Cover Extraction: Extracts front cover art for visual LLMs (Gemini, Claude, GPT-4o) to visually inspect titles, creators, and issue numbers.
• Dynamic JSON Patching: Mutate metadata via JSON strings without compiling C# lambdas.
• Safe Replacement Strategy: Minimizes risk of data loss by repacking to a temporary archive, validating readability, making backups, and swapping target paths on success.
• Open Source Attributions: Full license attributions for third-party tools (THIRD_PARTY_LICENSES.md).

---

📁 Repository Structure

InkTag/
├── src/
│   ├── InkTag.Core/          # Domain models, ComicInfo.xml parsing, metadata engines
│   │   ├── Schema/
│   │   │   └── ComicInfo.xsd # XML schema definition for validation
│   │   ├── ComicInfo.cs      # Deserialization model
│   │   └── MetadataEditor.cs # Core bulk-editing & repackaging logic
│   │
│   ├── InkTag.Cli/           # Command-line interface
│   │   └── Program.cs        # Subcommands (read, update, scan, cover, schema)
│   │
│   ├── InkTag.Mcp/           # Model Context Protocol (MCP) Server
│   │   └── Program.cs        # Stdio JSON-RPC tools for Claude, Cursor, Antigravity
│   │
│   └── InkTag.Gui/           # Avalonia UI desktop application
│       └── ...               # MVVM Avalonia UI
│
├── tests/
│   └── InkTag.Tests/         # Automated xUnit test suite
│
├── .agents/skills/           # Agent Skill package definitions
│   └── comic-metadata-curator/
│
└── docs/                     # Project wiki and design specifications

---

🛠️ Getting Started

macOS App Installation Note

Because pre-built .dmg releases are open-source and unnotarized by Apple:

1. Drag InkTag.app into /Applications.
2. Clear the browser quarantine attribute via Terminal:

   xattr -cr /Applications/InkTag.app
   

(Or go to System Settings > Privacy & Security and click Open Anyway).

Prerequisites

• .NET SDK 8.0 / 9.0 / 10.0

Building the Project

From the repository root, compile the entire solution:

dotnet build InkTag.slnx

---

🤖 AI Agent Integration

1. Model Context Protocol (MCP) Server

Run the MCP server to expose comic metadata tools directly to AI assistants (Claude Desktop, Cursor, Antigravity, VS Code):

dotnet run --project src/InkTag.Mcp/InkTag.Mcp.csproj

Exposed MCP Tools:

• read_comic_metadata: Read XML metadata from archive as JSON.
• update_comic_metadata: Apply JSON property edits (with optional dryRun).
• extract_cover_image: Extract cover image (optionally returns base64 for vision LLMs).
• scan_comics: Scan directory for files missing specific metadata fields.
• get_comic_schema: Get JSON Schema for ComicInfo.