SystemPrompt MCP Notion Server

# Services Directory Documentation ## Overview This directory contains service implementations that handle external integrations and business logic for the MCP server. The services are organized into two main categories: 1. System Prompt Services - For interacting with the systemprompt.io API 2. Notion Services - For interacting with the Notion API ## Service Architecture ### Base Services #### `notion-base-service.ts` An abstract base class that provides common functionality for all Notion services: ```typescript abstract class NotionBaseService { protected client: NotionClient; constructor(); protected waitForInit(): Promise<void>; } ``` Features: - Automatic client initialization - Shared client instance management - Error handling for API failures ### Core Services #### `systemprompt-service.ts` A singleton service for interacting with the systemprompt.io API: ```typescript class SystemPromptService { private static instance: SystemPromptService | null = null; static initialize(apiKey: string, baseUrl?: string): void; static getInstance(): SystemPromptService; static cleanup(): void; // Prompt Operations async getAllPrompts(): Promise<SystempromptPromptResponse[]>; // Block Operations async listBlocks(): Promise<SystempromptBlockResponse[]>; async getBlock(blockId: string): Promise<SystempromptBlockResponse>; } ``` Features: - Singleton pattern with API key initialization - Comprehensive error handling with specific error types - Configurable API endpoint - Type-safe request/response handling #### `notion-service.ts` Manages Notion API interactions: ```typescript class NotionService extends NotionBaseService { static getInstance(): NotionService; async initialize(): Promise<void>; // Page Operations async searchPages(query: string): Promise<NotionPage[]>; async getPage(pageId: string): Promise<NotionPage>; async createPage(options: CreatePageOptions): Promise<NotionPage>; async updatePage(options: UpdatePageOptions): Promise<NotionPage>; // Database Operations async listDatabases(): Promise<NotionDatabase[]>; async getDatabaseItems(databaseId: string): Promise<NotionPage[]>; // Comment Operations async createComment(pageId: string, content: string): Promise<NotionComment>; async getComments(pageId: string): Promise<NotionComment[]>; } ``` ## Implementation Details ### Error Handling All services implement comprehensive error handling: ```typescript try { const response = await this.client.pages.retrieve({ page_id: pageId }); if (!response) { throw new Error("Page not found"); } return this.mapPageResponse(response); } catch (error) { throw new Error(`Notion API request failed: ${error.message}`); } ``` ### Authentication #### System Prompt Authentication - API key-based authentication - Key passed via headers - Environment variable configuration #### Notion Authentication - API token-based authentication - Integration token management - Capability-based access control ## Usage Examples ### System Prompt Service ```typescript // Initialize SystemPromptService.initialize(process.env.SYSTEMPROMPT_API_KEY); const service = SystemPromptService.getInstance(); // Get all prompts const prompts = await service.getAllPrompts(); // List blocks const blocks = await service.listBlocks(); ``` ### Notion Service ```typescript // Initialize const notionService = NotionService.getInstance(); await notionService.initialize(); // Page operations const pages = await notionService.searchPages("query"); const page = await notionService.getPage("page-id"); // Database operations const databases = await notionService.listDatabases(); const items = await notionService.getDatabaseItems("database-id"); // Comment operations const comment = await notionService.createComment("page-id", "comment text"); const comments = await notionService.getComments("page-id"); ``` ## Testing All services have corresponding test files in the `__tests__` directory: - `systemprompt-service.test.ts` - `notion-service.test.ts` - `notion-base-service.test.ts` Tests cover: - Service initialization - API interactions - Error handling - Authentication flows - Response mapping - Edge cases