trevormunoz/iiif-mcp

IIIF MCP Server

A Model Context Protocol (MCP) server that provides access to IIIF (International Image Interoperability Framework) documentation. This server enables AI assistants to retrieve, cache, and search through IIIF API specifications including Image API, Presentation API, Search API, and Authentication API documentation.

Features

• 📚 Documentation Retrieval: Fetch and cache IIIF API documentation from iiif.io
• 🔍 Smart Search: Search across cached documentation with keyword matching
• 💾 Intelligent Caching: SQLite-based caching with configurable TTL (24 hours default)
• ✅ Content Validation: Validates retrieved content contains IIIF-specific patterns
• 📊 Health Monitoring: Basic health checks for operational status

Installation

# Clone the repository
git clone <repository-url>
cd iiif-mcp

# Install dependencies
npm install

# Build the project
npm run build

Usage

Starting the Server

# Development mode
npm run dev

# Production mode
npm start

Available Tools

1. get_api_docs - Retrieve IIIF Documentation

Fetch documentation for specific IIIF APIs.

{
  "name": "get_api_docs",
  "arguments": {
    "api": "image",
    "version": "3.0",
    "section": "parameters",
    "forceRefresh": false
  }
}

Parameters:

• api (required): API type (image, presentation, search, auth)
• version (optional): API version (default: 3.0)
• section (optional): Filter to specific section by title
• forceRefresh (optional): Force refresh from source (default: false)

2. search_docs - Search Documentation

Search through cached IIIF documentation.

{
  "name": "search_docs", 
  "arguments": {
    "query": "image parameters",
    "apis": ["image", "presentation"],
    "maxResults": 5
  }
}

Parameters:

• query (required): Search terms to look for
• apis (optional): Specific APIs to search (default: all common APIs)
• maxResults (optional): Maximum results to return (default: 10)

3. health_check - Server Health Status

Check server operational status and database connectivity.

{
  "name": "health_check",
  "arguments": {}
}

4. ping - Test Connectivity

Test server connectivity and responsiveness.

{
  "name": "ping",
  "arguments": {
    "includeTimestamp": true
  }
}

Configuration

Configure the server using environment variables:

# Cache directory (default: ./cache)
export IIIF_CACHE_DIR=/path/to/cache

# HTTP request timeout in milliseconds (default: 5000)
export IIIF_HTTP_TIMEOUT=10000

# Log level (default: info)
export IIIF_LOG_LEVEL=debug

Architecture

Core Components

• MCP Server: Handles tool requests and responses
• HTTP Client: Fetches content from iiif.io with retry logic
• Content Cache: SQLite-based caching with TTL management
• Parser: Extracts and structures content from HTML documentation
• Validator: Ensures retrieved content is valid IIIF documentation
• Monitor: Health checks for operational status

File Structure

src/
├── server.ts              # MCP server setup and tool routing
├── config.ts              # Configuration management
├── http.ts                 # HTTP client with retry logic
├── cache.ts                # SQLite content caching
├── parser.ts               # HTML parsing and text extraction
├── validation.ts           # Content validation and error handling
├── monitoring.ts           # Health monitoring
└── tools/
    ├── ping.ts            # Ping tool implementation
    ├── get-docs.ts        # Documentation retrieval tool
    └── search.ts          # Search functionality

Development

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run specific test file
npm test -- config.test.ts

Type Checking

# Check TypeScript types
npm run typecheck

Linting

# Run ESLint
npm run lint

API Coverage

The server provides access to documentation for these IIIF APIs:

• Image API 3.0: Web service for image delivery
• Presentation API 3.0: Structured metadata format
• Search API 1.0: Content search within resources
• Authentication API 1.0: Access control patterns

License

This project is licensed under the MIT License - see the file for details.

Related Projects

• IIIF: International Image Interoperability Framework
• Model Context Protocol: Standard for AI assistant integrations
• Claude Code: AI coding assistant that supports MCP