# Omdb Mcp Server

> Model Context Protocol (MCP) Server for the Open Movie Database (OMDB) API.

- **Type:** MCP server
- **Install:** `agentstack add mcp-tyrell-omdb-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [tyrell](https://agentstack.voostack.com/s/tyrell)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [tyrell](https://github.com/tyrell)
- **Source:** https://github.com/tyrell/omdb-mcp-server
- **Website:** https://tyrell.co

## Install

```sh
agentstack add mcp-tyrell-omdb-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# OMDB MCP Server

[](https://github.com/tyrell/omdb-mcp-server/actions/workflows/ci.yml)
[](https://github.com/tyrell/omdb-mcp-server/actions/workflows/build.yml)
[](https://github.com/tyrell/omdb-mcp-server/actions/workflows/docker.yml)
[](https://github.com/tyrell/omdb-mcp-server/actions/workflows/release.yml)
[](https://opensource.org/licenses/MIT)
[](https://openjdk.org/projects/jdk/24/)
[](https://spring.io/projects/spring-boot)
[](https://docs.spring.io/spring-ai/reference/)
[](https://github.com/tyrell/omdb-mcp-server/pkgs/container/omdb-mcp-server)
[](https://spec.modelcontextprotocol.io/specification/)

A Model Context Protocol (MCP) Server powered by **Spring AI** that provides access to the Open Movie Database (OMDB) API. This server uses Spring AI's native MCP Server support to allow AI assistants and other MCP clients to search for movies and retrieve detailed movie information.

## Table of Contents

- [OMDB MCP Server](#omdb-mcp-server)
  - [Table of Contents](#table-of-contents)
  - [Features](#features)
    - [🎬 Movie Database Access](#-movie-database-access)
    - [⚡ Intelligent Caching System](#-intelligent-caching-system)
    - [🔌 MCP Protocol Compliance](#-mcp-protocol-compliance)
    - [🚀 Production Ready](#-production-ready)
    - [🔧 Developer Experience](#-developer-experience)
  - [🏗️ Architecture \& Technology Stack](#️-architecture--technology-stack)
    - [Technology Stack](#technology-stack)
    - [Architecture Overview](#architecture-overview)
    - [Key Components](#key-components)
    - [Security Features](#security-features)
  - [Prerequisites](#prerequisites)
  - [Quick Start](#quick-start)
    - [🐳 Using Docker (Recommended)](#-using-docker-recommended)
    - [📦 Using Pre-built JAR](#-using-pre-built-jar)
    - [🔨 Building from Source](#-building-from-source)
  - [🔧 Configuration](#-configuration)
    - [Environment Variables](#environment-variables)
    - [Cache Configuration](#cache-configuration)
    - [Docker Compose](#docker-compose)
    - [Spring AI MCP Server Configuration](#spring-ai-mcp-server-configuration)
  - [MCP Tools](#mcp-tools)
    - [1. search\_movies](#1-search_movies)
    - [2. get\_movie\_details](#2-get_movie_details)
    - [3. get\_movie\_by\_imdb\_id](#3-get_movie_by_imdb_id)
  - [MCP Protocol Implementation](#mcp-protocol-implementation)
    - [Supported Methods](#supported-methods)
    - [Initialize](#initialize)
    - [Ping](#ping)
    - [List Tools](#list-tools)
  - [Configuration](#configuration)
    - [Core Configuration](#core-configuration)
    - [Advanced Configuration](#advanced-configuration)
  - [🧪 Testing \& Validation](#-testing--validation)
    - [Health Check](#health-check)
    - [Cache Performance Testing](#cache-performance-testing)
    - [MCP Protocol Testing](#mcp-protocol-testing)
    - [� Comprehensive Testing Guide](MCP_TESTING_GUIDE.md)
    - [�🔍 Development \& Debugging](#-development--debugging)
  - [🚀 CI/CD \& Deployment](#-cicd--deployment)
    - [Deployment Options](#deployment-options)
  - [📖 OpenAPI Documentation](#-openapi-documentation)
    - [Access Documentation](#access-documentation)
    - [API Endpoints](#api-endpoints)
      - [MCP Protocol Endpoints](#mcp-protocol-endpoints)
      - [Cache Management Endpoints](#cache-management-endpoints)
    - [OpenAPI Specification](#openapi-specification)
    - [Example Usage](#example-usage)
      - [Initialize MCP Connection](#initialize-mcp-connection)
      - [Get Available Tools](#get-available-tools)
      - [Search for Movies](#search-for-movies)
  - [API Response Format](#api-response-format)
  - [Error Handling](#error-handling)
  - [🤝 Contributing](#-contributing)
    - [Development Setup](#development-setup)
    - [Code Style](#code-style)
  - [📄 License](#-license)
  - [🙏 Acknowledgments](#-acknowledgments)
  - [📞 Support](#-support)

## Features

### 🎬 Movie Database Access
- **Search Movies**: Search for movies by title, year, and type
- **Get Movie Details**: Retrieve detailed information about a specific movie by title
- **Get Movie by IMDB ID**: Get detailed information using IMDB ID
- **Rich Metadata**: Access to ratings, cast, plot, awards, and more

### ⚡ Intelligent Caching System
- **Automatic Caching**: All OMDB API responses are automatically cached to reduce API calls
- **Configurable TTL**: Cache entries expire after 1 hour by default (configurable)
- **Memory Efficient**: Maximum cache size of 1000 entries with LRU eviction policy
- **Performance Monitoring**: Built-in cache statistics and management endpoints
- **Rate Limit Protection**: Helps stay within OMDB API usage limits and reduces costs

### 🔌 MCP Protocol Compliance
- **MCP 2024-11-05**: Fully implements the latest MCP specification
- **HTTP JSON-RPC**: Direct HTTP transport optimized for web service integration
- **JSON-RPC 2.0**: Standard protocol with proper error codes (-32700, -32600, -32601, -32602, -32603)
- **Tool Discovery**: Dynamic tool listing with JSON Schema validation
- **Enhanced Schemas**: Rich metadata, validation rules, and examples for better AI understanding
- **Protocol Methods**: Full support for initialize, ping, tools/list, tools/call, and notifications

### 🚀 Production Ready
- **Docker Support**: Multi-platform container images (AMD64/ARM64)
- **Health Checks**: Built-in monitoring and health endpoints
- **Configuration**: Environment-based configuration
- **Logging**: Structured logging with configurable levels
- **Testing**: Comprehensive test suite with coverage reporting

### 🔧 Developer Experience
- **GitHub Actions**: Complete CI/CD pipeline
- **Automated Releases**: Tagged releases with artifacts
- **Security Scanning**: Vulnerability detection and reporting
- **OpenAPI Documentation**: Interactive API documentation with Swagger UI
- **Code Quality**: Automated dependency updates and code analysis

## 🏗️ Architecture & Technology Stack

### Technology Stack
- **☕ Java 24**: Latest Java with modern features and performance improvements  
- **🍃 Spring Boot 3.5.4**: Production-ready application framework
- **🤖 Spring AI 1.0.0**: Native MCP Server support with autoconfiguration
- **⚡ Spring WebFlux**: Reactive programming with SSE transport for MCP communication
- **🗄️ Spring Cache + Caffeine**: High-performance in-memory caching with automatic management
- **🐳 Docker**: Containerized deployment with multi-stage builds
- **🧪 JUnit 5**: Comprehensive testing framework with Spring Boot Test integration
- **📊 JaCoCo**: Code coverage analysis
- **🔒 Spring Security**: Security scanning and best practices

### Architecture Overview
```
                    ┌─────────────────┐
                    │   MCP Client    │
                    │ (Claude Desktop)│
                    └─────────────────┘
                           │
                    ┌──────┴──────┐
                    │             │
           ┌────────▼─────┐ ┌─────▼──────────┐
           │ SSE          │ │ HTTP REST      │
           │ Transport    │ │ Controller     │
           │ (/sse)       │ │ (Port 8081)    │
           └────────┬─────┘ └─────┬──────────┘
                    │             │
                    └──────┬──────┘
                           ▼
                   ┌─────────────────┐
                   │ Spring AI MCP   │
                   │ Autoconfigured  │
                   │ Function Beans  │
                   └─────────────────┘
                           │
                           ▼
                   ┌─────────────────┐
                   │MovieSearchTools │◀─--┐
                   │ (Function Impl) │    │
                   └─────────────────┘    │
                           │              │
                           ▼              │
                   ┌─────────────────┐    │
                   │  OMDB Service   │    │
                   │ (External API)  │    │
                   └─────────────────┘    │
                           │              │
                           ▼              │
┌─────────────────┐ ┌─────────────────┐   │
│ Cache Manager   │ │  Caffeine Cache │   │
│   (Statistics)  │ │  (In-Memory)    │   │
└─────────────────┘ └─────────────────┘   │
        │                     ▲           │
        │                     │           │
        ▼                Cache Miss       │
┌─────────────────┐           │           │
│ Cache Endpoints │           │           │
│ /cache/stats    │           ▼           │
│ /cache/clear    │   ┌─────────────────┐ │
└─────────────────┘   │   OMDB API      │ │
                      │ (omdbapi.com)   │ │
                      └─────────────────┘ │
                           │              │
                           └────────────--┘
                         Cache Hit
```

### Key Components
- **🤖 Spring AI MCP**: Autoconfigured MCP server with WebFlux SSE transport
- **�️ MovieSearchTools**: Service providing OMDB movie search functionality as Spring AI Function beans
- **⚙️ McpServerConfig**: Configuration class registering Function beans for MCP tool discovery
- **🌐 OmdbService**: OMDB API integration with reactive WebClient and intelligent caching
- **⚡ Cache Layer**: Caffeine-based in-memory caching with configurable TTL and LRU eviction
- **📊 Cache Management**: REST endpoints for cache statistics and management (/cache/*)
- **� SSE Transport**: Server-Sent Events endpoint (/sse) for real-time MCP communication
- **📋 Model Classes**: Request/response records for strongly-typed Function interfaces
- **⚙️ Configuration**: Spring AI MCP autoconfiguration via application.properties

### Security Features
- 🔐 Non-root Docker user
- 🛡️ Automated vulnerability scanning
- 🚫 No sensitive data in images
- ✅ Health checks and monitoring
- 🔒 HTTPS support for external APIs

## Prerequisites

- Java 24 or higher
- Maven 3.6 or higher
- OMDB API Key (free registration at http://www.omdbapi.com/apikey.aspx)

## Quick Start

### 🐳 Using Docker (Recommended)

```bash
# Pull and run the latest Docker image
docker run -p 8081:8081 -e OMDB_API_KEY=your-api-key ghcr.io/tyrell/omdb-mcp-server:latest
```

### 📦 Using Pre-built JAR

1. Download the latest JAR from [Releases](https://github.com/tyrell/omdb-mcp-server/releases)
2. Run with your OMDB API key:
   ```bash
   java -jar omdb-mcp-server-*.jar --omdb.api.key=your-api-key
   ```

### 🔨 Building from Source

1. **Clone and build the project**:
   ```bash
   git clone https://github.com/tyrell/omdb-mcp-server
   cd omdb-mcp-server
   ./mvnw clean package
   ```

2. **Set your OMDB API key**:
   ```bash
   export OMDB_API_KEY=your-actual-api-key-here
   ```

3. **Run the server**:
   ```bash
   ./mvnw spring-boot:run
   ```

The server will start on `http://localhost:8081`

**📖 View API Documentation**: Once running, access the interactive API documentation at http://localhost:8081/swagger-ui/index.html

## 🔧 Configuration

### Environment Variables
- `OMDB_API_KEY`: Your OMDB API key (required)
- `SERVER_PORT`: Server port (default: 8081)
- `SPRING_AI_MCP_SERVER_NAME`: MCP server name (default: "OMDB Movie Database Server")
- `SPRING_AI_MCP_SERVER_VERSION`: MCP server version (default: "0.2.0-SNAPSHOT")

### Cache Configuration
The server includes intelligent caching to reduce OMDB API calls:

```properties
# Cache Configuration (default values shown)
cache.expire-after-write=1h        # Cache TTL (Time To Live)
cache.maximum-size=1000           # Maximum number of cached entries
cache.record-stats=true           # Enable cache statistics
```

Cache management endpoints:
- `GET /cache/stats` - View cache performance statistics
- `DELETE /cache/clear` - Clear all caches
- `DELETE /cache/clear/{cacheName}` - Clear specific cache

### Docker Compose
```yaml
version: '3.8'
services:
  omdb-mcp-server:
    image: ghcr.io/tyrell/omdb-mcp-server:latest
    ports:
      - "8081:8081"
    environment:
      - OMDB_API_KEY=your-api-key-here
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8081/actuator/health"]
      interval: 30s
      timeout: 3s
      retries: 3
```

### Spring AI MCP Server Configuration

For AI clients like Claude Desktop, use the Server-Sent Events (SSE) transport:

**SSE Endpoint**: `http://localhost:8081/sse`

**Claude Desktop Configuration** (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "omdb": {
      "command": "java",
      "args": ["-jar", "/path/to/omdb-mcp-server.jar"],
      "env": {
        "OMDB_API_KEY": "your-actual-api-key-here"
      }
    }
  }
}
```

**Alternative: Direct SSE Connection**:
If using a custom MCP client that supports SSE:
```javascript
const eventSource = new EventSource('http://localhost:8081/sse');
eventSource.onmessage = function(event) {
  // Handle MCP messages
  const mcpMessage = JSON.parse(event.data);
};
```

**Transport Mode**:
- **HTTP JSON-RPC**: MCP protocol over HTTP at `/mcp` endpoint on port 8081

## MCP Tools

### 1. search_movies
Search for movies by title in the OMDB database.

**Parameters**:
- `title` (required): Movie title to search for
- `year` (optional): Year of release
- `type` (optional): Type of result (movie, series, or episode)

**Example**:
```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "search_movies",
    "arguments": {
      "title": "The Matrix",
      "year": "1999"
    }
  }
}
```

### 2. get_movie_details
Get detailed information about a specific movie by title.

**Parameters**:
- `title` (required): Movie title
- `year` (optional): Year of release
- `plot` (optional): Plot length ("short" or "full", default: "full")

**Example**:
```json
{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "tools/call",
  "params": {
    "name": "get_movie_details",
    "arguments": {
      "title": "The Shawshank Redemption",
      "plot": "full"
    }
  }
}
```

### 3. get_movie_by_imdb_id
Get detailed information about a movie by IMDB ID.

**Parameters**:
- `imdbId` (required): IMDB ID (e.g., "tt0111161")
- `plot` (optional): Plot length ("short" or "full", default: "full")

**Example**:
```json
{
  "jsonrpc": "2.0",
  "id": "3",
  "method": "tools/call",
  "params": {
    "name": "get_movie_by_imdb_id",
    "arguments": {
      "imdbId": "tt0111161"
    }
  }
}
```

## MCP Protocol Implementation

This server implements the MCP 2024-11-05 specification using **Spring AI's native MCP Server support** with the following capabilities:

### Supported Methods
- **initialize**: Server initialization and capability negotiation (handled by Spring AI)
- **ping**: Connection testing and keep-alive (handled by Spring AI)
- **tools/list**: Dynamic tool discovery via Function bean registration
- **tools/call**: Tool execution through Spring AI Function interface
- **notifications/initialized**: Client initialization completion (handled by Spring AI)

### Spring AI Function Registration
Tools are automatically registered as Function beans and discovered by Spring AI:

```java
@Configuration
public class McpServerConfig {
    
    @Bean
    public Function searchMovies(MovieSearchTools movieSearchTools) {
        return movieSearchTools::searchMovies;
    }
    
    @Bean
    public Function getMovieDetails(MovieSearchTools movieSearchTools) {
        return movieSearchTools::getMovieDetails;
    }
    
    @Bean
    public Function getMovieByImdbId(MovieSearchTools movieSearchTools) {
        return movieSearchTools::getMovieByImdbId;
    }
}
```

### SSE Transport
Spring AI MCP Server uses Server-Sent Events for real-time communication:
- **Endpoint**: `GET /sse`
- **Content-Type**: `text/event-stream`
- **Connection**: Persistent bidirectional communication

### List Tools
```json
{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "tools/list"
}
```

## Configuration

The server can be configured using environment variables or `application.properties`:

### Core Configuration
```properties
# Server Configuration
server.port=8081

# OMDB API Configuration
omdb.

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [tyrell](https://github.com/tyrell)
- **Source:** [tyrell/omdb-mcp-server](https://github.com/tyrell/omdb-mcp-server)
- **License:** MIT
- **Homepage:** https://tyrell.co

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-tyrell-omdb-mcp-server
- Seller: https://agentstack.voostack.com/s/tyrell
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.