SproutVideo MCP Server

A Model Context Protocol (MCP) server that wraps the SproutVideo API, enabling AI models to interact with SproutVideo content through standardized tools with advanced database persistence, semantic search, and security features.

Overview

This project implements a Model Context Protocol server that allows AI models to access, search, and manipulate video content on SproutVideo. It follows the MCP specification to expose SproutVideo functionality as tools that can be called by AI systems, with an additional layer for metadata persistence, semantic search, and enhanced security.

Documentation

- API Documentation - Detailed information about the API endpoints, request/response formats, and examples
- Architecture Diagrams - Visual representations of system architecture, data flows, and component interactions
- Database Schema - Comprehensive documentation of database tables, fields, and relationships
- Setup Guide - Detailed instructions for installing, configuring, and running the server
- Tool Examples - Comprehensive examples for using each tool with code samples in multiple languages
- Troubleshooting Guide - Comprehensive guide for diagnosing and resolving common issues
- User Guide - Practical instructions for using the MCP Server with AI models, including examples and best practices
- Technical Tests - Information about test status and recent fixes
- Types Reference - Comprehensive list of types and interfaces used in the project

Features

- MCP Compliant: Implements the Model Context Protocol for seamless integration with AI systems
- SproutVideo Integration: Provides a bridge to SproutVideo's API with robust rate limiting and retry mechanisms
- Tool-based Architecture: Exposes SproutVideo functionality as callable tools
- Environment-based Configuration: Simple setup using environment variables
- Metadata Persistence: Stores video metadata in PostgreSQL for advanced querying capabilities
- Semantic Search: Uses vector embeddings to enable natural language searching of video content
- High Availability Embeddings: Primary provider with automatic fallback for uninterrupted service
- Security Layer: Implements API key management, access control, and audit logging
- Caching System: Optimizes performance for frequent operations

Current Tools

| Tool Name | Description | Parameters |
| ------------------------ | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| get_a_video | Retrieves video information from SproutVideo | videoId: The ID of the video to retrieve |
| list_videos | Lists all videos from SproutVideo | page: Page number for pagination (defaults to 1 if not provided)<br>perPage: Number of videos per page, max 100 (defaults to 25 if not provided)<br>orderBy: Field to order by: created_at, updated_at, duration, title (optional)<br>orderDir: Sort direction: asc or desc (optional)<br>folderId: Filter by folder ID (optional)<br>tagId: Filter by tag ID (optional)<br>tagName: Filter by tag name (optional) |
| search_videos | Semantically searches videos using natural language | query: The natural language search query<br>limit: Maximum number of results to return (optional)<br>filter: Additional metadata filters (optional) |
| edit_video_metadata | Updates video metadata | videoId: The ID of the video to update<br>title: New title (optional)<br>description: New description (optional)<br>tags: New tags array (optional)<br>privacy: Privacy setting (optional) |
| generate_video_summary | Creates a concise summary of video content | videoId: The ID of the video to summarize |

Prerequisites

- Node.js (v16 or higher)
- npm or yarn
- PostgreSQL (with pgvector extension)
- Ollama (for local embeddings) or OpenAI API key
- SproutVideo API Key

Installation

1. Clone the repository:

   git clone https://github.com/twentynineteen/sproutvideo-mcp-server.git
   cd sproutvideo-mcp-server
   

2. Install dependencies:

   npm install
   

3. Set up PostgreSQL with pgvector extension:

We've provided an automated script that verifies and sets up pgvector:

   ./scripts/setup_pgvector.sh
   

This script will:

- Check if the required databases exist and create them if needed
- Verify the pgvector extension is installed and enable it if possible
- Test vector operations capability in your PostgreSQL instance
- Provide clear guidance if manual installation steps are needed

Alternatively, you can manually set up the databases:

   psql -c "CREATE DATABASE sproutvideo_mcp;"
   psql -d sproutvideo_mcp -c "CREATE EXTENSION IF NOT EXISTS vector;"
   

4. Create a .env file in the root directory with your configuration:

   # API Keys
   SPROUTVIDEO_API_KEY=your_api_key_here
# Database Configuration

   DB_HOST=localhost

   DB_PORT=5432

   DB_NAME=sproutvideo_mcp

   DB_USER=postgres

   DB_PASSWORD=your_db_password
# Embedding Configuration

   EMBEDDING_PROVIDER=ollama      # Primary provider: 'ollama' or 'openai'

   EMBEDDING_FALLBACK=openai      # Optional fallback provider: 'ollama' or 'openai'

   EMBEDDING_MODEL=nomic-embed-text

   OLLAMA_URL=http://localhost:11434

   OPENAI_API_KEY=your_openai_key  # Required if using OpenAI as primary or fallback
# Security and Performance

   API_RATE_LIMIT=100

   CACHE_TTL=3600

   LOGGING_LEVEL=info

   

5. Run database migrations:

   npm run migrate
   

Usage

Build the project

npm run build

Run the server

npm start

The server will initialize and start listening for MCP requests on standard input/output channels.

Sync video metadata

npm run sync

This command synchronizes video metadata from SproutVideo API to your local database.

Project Structure

sproutvideo-mcp-server/
├── src/                        # Source code
│   ├── api/                    # API Integration Layer
│   │   ├── client.ts           # SproutVideo API client
│   │   ├── rateLimiter.ts      # Rate limiting implementation
│   │   └── transformers/       # Response transformers
│   ├── database/               # Persistence Layer
│   │   ├── entities/           # Database entity definitions
│   │   ├── migrations/         # Database migrations
│   │   └── connection.ts       # Database connection manager
│   ├── embedding/              # Intelligence Layer
│   │   ├── OllamaProvider.ts   # Ollama embedding provider
│   │   ├── OpenAIProvider.ts   # OpenAI embedding provider
│   │   ├── EmbeddingService.ts # Embedding service with fallback support
│   │   └── types.ts            # Common embedding interfaces
│   ├── mcp/                    # MCP Protocol Layer
│   │   ├── handlers/           # Tool handler implementations
│   │   ├── schema.ts           # Tool schemas and validation
│   │   └── server.ts           # MCP server implementation
│   ├── search/                 # Search Functionality
│   │   ├── cache.ts            # Search result caching
│   │   └── vectorSearch.ts     # Vector similarity search
│   ├── security/               # Security Layer
│   │   ├── access.ts           # Access control
│   │   ├── audit.ts            # Audit logging
│   │   └── encryption.ts       # Data encryption utilities
│   ├── tools/                  # Tool Implementations
│   │   ├── videoTools.ts       # Video-related tools
│   │   └── searchTools.ts      # Search-related tools
│   ├── utils/                  # Common utilities
│   ├── config.ts               # Configuration management
│   └── index.ts                # Entry point
├── tests/                      # Test files mirroring src structure
├── build/                      # Compiled JavaScript files
├── scripts/                    # Utility scripts
│   ├── sync.ts                 # Database synchronization
│   └── migrations.ts           # Migration runner
├── .env                        # Environment variables (not in git)
├── .env.example                # Example environment configuration
├── .eslintrc                   # ESLint configuration
├── .gitignore                  # Git ignore file
├── .prettierrc                 # Prettier configuration
├── jest.config.js              # Jest test configuration
├── package.json                # Project metadata and dependencies
├── tsconfig.json               # TypeScript configuration
├── PLANNING.md                 # Technical vision and architecture
├── TASKS.md                    # Development task tracking
└── README.md                   # This documentation

High Availability Embedding System

The server supports multiple embedding providers with an automatic fallback mechanism:

1. Primary Provider: Configured via EMBEDDING_PROVIDER (defaults to Ollama)
2. Fallback Provider: Optionally configured via EMBEDDING_FALLBACK

This system provides high availability by automatically switching to the fallback provider if the primary provider fails, ensuring uninterrupted service. This applies to both embedding generation and text generation capabilities.

Supported providers:

- Ollama: Local embedding generation with models like nomic-embed-text
- OpenAI: Cloud-based embeddings using OpenAI's embedding models

Configure the system to balance between:

- Performance (Ollama running locally offers lower latency)
- Reliability (OpenAI offers high uptime but requires API key)
- Cost efficiency (Ollama has no per-request costs)

Example configurations:

1. Local-first with cloud fallback:

   EMBEDDING_PROVIDER=ollama
   EMBEDDING_FALLBACK=openai
   OPENAI_API_KEY=your_key_here
   

2. Cloud-first with local fallback:

   EMBEDDING_PROVIDER=openai
   EMBEDDING_FALLBACK=ollama
   OPENAI_API_KEY=your_key_here
   

3. Local-only (no fallback):

   EMBEDDING_PROVIDER=ollama

   

How It Works

1. The server initializes with the MCP protocol handlers and establishes database connections.
2. Video metadata is synced from SproutVideo to the local database, with embeddings generated for search.
3. The server listens for tool listing requests and returns available tools.
4. When a tool is called, parameters are validated and the appropriate handler is invoked.
5. For data retrieval operations, the server first checks the local database before making API calls.
6. Semantic search leverages vector embeddings to find videos matching natural language queries.
7. Results are formatted according to the MCP specification and returned to the caller.

Technical Implementation

The server is built with TypeScript and uses the following key components:

- MCP SDK: For implementing the Model Context Protocol
- Axios: For making HTTP requests to the SproutVideo API
- StdioServerTransport: For communication via stdin/stdout
- PostgreSQL with pgvector: For metadata storage and vector similarity search
- TypeORM: For database entity management
- Ollama/OpenAI: For generating embeddings from text
- Jest: For comprehensive testing
- Environment Variables: For securely storing configuration

Error Handling

The server implements comprehensive error handling:

- Parameter validation with clear error messages
- API error handling with appropriate status codes
- Graceful error formatting following MCP specifications
- Rate limiting with exponential backoff
- Database connection retry mechanisms
- Audit logging for critical errors

Development

Test Status

We maintain a comprehensive test coverage across the entire codebase. Our current test status shows 96% of all tests passing. For detailed information about test status and recent fixes, see TESTS.md.

The test suite includes:

- Unit tests for all components
- Integration tests for critical system paths
- Performance tests for search and caching systems
- Security implementation tests

Only a small number of example tests remain to be fixed, which are tracked in our task list.

Adding New Tools

To add a new tool to the server:

1. Add the tool definition to the schema in src/mcp/schema.ts
2. Create a tool handler in src/mcp/handlers/
3. Register the handler in the MCP server
4. Add integration tests in the corresponding test file
5. Update this README with the new tool details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

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

Acknowledgments

- Model Context Protocol - For the MCP specification
- SproutVideo API - For video hosting services
- pgvector - For vector similarity search in PostgreSQL
- Ollama - For local embedding generation
- OpenAI - For cloud-based embeddings and completions