@felores/mcp-video 0.5.3 → 0.5.4

package/documentation/mcp-inspector-guide.md

@@ -1,308 +0,0 @@
-# MCP Inspector Guide for LLMs
-
-This guide provides detailed information about using the MCP Inspector tool for testing, debugging, and validating MCP servers.
-
-## 1. Getting Started
-
-### Installation and Basic Usage
-```bash
-# Run directly without installation
-npx mcp-inspector <server-command>
-
-# For NPM/PyPi packages
-npx mcp-inspector npx -y @your-package/server-name
-
-# For local development
-npx mcp-inspector node path/to/your/server.js
-npx mcp-inspector python path/to/your/server.py
-```
-
-### Server Connection Setup
-1. Select appropriate transport (stdio/SSE)
-2. Configure command-line arguments
-3. Set required environment variables
-4. Test initial connection
-
-## 2. Core Features
-
-### Server Connection Pane
-1. Transport Selection:
-   - stdio for local servers
-   - SSE for network-based servers
-   - Custom transport configuration
-
-2. Connection Settings:
-   - Command-line arguments
-   - Environment variables
-   - Connection timeouts
-
-3. Status Monitoring:
-   - Connection state
-   - Protocol version
-   - Capability negotiation
-
-### Resources Tab
-1. Resource Listing:
-   ```typescript
-   // Example resource listing structure
-   {
-     resources: [
-       {
-         uri: "custom://resource",
-         name: "Resource Name",
-         description: "Resource description",
-         mimeType: "text/plain"
-       }
-     ]
-   }
-   ```
-
-2. Resource Inspection:
-   - View metadata
-   - Examine content
-   - Check MIME types
-   - Test resource reading
-
-3. Subscription Testing:
-   - Subscribe to updates
-   - Monitor changes
-   - Test unsubscribe
-
-### Prompts Tab
-1. Template Inspection:
-   ```typescript
-   // Example prompt structure
-   {
-     name: "prompt-name",
-     description: "Prompt description",
-     arguments: [
-       {
-         name: "arg1",
-         description: "Argument description",
-         required: true
-       }
-     ]
-   }
-   ```
-
-2. Testing Features:
-   - View available templates
-   - Test with custom arguments
-   - Preview generated messages
-   - Validate responses
-
-### Tools Tab
-1. Tool Discovery:
-   ```typescript
-   // Example tool listing
-   {
-     tools: [
-       {
-         name: "tool-name",
-         description: "Tool description",
-         inputSchema: {
-           type: "object",
-           properties: {
-             // Parameter definitions
-           }
-         }
-       }
-     ]
-   }
-   ```
-
-2. Testing Features:
-   - List available tools
-   - Validate schemas
-   - Test execution
-   - Monitor results
-
-### Notifications Pane
-1. Message Types:
-   - Server logs
-   - Error messages
-   - Status updates
-   - Progress notifications
-
-2. Monitoring:
-   - Real-time updates
-   - Message filtering
-   - Error tracking
-
-## 3. Testing Workflows
-
-### Development Workflow
-1. Initial Testing:
-   ```bash
-   # Start Inspector with development server
-   npx mcp-inspector npm run dev
-   ```
-
-2. Development Cycle:
-   - Make code changes
-   - Restart server
-   - Test affected features
-   - Monitor logs
-   - Debug issues
-
-3. Feature Testing:
-   - Verify basic functionality
-   - Test edge cases
-   - Check error handling
-   - Validate responses
-
-### Resource Testing
-1. Listing Verification:
-   - Check resource discovery
-   - Validate metadata
-   - Test pagination
-   - Check updates
-
-2. Content Testing:
-   - Read resource content
-   - Verify MIME types
-   - Test binary data
-   - Check encoding
-
-3. Subscription Testing:
-   - Subscribe to resources
-   - Monitor updates
-   - Test unsubscribe
-   - Verify notifications
-
-### Tool Testing
-1. Discovery Testing:
-   - List available tools
-   - Verify schemas
-   - Check descriptions
-   - Validate metadata
-
-2. Execution Testing:
-   - Test with valid inputs
-   - Try invalid inputs
-   - Check error handling
-   - Monitor progress
-   - Validate results
-
-### Prompt Testing
-1. Template Verification:
-   - Check available prompts
-   - Validate arguments
-   - Test descriptions
-   - Verify schemas
-
-2. Generation Testing:
-   - Test with arguments
-   - Check message format
-   - Validate content
-   - Test error cases
-
-## 4. Debugging
-
-### Common Issues
-1. Connection Problems:
-   - Check server process
-   - Verify transport
-   - Monitor initialization
-   - Check capabilities
-
-2. Message Errors:
-   - Validate formats
-   - Check handlers
-   - Monitor responses
-   - Track errors
-
-3. Resource Issues:
-   - Check permissions
-   - Verify paths
-   - Test content types
-   - Monitor updates
-
-### Debugging Tools
-1. Console Logging:
-   ```typescript
-   // Server-side logging
-   console.error("Debug message");
-   ```
-
-2. Message Inspection:
-   - View raw messages
-   - Check formatting
-   - Track request/response
-   - Monitor timing
-
-3. Error Analysis:
-   - Stack traces
-   - Error codes
-   - Response validation
-   - Context examination
-
-## 5. Best Practices
-
-### Testing Strategy
-1. Systematic Approach:
-   - Test core features first
-   - Add edge cases
-   - Verify error handling
-   - Check performance
-
-2. Resource Management:
-   - Monitor memory usage
-   - Check file handles
-   - Verify cleanup
-   - Test limits
-
-3. Error Handling:
-   - Test all error paths
-   - Verify messages
-   - Check recovery
-   - Monitor cleanup
-
-### Security Testing
-1. Input Validation:
-   - Test boundaries
-   - Try invalid input
-   - Check sanitization
-   - Verify limits
-
-2. Authentication:
-   - Test credentials
-   - Check permissions
-   - Verify tokens
-   - Monitor access
-
-3. Resource Protection:
-   - Test access control
-   - Check paths
-   - Verify isolation
-   - Monitor usage
-
-## 6. Performance Testing
-
-### Response Time
-1. Operation Timing:
-   - Track latency
-   - Monitor variance
-   - Check thresholds
-   - Log outliers
-
-2. Batch Operations:
-   - Test concurrent requests
-   - Monitor memory
-   - Check throughput
-   - Verify ordering
-
-### Resource Usage
-1. Memory Monitoring:
-   - Track allocation
-   - Check leaks
-   - Monitor peaks
-   - Verify cleanup
-
-2. Connection Management:
-   - Test connection stability
-   - Check timeouts
-   - Monitor states
-   - Verify cleanup
-
-This guide should be used as a reference when testing and debugging MCP servers using the Inspector tool. Always consider the specific requirements of your server while following these guidelines.

package/documentation/mcp-llm-guide.md

@@ -1,379 +0,0 @@
-# MCP Development Guide for LLMs
-
-This guide provides structured information for LLMs to assist in creating, modifying, and using Model Context Protocol (MCP) servers.
-
-## 1. Core Concepts
-
-### Protocol Overview
-- MCP enables standardized communication between LLM applications and integrations
-- Uses client-server architecture with JSON-RPC 2.0 message format
-- Latest protocol version: 2024-11-05
-- Supports stdio and SSE transports
-
-### Key Components
-1. **Hosts**: LLM applications that initiate connections (e.g., Claude Desktop)
-2. **Clients**: Maintain 1:1 connections with servers
-3. **Servers**: Provide context, tools, and prompts to clients
-4. **Resources**: File-like data that can be read by clients
-5. **Tools**: Functions that can be called by the LLM
-6. **Prompts**: Pre-written templates for specific tasks
-
-## 2. Server Implementation Guidelines
-
-### Server Structure
-1. Core Server Class:
-```typescript
-class Server extends Protocol<ServerRequest, ServerNotification, ServerResult> {
-    constructor(serverInfo: Implementation, options: ServerOptions)
-    // Must implement base protocol methods
-}
-```
-
-2. Required Capabilities:
-```typescript
-interface ServerCapabilities {
-    experimental?: object;
-    logging?: object;
-    prompts?: { listChanged?: boolean };
-    resources?: { 
-        subscribe?: boolean;
-        listChanged?: boolean 
-    };
-    tools?: { listChanged?: boolean };
-}
-```
-
-### Essential Implementation Steps
-
-1. **Server Initialization**:
-```typescript
-const server = new Server(
-    {
-        name: "your-server-name",
-        version: "1.0.0"
-    },
-    {
-        capabilities: {
-            // Declare supported capabilities
-            resources: {},
-            tools: {},
-            prompts: {}
-        }
-    }
-);
-```
-
-2. **Request Handlers**:
-```typescript
-// Example tool handler
-server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: [
-        {
-            name: "tool-name",
-            description: "Tool description",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    // Define parameters
-                }
-            }
-        }
-    ]
-}));
-```
-
-3. **Transport Setup**:
-```typescript
-const transport = new StdioServerTransport();
-await server.connect(transport);
-```
-
-## 3. Core Features Implementation
-
-### Resources
-```typescript
-interface Resource {
-    uri: string;
-    name: string;
-    description?: string;
-    mimeType?: string;
-}
-
-// Handler example
-server.setRequestHandler(ListResourcesRequestSchema, async () => ({
-    resources: [
-        {
-            uri: "custom://resource",
-            name: "Resource Name",
-            description: "Resource description"
-        }
-    ]
-}));
-```
-
-### Tools
-```typescript
-interface Tool {
-    name: string;
-    description?: string;
-    inputSchema: {
-        type: "object";
-        properties?: object;
-        required?: string[];
-    };
-}
-
-// Handler example
-server.setRequestHandler(CallToolRequestSchema, async (request) => ({
-    content: [
-        {
-            type: "text",
-            text: "Tool execution result"
-        }
-    ]
-}));
-```
-
-### Prompts
-```typescript
-interface Prompt {
-    name: string;
-    description?: string;
-    arguments?: PromptArgument[];
-}
-
-// Handler example
-server.setRequestHandler(GetPromptRequestSchema, async (request) => ({
-    messages: [
-        {
-            role: "user",
-            content: {
-                type: "text",
-                text: "Prompt template"
-            }
-        }
-    ]
-}));
-```
-
-## 4. Best Practices
-
-### Error Handling
-1. Use appropriate error codes:
-```typescript
-enum ErrorCode {
-    ParseError = -32700,
-    InvalidRequest = -32600,
-    MethodNotFound = -32601,
-    InvalidParams = -32602,
-    InternalError = -32603
-}
-```
-
-2. Tool errors should be in result:
-```typescript
-{
-    isError: true,
-    content: [{
-        type: "text",
-        text: "Error description"
-    }]
-}
-```
-
-### Security Considerations
-1. Input Validation:
-   - Validate all parameters against schemas
-   - Sanitize file paths and system commands
-   - Validate URLs and external identifiers
-   - Check parameter sizes and ranges
-
-2. Access Control:
-   - Implement authentication where needed
-   - Use appropriate authorization checks
-   - Audit tool usage
-   - Rate limit requests
-
-3. Resource Protection:
-   - Validate resource paths
-   - Monitor resource usage
-   - Implement access controls
-   - Rate limit requests
-
-### Message Handling
-1. Request Processing:
-   - Validate inputs thoroughly
-   - Use type-safe schemas
-   - Handle errors gracefully
-   - Implement timeouts
-
-2. Progress Reporting:
-   - Use progress tokens for long operations
-   - Report progress incrementally
-   - Include total progress when known
-
-## 5. Client Integration Guidelines
-
-### Client Configuration
-```json
-{
-    "mcpServers": {
-        "server-name": {
-            "command": "command-to-run",
-            "args": ["arg1", "arg2"],
-            "env": {
-                "ENV_VAR": "value"
-            }
-        }
-    }
-}
-```
-
-### Environment Variables
-- Server inherits limited environment variables
-- Custom variables must be specified in config
-- Sensitive data should be in environment variables
-
-## 6. Testing and Debugging
-
-### MCP Inspector Usage
-1. Start inspector with server:
-```bash
-npx mcp-inspector your-server-command
-```
-
-2. Features to test:
-   - Resource listing and reading
-   - Tool execution
-   - Prompt generation
-   - Error handling
-   - Progress reporting
-
-### Common Issues
-1. Connection Problems:
-   - Check transport configuration
-   - Verify server process is running
-   - Check for initialization errors
-
-2. Message Handling:
-   - Validate message formats
-   - Check handler implementations
-   - Verify error responses
-
-3. Resource Issues:
-   - Check file permissions
-   - Validate URI formats
-   - Verify content types
-
-## 7. Performance and Scaling
-
-### Best Practices
-1. Resource Management:
-   - Cache when appropriate
-   - Implement cleanup
-   - Monitor memory usage
-
-2. Request Handling:
-   - Use appropriate timeouts
-   - Implement rate limiting
-   - Handle concurrent requests
-
-3. Error Recovery:
-   - Implement reconnection logic
-   - Handle partial failures
-   - Clean up resources
-
-## 8. Documentation Requirements
-
-### Server Documentation
-1. Capabilities Documentation:
-   - List supported features
-   - Document configuration options
-   - Describe environment variables
-
-2. API Documentation:
-   - Document all resources
-   - Document all tools
-   - Document all prompts
-   - Include example usage
-
-3. Error Documentation:
-   - List possible error codes
-   - Describe error conditions
-   - Include recovery steps
-
-### Integration Guide
-1. Setup Instructions:
-   - Installation steps
-   - Configuration options
-   - Environment setup
-
-2. Usage Examples:
-   - Basic usage patterns
-   - Common integrations
-   - Error handling examples
-
-## 9. Versioning and Updates
-
-### Version Management
-1. Protocol Versioning:
-   - Support LATEST_PROTOCOL_VERSION
-   - Handle version negotiation
-   - Maintain compatibility
-
-2. Server Versioning:
-   - Use semantic versioning
-   - Document breaking changes
-   - Provide migration guides
-
-### Update Handling
-1. Capability Updates:
-   - Notify clients of changes
-   - Handle capability negotiation
-   - Maintain backwards compatibility
-
-2. Resource Updates:
-   - Handle resource changes
-   - Notify subscribed clients
-   - Maintain consistency
-
-## 10. Specific Server Types
-
-### Database Servers (like Airtable)
-1. Required Capabilities:
-   - Resources for data access
-   - Tools for data manipulation
-   - Prompts for common operations
-
-2. Implementation Focus:
-   - Connection management
-   - Query handling
-   - Data transformation
-   - Error handling
-   - Rate limiting
-
-3. Security Considerations:
-   - API key management
-   - Access control
-   - Data validation
-   - Request sanitization
-
-4. Tools to Implement:
-   - List databases/bases
-   - Create/modify tables
-   - Query data
-   - Update records
-   - Delete records
-
-5. Resource Structure:
-   - Database schema
-   - Table contents
-   - Query results
-
-6. Error Handling:
-   - Connection errors
-   - Query errors
-   - Rate limit errors
-   - Authorization errors
-
-This guide should be used as a reference when assisting with MCP server development. Always consider the specific requirements and constraints of the project while following these guidelines.