@ngxtm/devkit 3.7.0 → 3.8.0

package/merged-commands/mcp-developer.md

@@ -0,0 +1,94 @@
+---
+name: mcp-developer
+description: Use when building MCP servers or clients that connect AI systems with external tools and data sources. Invoke for MCP protocol compliance, TypeScript/Python SDKs, resource providers, tool functions.
+triggers:
+  - MCP
+  - Model Context Protocol
+  - MCP server
+  - MCP client
+  - Claude integration
+  - AI tools
+  - context protocol
+  - JSON-RPC
+role: specialist
+scope: implementation
+output-format: code
+---
+
+# MCP Developer
+
+Senior MCP (Model Context Protocol) developer with deep expertise in building servers and clients that connect AI systems with external tools and data sources.
+
+## Role Definition
+
+You are a senior MCP developer with expertise in protocol implementation, SDK usage (TypeScript/Python), and production deployment. You build robust MCP servers that expose resources, tools, and prompts to Claude and other AI systems while maintaining security, performance, and developer experience standards.
+
+## When to Use This Skill
+
+- Building MCP servers for data source integration
+- Implementing tool functions for AI assistants
+- Creating resource providers with URI schemes
+- Setting up MCP clients for Claude integration
+- Debugging protocol compliance issues
+- Optimizing MCP performance and security
+
+## Core Workflow
+
+1. **Analyze requirements** - Identify data sources, tools needed, client apps
+2. **Design protocol** - Define resources, tools, prompts, schemas
+3. **Implement** - Build server/client with SDK, add security controls
+4. **Test** - Verify protocol compliance, performance, error handling
+5. **Deploy** - Package, configure, monitor in production
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Protocol | `references/protocol.md` | Message types, lifecycle, JSON-RPC 2.0 |
+| TypeScript SDK | `references/typescript-sdk.md` | Building servers/clients in Node.js |
+| Python SDK | `references/python-sdk.md` | Building servers/clients in Python |
+| Tools | `references/tools.md` | Tool definitions, schemas, execution |
+| Resources | `references/resources.md` | Resource providers, URIs, templates |
+
+## Constraints
+
+### MUST DO
+- Implement JSON-RPC 2.0 protocol correctly
+- Validate all inputs with schemas (Zod/Pydantic)
+- Use proper transport mechanisms (stdio/HTTP/SSE)
+- Implement comprehensive error handling
+- Add authentication and authorization
+- Log protocol messages for debugging
+- Test protocol compliance thoroughly
+- Document server capabilities
+
+### MUST NOT DO
+- Skip input validation on tool inputs
+- Expose sensitive data in resource content
+- Ignore protocol version compatibility
+- Mix synchronous code with async transports
+- Hardcode credentials or secrets
+- Return unstructured errors to clients
+- Deploy without rate limiting
+- Skip security controls
+
+## Output Templates
+
+When implementing MCP features, provide:
+1. Server/client implementation file
+2. Schema definitions (tools, resources, prompts)
+3. Configuration file (transport, auth, etc.)
+4. Brief explanation of design decisions
+
+## Knowledge Reference
+
+Model Context Protocol (MCP), JSON-RPC 2.0, TypeScript SDK (@modelcontextprotocol/sdk), Python SDK (mcp), Zod schemas, Pydantic validation, stdio transport, SSE transport, resource URIs, tool functions, prompt templates, authentication, rate limiting
+
+## Related Skills
+
+- **FastAPI Expert** - Python API servers for HTTP transport
+- **TypeScript Pro** - Advanced TypeScript for Node.js servers
+- **Security Reviewer** - Security audits for MCP implementations
+- **DevOps Engineer** - Deployment and monitoring

package/merged-commands/mcp-management.md

@@ -0,0 +1,209 @@
+---
+name: mcp-management
+description: Manage MCP servers - discover, analyze, execute tools/prompts/resources. Use for MCP integrations, intelligent tool selection, multi-server management, context-efficient capability discovery.
+---
+
+# MCP Management
+
+Skill for managing and interacting with Model Context Protocol (MCP) servers.
+
+## Overview
+
+MCP is an open protocol enabling AI agents to connect to external tools and data sources. This skill provides scripts and utilities to discover, analyze, and execute MCP capabilities from configured servers without polluting the main context window.
+
+**Key Benefits**:
+- Progressive disclosure of MCP capabilities (load only what's needed)
+- Intelligent tool/prompt/resource selection based on task requirements
+- Multi-server management from single config file
+- Context-efficient: subagents handle MCP discovery and execution
+- Persistent tool catalog: automatically saves discovered tools to JSON for fast reference
+
+## When to Use This Skill
+
+Use this skill when:
+1. **Discovering MCP Capabilities**: Need to list available tools/prompts/resources from configured servers
+2. **Task-Based Tool Selection**: Analyzing which MCP tools are relevant for a specific task
+3. **Executing MCP Tools**: Calling MCP tools programmatically with proper parameter handling
+4. **MCP Integration**: Building or debugging MCP client implementations
+5. **Context Management**: Avoiding context pollution by delegating MCP operations to subagents
+
+## Core Capabilities
+
+### 1. Configuration Management
+
+MCP servers configured in `.claude/.mcp.json`.
+
+**Gemini CLI Integration** (recommended): Create symlink to `.gemini/settings.json`:
+```bash
+mkdir -p .gemini && ln -sf .claude/.mcp.json .gemini/settings.json
+```
+
+See [references/configuration.md](references/configuration.md) and [references/gemini-cli-integration.md](references/gemini-cli-integration.md).
+
+**GEMINI.md Response Format**: Project root contains `GEMINI.md` that Gemini CLI auto-loads, enforcing structured JSON responses:
+```json
+{"server":"name","tool":"name","success":true,"result":<data>,"error":null}
+```
+
+This ensures parseable, consistent output instead of unpredictable natural language. The file defines:
+- Mandatory JSON-only response format (no markdown, no explanations)
+- Maximum 500 character responses
+- Error handling structure
+- Available MCP servers reference
+
+**Benefits**: Programmatically parseable output, consistent error reporting, DRY configuration (format defined once), context-efficient (auto-loaded by Gemini CLI).
+
+### 2. Capability Discovery
+
+```bash
+npx tsx scripts/cli.ts list-tools  # Saves to assets/tools.json
+npx tsx scripts/cli.ts list-prompts
+npx tsx scripts/cli.ts list-resources
+```
+
+Aggregates capabilities from multiple servers with server identification.
+
+### 3. Intelligent Tool Analysis
+
+LLM analyzes `assets/tools.json` directly - better than keyword matching algorithms.
+
+### 4. Tool Execution
+
+**Primary: Gemini CLI** (if available)
+```bash
+# IMPORTANT: Use stdin piping, NOT -p flag (deprecated, skips MCP init)
+echo "Take a screenshot of https://example.com" | gemini -y -m gemini-2.5-flash
+```
+
+**Secondary: Direct Scripts**
+```bash
+npx tsx scripts/cli.ts call-tool memory create_entities '{"entities":[...]}'
+```
+
+**Fallback: mcp-manager Subagent**
+
+See [references/gemini-cli-integration.md](references/gemini-cli-integration.md) for complete examples.
+
+## Implementation Patterns
+
+### Pattern 1: Gemini CLI Auto-Execution (Primary)
+
+Use Gemini CLI for automatic tool discovery and execution. Gemini CLI auto-loads `GEMINI.md` from project root to enforce structured JSON responses.
+
+**Quick Example**:
+```bash
+# IMPORTANT: Use stdin piping, NOT -p flag (deprecated, skips MCP init)
+# Add "Return JSON only per GEMINI.md instructions" to enforce structured output
+echo "Take a screenshot of https://example.com. Return JSON only per GEMINI.md instructions." | gemini -y -m gemini-2.5-flash
+```
+
+**Expected Output**:
+```json
+{"server":"puppeteer","tool":"screenshot","success":true,"result":"screenshot.png","error":null}
+```
+
+**Benefits**:
+- Automatic tool discovery
+- Structured JSON responses (parseable by Claude)
+- GEMINI.md auto-loaded for consistent formatting
+- Faster than subagent orchestration
+- No natural language ambiguity
+
+See [references/gemini-cli-integration.md](references/gemini-cli-integration.md) for complete guide.
+
+### Pattern 2: Subagent-Based Execution (Fallback)
+
+Use `mcp-manager` agent when Gemini CLI unavailable. Subagent discovers tools, selects relevant ones, executes tasks, reports back.
+
+**Benefit**: Main context stays clean, only relevant tool definitions loaded when needed.
+
+### Pattern 3: LLM-Driven Tool Selection
+
+LLM reads `assets/tools.json`, intelligently selects relevant tools using context understanding, synonyms, and intent recognition.
+
+### Pattern 4: Multi-Server Orchestration
+
+Coordinate tools across multiple servers. Each tool knows its source server for proper routing.
+
+## Scripts Reference
+
+### scripts/mcp-client.ts
+
+Core MCP client manager class. Handles:
+- Config loading from `.claude/.mcp.json`
+- Connecting to multiple MCP servers
+- Listing tools/prompts/resources across all servers
+- Executing tools with proper error handling
+- Connection lifecycle management
+
+### scripts/cli.ts
+
+Command-line interface for MCP operations. Commands:
+- `list-tools` - Display all tools and save to `assets/tools.json`
+- `list-prompts` - Display all prompts
+- `list-resources` - Display all resources
+- `call-tool <server> <tool> <json>` - Execute a tool
+
+**Note**: `list-tools` persists complete tool catalog to `assets/tools.json` with full schemas for fast reference, offline browsing, and version control.
+
+## Quick Start
+
+**Method 1: Gemini CLI** (recommended)
+```bash
+npm install -g gemini-cli
+mkdir -p .gemini && ln -sf .claude/.mcp.json .gemini/settings.json
+# IMPORTANT: Use stdin piping, NOT -p flag (deprecated, skips MCP init)
+# GEMINI.md auto-loads to enforce JSON responses
+echo "Take a screenshot of https://example.com. Return JSON only per GEMINI.md instructions." | gemini -y -m gemini-2.5-flash
+```
+
+Returns structured JSON: `{"server":"puppeteer","tool":"screenshot","success":true,"result":"screenshot.png","error":null}`
+
+**Method 2: Scripts**
+```bash
+cd .claude/skills/mcp-management/scripts && npm install
+npx tsx cli.ts list-tools  # Saves to assets/tools.json
+npx tsx cli.ts call-tool memory create_entities '{"entities":[...]}'
+```
+
+**Method 3: mcp-manager Subagent**
+
+See [references/gemini-cli-integration.md](references/gemini-cli-integration.md) for complete guide.
+
+## Technical Details
+
+See [references/mcp-protocol.md](references/mcp-protocol.md) for:
+- JSON-RPC protocol details
+- Message types and formats
+- Error codes and handling
+- Transport mechanisms (stdio, HTTP+SSE)
+- Best practices
+
+## Integration Strategy
+
+### Execution Priority
+
+1. **Gemini CLI** (Primary): Fast, automatic, intelligent tool selection
+   - Check: `command -v gemini`
+   - Execute: `echo "<task>" | gemini -y -m gemini-2.5-flash`
+   - **IMPORTANT**: Use stdin piping, NOT `-p` flag (deprecated, skips MCP init)
+   - Best for: All tasks when available
+
+2. **Direct CLI Scripts** (Secondary): Manual tool specification
+   - Use when: Need specific tool/server control
+   - Execute: `npx tsx scripts/cli.ts call-tool <server> <tool> <args>`
+
+3. **mcp-manager Subagent** (Fallback): Context-efficient delegation
+   - Use when: Gemini unavailable or failed
+   - Keeps main context clean
+
+### Integration with Agents
+
+The `mcp-manager` agent uses this skill to:
+- Check Gemini CLI availability first
+- Execute via `gemini` command if available
+- Fallback to direct script execution
+- Discover MCP capabilities without loading into main context
+- Report results back to main agent
+
+This keeps main agent context clean and enables efficient MCP integration.

package/merged-commands/media-processing.md

@@ -0,0 +1,358 @@
+---
+name: media-processing
+description: Process multimedia files with FFmpeg (video/audio encoding, conversion, streaming, filtering, hardware acceleration) and ImageMagick (image manipulation, format conversion, batch processing, effects, composition). Use when converting media formats, encoding videos with specific codecs (H.264, H.265, VP9), resizing/cropping images, extracting audio from video, applying filters and effects, optimizing file sizes, creating streaming manifests (HLS/DASH), generating thumbnails, batch processing images, creating composite images, or implementing media processing pipelines. Supports 100+ formats, hardware acceleration (NVENC, QSV), and complex filtergraphs.
+license: MIT
+---
+
+# Media Processing Skill
+
+Process video, audio, and images using FFmpeg and ImageMagick command-line tools for conversion, optimization, streaming, and manipulation tasks.
+
+## When to Use This Skill
+
+Use when:
+- Converting media formats (video, audio, images)
+- Encoding video with codecs (H.264, H.265, VP9, AV1)
+- Processing images (resize, crop, effects, watermarks)
+- Extracting audio from video
+- Creating streaming manifests (HLS/DASH)
+- Generating thumbnails and previews
+- Batch processing media files
+- Optimizing file sizes and quality
+- Applying filters and effects
+- Creating composite images or videos
+
+## Tool Selection Guide
+
+### FFmpeg: Video/Audio Processing
+Use FFmpeg for:
+- Video encoding, conversion, transcoding
+- Audio extraction, conversion, mixing
+- Live streaming (RTMP, HLS, DASH)
+- Video filters (scale, crop, rotate, overlay)
+- Hardware-accelerated encoding
+- Media file inspection (ffprobe)
+- Frame extraction, concatenation
+- Codec selection and optimization
+
+### ImageMagick: Image Processing
+Use ImageMagick for:
+- Image format conversion (PNG, JPEG, WebP, GIF)
+- Resizing, cropping, transformations
+- Batch image processing (mogrify)
+- Visual effects (blur, sharpen, sepia)
+- Text overlays and watermarks
+- Image composition and montages
+- Color adjustments, filters
+- Thumbnail generation
+
+### Decision Matrix
+
+| Task | Tool | Why |
+|------|------|-----|
+| Video encoding | FFmpeg | Native video codec support |
+| Audio extraction | FFmpeg | Direct stream manipulation |
+| Image resize | ImageMagick | Optimized for still images |
+| Batch images | ImageMagick | mogrify for in-place edits |
+| Video thumbnails | FFmpeg | Frame extraction built-in |
+| GIF creation | FFmpeg or ImageMagick | FFmpeg for video source, ImageMagick for images |
+| Streaming | FFmpeg | Live streaming protocols |
+| Image effects | ImageMagick | Rich filter library |
+
+## Installation
+
+### macOS
+```bash
+brew install ffmpeg imagemagick
+```
+
+### Ubuntu/Debian
+```bash
+sudo apt-get install ffmpeg imagemagick
+```
+
+### Windows
+```bash
+# Using winget
+winget install ffmpeg
+winget install ImageMagick.ImageMagick
+
+# Or download binaries
+# FFmpeg: https://ffmpeg.org/download.html
+# ImageMagick: https://imagemagick.org/script/download.php
+```
+
+### Verify Installation
+```bash
+ffmpeg -version
+ffprobe -version
+magick -version
+# or
+convert -version
+```
+
+## Quick Start Examples
+
+### Video Conversion
+```bash
+# Convert format (copy streams, fast)
+ffmpeg -i input.mkv -c copy output.mp4
+
+# Re-encode with H.264
+ffmpeg -i input.avi -c:v libx264 -crf 22 -c:a aac output.mp4
+
+# Resize video to 720p
+ffmpeg -i input.mp4 -vf scale=-1:720 -c:a copy output.mp4
+```
+
+### Audio Extraction
+```bash
+# Extract audio (no re-encoding)
+ffmpeg -i video.mp4 -vn -c:a copy audio.m4a
+
+# Convert to MP3
+ffmpeg -i video.mp4 -vn -q:a 0 audio.mp3
+```
+
+### Image Processing
+```bash
+# Convert format
+magick input.png output.jpg
+
+# Resize maintaining aspect ratio
+magick input.jpg -resize 800x600 output.jpg
+
+# Create square thumbnail
+magick input.jpg -resize 200x200^ -gravity center -extent 200x200 thumb.jpg
+```
+
+### Batch Image Resize
+```bash
+# Resize all JPEGs to 800px width
+mogrify -resize 800x -quality 85 *.jpg
+
+# Output to separate directory
+mogrify -path ./output -resize 800x600 *.jpg
+```
+
+### Video Thumbnail
+```bash
+# Extract frame at 5 seconds
+ffmpeg -ss 00:00:05 -i video.mp4 -vframes 1 -vf scale=320:-1 thumb.jpg
+```
+
+### HLS Streaming
+```bash
+# Generate HLS playlist
+ffmpeg -i input.mp4 \
+  -c:v libx264 -preset fast -crf 22 -g 48 \
+  -c:a aac -b:a 128k \
+  -f hls -hls_time 6 -hls_playlist_type vod \
+  playlist.m3u8
+```
+
+### Image Watermark
+```bash
+# Add watermark to corner
+magick input.jpg watermark.png -gravity southeast \
+  -geometry +10+10 -composite output.jpg
+```
+
+## Common Workflows
+
+### Optimize Video for Web
+```bash
+# H.264 with good compression
+ffmpeg -i input.mp4 \
+  -c:v libx264 -preset slow -crf 23 \
+  -c:a aac -b:a 128k \
+  -movflags +faststart \
+  output.mp4
+```
+
+### Create Responsive Images
+```bash
+# Generate multiple sizes
+for size in 320 640 1024 1920; do
+  magick input.jpg -resize ${size}x -quality 85 "output-${size}w.jpg"
+done
+```
+
+### Extract Video Segment
+```bash
+# From 1:30 to 3:00 (re-encode for precision)
+ffmpeg -i input.mp4 -ss 00:01:30 -to 00:03:00 \
+  -c:v libx264 -c:a aac output.mp4
+```
+
+### Batch Image Optimization
+```bash
+# Convert PNG to optimized JPEG
+mogrify -path ./optimized -format jpg -quality 85 -strip *.png
+```
+
+### Video GIF Creation
+```bash
+# High quality GIF with palette
+ffmpeg -i input.mp4 -vf "fps=15,scale=640:-1:flags=lanczos,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse" output.gif
+```
+
+### Image Blur Effect
+```bash
+# Gaussian blur
+magick input.jpg -gaussian-blur 0x8 output.jpg
+```
+
+## Advanced Techniques
+
+### Multi-Pass Video Encoding
+```bash
+# Pass 1 (analysis)
+ffmpeg -y -i input.mkv -c:v libx264 -b:v 2600k -pass 1 -an -f null /dev/null
+
+# Pass 2 (encoding)
+ffmpeg -i input.mkv -c:v libx264 -b:v 2600k -pass 2 -c:a aac output.mp4
+```
+
+### Hardware-Accelerated Encoding
+```bash
+# NVIDIA NVENC
+ffmpeg -hwaccel cuda -i input.mp4 -c:v h264_nvenc -preset fast -crf 22 output.mp4
+
+# Intel QuickSync
+ffmpeg -hwaccel qsv -c:v h264_qsv -i input.mp4 -c:v h264_qsv output.mp4
+```
+
+### Complex Image Pipeline
+```bash
+# Resize, crop, border, adjust
+magick input.jpg \
+  -resize 1000x1000^ \
+  -gravity center \
+  -crop 1000x1000+0+0 +repage \
+  -bordercolor black -border 5x5 \
+  -brightness-contrast 5x10 \
+  -quality 90 \
+  output.jpg
+```
+
+### Video Filter Chains
+```bash
+# Scale, denoise, watermark
+ffmpeg -i video.mp4 -i logo.png \
+  -filter_complex "[0:v]scale=1280:720,hqdn3d[v];[v][1:v]overlay=10:10" \
+  -c:a copy output.mp4
+```
+
+### Animated GIF from Images
+```bash
+# Create with delay
+magick -delay 100 -loop 0 frame*.png animated.gif
+
+# Optimize size
+magick animated.gif -fuzz 5% -layers Optimize optimized.gif
+```
+
+## Media Analysis
+
+### Inspect Video Properties
+```bash
+# Detailed JSON output
+ffprobe -v quiet -print_format json -show_format -show_streams input.mp4
+
+# Get resolution
+ffprobe -v error -select_streams v:0 \
+  -show_entries stream=width,height \
+  -of csv=s=x:p=0 input.mp4
+```
+
+### Image Information
+```bash
+# Basic info
+identify image.jpg
+
+# Detailed format
+identify -verbose image.jpg
+
+# Custom format
+identify -format "%f: %wx%h %b\n" image.jpg
+```
+
+## Performance Tips
+
+1. **Use CRF for quality control** - Better than bitrate for video
+2. **Copy streams when possible** - Avoid re-encoding with `-c copy`
+3. **Hardware acceleration** - GPU encoding 5-10x faster
+4. **Appropriate presets** - Balance speed vs compression
+5. **Batch with mogrify** - In-place image processing
+6. **Strip metadata** - Reduce file size with `-strip`
+7. **Progressive JPEG** - Better web loading with `-interlace Plane`
+8. **Limit memory** - Prevent crashes on large batches
+9. **Test on samples** - Verify settings before batch
+10. **Parallel processing** - Use GNU Parallel for multiple files
+
+## Reference Documentation
+
+Detailed guides in `references/`:
+
+- **ffmpeg-encoding.md** - Video/audio codecs, quality optimization, hardware acceleration
+- **ffmpeg-streaming.md** - HLS/DASH, live streaming, adaptive bitrate
+- **ffmpeg-filters.md** - Video/audio filters, complex filtergraphs
+- **imagemagick-editing.md** - Format conversion, effects, transformations
+- **imagemagick-batch.md** - Batch processing, mogrify, parallel operations
+- **format-compatibility.md** - Format support, codec recommendations
+
+## Common Parameters
+
+### FFmpeg Video
+- `-c:v` - Video codec (libx264, libx265, libvpx-vp9)
+- `-crf` - Quality (0-51, lower=better, 23=default)
+- `-preset` - Speed/compression (ultrafast to veryslow)
+- `-b:v` - Video bitrate (e.g., 2M, 2500k)
+- `-vf` - Video filters
+
+### FFmpeg Audio
+- `-c:a` - Audio codec (aac, mp3, opus)
+- `-b:a` - Audio bitrate (e.g., 128k, 192k)
+- `-ar` - Sample rate (44100, 48000)
+
+### ImageMagick Geometry
+- `800x600` - Fit within (maintains aspect)
+- `800x600!` - Force exact size
+- `800x600^` - Fill (may crop)
+- `800x` - Width only
+- `x600` - Height only
+- `50%` - Scale percentage
+
+## Troubleshooting
+
+**FFmpeg "Unknown encoder"**
+```bash
+# Check available encoders
+ffmpeg -encoders | grep h264
+
+# Install codec libraries
+sudo apt-get install libx264-dev libx265-dev
+```
+
+**ImageMagick "not authorized"**
+```bash
+# Edit policy file
+sudo nano /etc/ImageMagick-7/policy.xml
+# Change <policy domain="coder" rights="none" pattern="PDF" />
+# to <policy domain="coder" rights="read|write" pattern="PDF" />
+```
+
+**Memory errors**
+```bash
+# Limit memory usage
+ffmpeg -threads 4 input.mp4 output.mp4
+magick -limit memory 2GB -limit map 4GB input.jpg output.jpg
+```
+
+## Resources
+
+- FFmpeg: https://ffmpeg.org/documentation.html
+- FFmpeg Wiki: https://trac.ffmpeg.org/
+- ImageMagick: https://imagemagick.org/
+- ImageMagick Usage: https://imagemagick.org/Usage/