README.md•5.73 kB
# 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:**
```bash
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:
```bash
cp .env.example .env
```
3. **Update environment variables in `.env`:**
```env
POSTGRES_USER=your_username
POSTGRES_PASSWORD=your_password
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=video_metadata
```
4. **Build the project:**
```bash
npm run build
```
5. **Initialize the database with sample data:**
```bash
npm run setup
```
## Usage
### Running the MCP Server
```bash
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:
```json
{
"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
```bash
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.