Code Snippet Server

# Handlers Directory Documentation ## Overview This directory contains the MCP server request handlers that implement core functionality for resources, tools, and prompts. The handlers integrate with Gmail, Google Calendar, and systemprompt.io APIs to provide comprehensive email, calendar, and prompt management capabilities. ## Handler Files ### `resource-handlers.ts` Implements handlers for managing systemprompt.io blocks (resources): - `handleListResources()`: Lists available blocks with metadata - Currently returns the default agent resource - Includes name, description, and MIME type - `handleResourceCall()`: Retrieves block content by URI (`resource:///block/{id}`) - Validates URI format (`resource:///block/{id}`) - Returns block content with proper MCP formatting - Supports metadata and content management ### `tool-handlers.ts` Implements handlers for Gmail, Calendar, and resource management tools: - `handleListTools()`: Lists available tools with their schemas - `handleToolCall()`: Executes tool operations: **Gmail Operations:** - `systemprompt_list_messages`: List and filter Gmail messages - `systemprompt_get_message`: Get specific email details - `systemprompt_search_messages`: Search emails with query - `systemprompt_list_labels`: List Gmail labels - `systemprompt_send_email`: Send new emails - `systemprompt_create_draft`: Create email drafts - `systemprompt_list_drafts`: List email drafts - `systemprompt_delete_draft`: Delete email drafts **Calendar Operations:** - `systemprompt_list_events`: List calendar events - `systemprompt_get_event`: Get specific event details - `systemprompt_search_events`: Search calendar events - `systemprompt_list_calendars`: List available calendars **Resource Operations:** - `systemprompt_fetch_resource`: Retrieve block content ### `prompt-handlers.ts` Implements handlers for prompt management: - `handleListPrompts()`: Lists available prompts with metadata - Returns predefined prompts for common tasks - Includes name, description, and required arguments - `handleGetPrompt()`: Retrieves specific prompt by name - Returns prompt details with messages - Supports task-specific prompts (Todo List, Email, Calendar) ## Implementation Details ### Resource Handlers - Default agent resource provides core functionality - Includes specialized instructions for email and calendar management - Supports voice configuration for audio responses - Returns content with proper MCP formatting ### Tool Handlers - Implements comprehensive email and calendar operations - Supports advanced Gmail features: - Message filtering by date, sender, recipient - Attachment handling - Label management - Draft email operations - Calendar integration features: - Event management across multiple calendars - Search and retrieval capabilities - Primary and secondary calendar support - Input validation through TypeScript interfaces - Proper error handling and response formatting ### Prompt Handlers - Predefined prompts for common tasks: - Todo List Organizer - Email Analyzer - Calendar Overview - Smart Email Composer - Meeting Scheduler - Each prompt includes: - Required and optional arguments - Clear descriptions - Task-specific instructions - Supports both static and dynamic instructions ## Error Handling - Comprehensive error handling across all handlers - Specific error cases: - Invalid resource URI format - Resource not found - Invalid tool parameters - API operation failures - Authentication errors - Descriptive error messages for debugging - Proper error propagation to clients ## Usage Example ```typescript // Register handlers with MCP server server.setRequestHandler(ListResourcesRequestSchema, handleListResources); server.setRequestHandler(ReadResourceRequestSchema, handleResourceCall); server.setRequestHandler(ListToolsRequestSchema, handleListTools); server.setRequestHandler(CallToolRequestSchema, handleToolCall); server.setRequestHandler(ListPromptsRequestSchema, handleListPrompts); server.setRequestHandler(GetPromptRequestSchema, handleGetPrompt); ``` ## Notifications The server implements change notifications for: - Prompt updates (`sendPromptChangedNotification`) - Resource updates (`sendResourceChangedNotification`) - Tool operation completions These are sent asynchronously after successful operations to maintain responsiveness. ## Authentication - Integrates with Google OAuth for Gmail and Calendar access - Handles token management and refresh - Supports multiple authentication scopes - Maintains secure credential handling ## Testing Comprehensive test coverage includes: - Unit tests for all handlers - Mock services for Gmail and Calendar operations - Error case validation - Response format verification - Tool operation validation