The Data Layer serves as the foundational abstraction for interacting with the Help Scout API. It is responsible for secure authentication, robust network communication, data validation via schemas, and performance optimization through caching. This layer ensures that the rest of the MCP server can operate on structured, validated data without managing the complexities of the Help Scout OAuth2 flow or rate-limiting constraints.
The data layer is structured to move data from the "Natural Language Space" (where LLMs operate) into the "Code Entity Space" (where the Help Scout API resides) by applying strict validation and transformation rules.
The following diagram illustrates how a user's intent is transformed into a validated API request.
Intent Transformation Pipeline
Sources: src/utils/helpscout-client.ts104-124 src/schema/types.ts82-132 src/utils/cache.ts22-41
The server utilizes two distinct clients to interact with the Help Scout ecosystem. The HelpScoutClient manages the primary Mailbox API using OAuth2 Client Credentials flow src/utils/helpscout-client.ts106-108 It implements a robust executeWithRetry mechanism that handles exponential backoff, jitter, and specialized logic for refreshing stale OAuth tokens during 401 errors src/utils/helpscout-client.ts210-220 The HelpScoutDocsClient provides access to the Docs v1 API using Basic Authentication src/utils/helpscout-docs-client.ts119-142 Both clients share an optimized connection pooling strategy via HttpAgent and HttpsAgent to maintain performance under high concurrency src/utils/helpscout-client.ts133-147 src/utils/helpscout-docs-client.ts33-47
For details, see Help Scout API Clients.
All data entering or leaving the server is validated against Zod schemas. This ensures that the MCP server remains "type-safe" even when dealing with unpredictable external API responses. The system defines core entities like InboxSchema src/schema/types.ts4-11 ConversationSchema src/schema/types.ts13-44 and CustomerSchema src/schema/types.ts139-174 It also handles complex input validation, such as the SearchConversationsInputSchema which provides structured filters for the Help Scout query language src/schema/types.ts83-109
For details, see Schema and Type System.
To reduce latency and avoid hitting API rate limits, the server employs an in-memory LRUCache src/utils/cache.ts11-20 Cache keys are generated using SHA-256 hashes of the request prefix and parameters to ensure uniqueness across different tool calls src/utils/cache.ts22-26 The layer supports endpoint-specific TTLs (Time-To-Live), allowing frequently changing data like conversation threads to expire faster than static data like mailbox lists src/utils/cache.ts43-55 Configuration is managed via CACHE_TTL_SECONDS and MAX_CACHE_SIZE environment variables src/utils/cache.ts15-19
For details, see Caching Layer.
The server uses a centralized error handling strategy to map upstream API failures to standard MCP error codes. This is facilitated by the transformError method in the client which converts AxiosError instances into structured ApiError types src/utils/helpscout-docs-client.ts157-208 Logging is handled via a dedicated Logger class that outputs to stderr src/utils/helpscout-client.ts162-167 ensuring logs do not interfere with the MCP JSON-RPC protocol on stdout.
For details, see Error Handling and Logging.
The following diagram bridges the internal TypeScript classes and schemas to the external Help Scout API endpoints they interact with.
System Entity Mapping
Sources: src/utils/helpscout-client.ts104-160 src/utils/helpscout-docs-client.ts27-58 src/schema/types.ts4-109
Sources:
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.