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.

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
• Security Layer: Implements API key management, access control, and audit logging
• Caching System: Optimizes performance for frequent operations

Current Tools

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 database with pgvector:

   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  # or 'openai'
   EMBEDDING_MODEL=nomic-embed-text
   OLLAMA_URL=http://localhost:11434
   # OPENAI_API_KEY=your_openai_key  # Uncomment if using OpenAI
   
   # 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
│   │   ├── ollama.ts           # Ollama client for embeddings
│   │   ├── openai.ts           # OpenAI client (alternative)
│   │   └── service.ts          # Embedding service
│   ├── 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

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

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