Video Metadata MCP Server

A Model Context Protocol (MCP) server for managing video metadata with game information, teams, scores, and other sports-related data. This server uses PostgreSQL as the database backend.

Features

• CRUD Operations: Create, read, update, and delete video metadata records
• Advanced Search: Filter videos by game type, teams, league, season, tags, and date ranges
• PostgreSQL Integration: Robust database with JSONB support for flexible data storage
• MCP Protocol: Compatible with Claude Desktop and other MCP clients
• Rich Metadata: Support for game statistics, player data, venues, and more

Database Schema

The server manages video metadata with the following fields:

• id: Unique identifier (auto-generated)
• title: Video title
• game_type: Type of game (e.g., "basketball", "football", "soccer")
• teams: Array of participating team names
• score: Final score as a string
• duration_seconds: Video duration in seconds
• video_url: URL to the video file
• thumbnail_url: URL to the thumbnail image
• description: Video description
• tags: Array of tags for categorization
• player_stats: JSON object containing player statistics
• match_date: Date when the match was played
• venue: Location where the match took place
• league: League or competition name
• season: Season identifier
• created_at / updated_at: Timestamps

Prerequisites

• Node.js (v18 or higher)
• PostgreSQL (v12 or higher)
• npm or yarn

Installation

1. Clone and setup the project:

   git clone <repository-url>
   cd metadata-mcp
   npm install
   

2. Configure PostgreSQL:

   • Ensure PostgreSQL is running
   • Create a database named video_metadata (or use your preferred name)
   • Copy .env.example to .env and update the database credentials:

   cp .env.example .env
   

3. Update environment variables in .env:

   POSTGRES_USER=your_username
   POSTGRES_PASSWORD=your_password
   POSTGRES_HOST=localhost
   POSTGRES_PORT=5432
   POSTGRES_DB=video_metadata
   

4. Build the project:

   npm run build
   

5. Initialize the database with sample data:

   npm run setup
   

Usage

Running the MCP Server

npm start

The server will run on stdio and can be connected to by MCP clients.

Available Tools

The server provides the following tools:

1. list_video_metadata

Get all video metadata records.

2. get_video_metadata

Get a specific video metadata record by ID.

• Parameters: id (number)

3. search_video_metadata

Search video metadata with filters.

• Parameters:
  • game_type (string, optional)
  • teams (array of strings, optional)
  • league (string, optional)
  • season (string, optional)
  • tags (array of strings, optional)
  • match_date_from (ISO date string, optional)
  • match_date_to (ISO date string, optional)

4. create_video_metadata

Create a new video metadata record.

• Required Parameters: title, game_type, teams
• Optional Parameters: All other fields

5. update_video_metadata

Update an existing video metadata record.

• Required Parameters: id
• Optional Parameters: Any field to update

6. delete_video_metadata

Delete a video metadata record.

• Parameters: id (number)

7. get_game_types

Get all unique game types from the database.

8. get_teams

Get all unique teams from the database.

9. get_leagues

Get all unique leagues from the database.

Example Usage with Claude Desktop

Add this to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "video-metadata": {
      "command": "node",
      "args": ["/path/to/metadata-mcp/build/index.js"],
      "env": {
        "POSTGRES_USER": "your_username",
        "POSTGRES_PASSWORD": "your_password",
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "POSTGRES_DB": "video_metadata"
      }
    }
  }
}

Sample Data

The setup script includes sample data for:

• NBA Finals Game 7 (Lakers vs Celtics)
• Super Bowl LVIII (Chiefs vs 49ers)
• Champions League Final (Real Madrid vs Liverpool)

Development

Project Structure

src/
├── index.ts        # Main MCP server implementation
├── database.ts     # Database manager and schema
└── setup.ts        # Database initialization script

build/              # Compiled JavaScript files
tsconfig.json       # TypeScript configuration
package.json        # Dependencies and scripts
.env.example        # Environment variables template

Building

npm run build

Adding New Features

1. Extend the VideoMetadata interface in database.ts
2. Add corresponding database schema changes in initializeSchema()
3. Implement new tools in the MCP server (index.ts)
4. Add validation schemas using Zod

Database Indexes

The following indexes are automatically created for optimal performance:

• idx_video_metadata_game_type: On game_type field
• idx_video_metadata_teams: GIN index on teams JSONB array
• idx_video_metadata_tags: GIN index on tags JSONB array
• idx_video_metadata_match_date: On match_date field
• idx_video_metadata_league: On league field

Error Handling

The server includes comprehensive error handling:

• Database connection errors
• Invalid parameter validation (using Zod schemas)
• Resource not found errors
• Proper MCP error codes and messages

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

License

MIT License - see LICENSE file for details.