Alt Text Generator MCP

An Apify Actor that generates AI-powered alt text descriptions for images using Qwen2.5-VL vision model via MCP (Model Context Protocol).

Overview

This actor provides two tools for generating accessible alt text:

1. generate_alt_text — Generates concise, screen-reader-friendly alt text (max 125 characters)
2. generate_detailed_description — Generates detailed descriptions for visually impaired users (2-3 sentences)

Features

• AI-Powered: Uses Qwen2.5-VL via ai.ntriq.co.kr for high-quality image analysis
• MCP Integration: Full Model Context Protocol support for Claude and compatible clients
• Accessibility Focus: Optimized for WCAG and ADA compliance guidelines
• Pay-Per-Event: Transparent pricing model with event-based charging
• Multi-Language Support: Generates alt text in any supported language

Tools

generate_alt_text

Generates concise alt text suitable for screen readers.

Input:

• image_url (string, required) — URL of the image to analyze
• language (string, optional) — Language code (default: "en")
• context (string, optional) — Page or document context for improved descriptions

Output:

{
  "status": "success",
  "alt_text": "A descriptive alt text...",
  "disclaimer": "AI-generated. Not guaranteed WCAG/ADA compliant. Human review required.",
  "model": "Qwen2.5-VL",
  "processing_time_ms": 1200,
  "charged": true,
  "cost_usd": 0.05
}

Pricing: $0.05 per request

generate_detailed_description

Generates detailed descriptions for comprehensive accessibility.

Input:

• image_url (string, required) — URL of the image to analyze
• language (string, optional) — Language code (default: "en")

Output:

{
  "status": "success",
  "description": "Detailed description covering main subject, colors, text, spatial relationships...",
  "disclaimer": "AI-generated. Not guaranteed WCAG/ADA compliant. Human review required.",
  "model": "Qwen2.5-VL",
  "processing_time_ms": 1800,
  "charged": true,
  "cost_usd": 0.08
}

Pricing: $0.08 per request

DISCLAIMER

IMPORTANT: The alt text and descriptions generated by this AI tool are machine-generated and may not fully comply with WCAG 2.1 or ADA accessibility standards. Before publishing any web content:

• Human Review Required: Always review generated alt text and descriptions for accuracy and completeness
• No Liability: This tool provides suggestions only and does not guarantee regulatory compliance
• Best Practices: Combine AI generation with manual editing to ensure quality accessibility
• Screen Reader Testing: Test descriptions with actual screen readers (NVDA, JAWS, VoiceOver)

Users and publishers are solely responsible for ensuring their alt text meets applicable accessibility regulations.

Installation

$npm install

Usage

Local Testing

$npm start

Server runs on http://localhost:3000 with MCP endpoint at /mcp.

Health Check

$curl http://localhost:3000/health

Response:

{
  "status": "ok",
  "actor": "alt-text-generator-mcp",
  "version": "1.0.0"
}

Test MCP Request

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "generate_alt_text",
      "arguments": {
        "image_url": "https://example.com/image.jpg",
        "language": "en"
      }
    }
  }'

Apify Deployment

Build

$apify build

Push to Apify

$apify push --with-api

Run on Apify Platform

Configure input parameters and run via Apify Console or API.

Architecture

• Express Server: HTTP endpoint for MCP protocol
• MCP Server: Model Context Protocol implementation with tool registration
• Agnost Tracking: Event tracking for pay-per-event billing
• Apify Actor: Native Apify runtime integration with charging support

Configuration

Environment Variable	Default	Description
APIFY_CONTAINER_PORT	3000	HTTP server port
AI_API_ENDPOINT	https://ai.ntriq.co.kr/analyze/image	AI service endpoint
AI_REQUEST_TIMEOUT	30000	Request timeout (ms)

Pay-Per-Event Pricing

Event	Price
generate_alt_text	$0.05
generate_detailed_description	$0.08

Error Handling

All responses include status field:

• status: "success" — Tool executed successfully
• status: "error" — Tool encountered an error

Error responses include:

• error — Error message
• code — Error code (e.g., "INVALID_URL", "API_ERROR", "TIMEOUT")

Logging

Structured JSON logs to stdout with:

• Timestamp
• Log level (info, error, warn)
• Tool name and parameters (redacted URLs)
• Processing time
• Charging status

Performance

• Average processing time: 1-2 seconds per image
• Concurrent request limit: Depends on Apify infrastructure
• Timeout: 30 seconds per request

License

Apache-2.0