The Reporting Tools sub-system provides comprehensive access to Help Scout's analytics engine. It allows for the retrieval of high-level metrics and granular drilldown data across company performance, conversation volume, team productivity, and customer happiness.
The reporting system is built to provide structured analytical data rather than raw conversation streams. To prevent performance degradation and ensure API compliance, the server implements several guardrails:
ReportBaseInput schema src/schema/types.ts379-388YYYY-MM-DDTHH:MM:SSZ). The ToolHandler includes a normalizeApiDateParam helper to strip milliseconds, as the Help Scout API rejects the .xxx format src/tools/index.ts168-180mailboxes or tags to avoid massive account-wide aggregations that may hit upstream timeouts src/schema/types.ts380-388The reporting tools follow a standardized pipeline from the MCP request to the Help Scout API:
Sources: src/tools/index.ts182-205 src/utils/helpscout-client.ts2-5 src/schema/types.ts29-31
All reporting tools utilize a base set of parameters defined in the ReportBaseInput schema src/schema/types.ts379-388
| Parameter | Type | Description |
|---|---|---|
start | ISO 8601 | Start date for the primary reporting period. |
end | ISO 8601 | End date for the primary reporting period. |
previousStart | ISO 8601 | Start date for the comparison period. |
previousEnd | ISO 8601 | End date for the comparison period. |
mailboxes | number[] | Array of mailbox IDs to filter by. |
tags | string[] | Array of tag names to filter by. |
The ToolHandler utilizes specialized builders to transform Zod-validated inputs into Help Scout query parameters:
buildReportQueryParams: Handles base dates, mailboxes, and tags src/tools/index.ts182-196buildProductivityReportQueryParams: Adds officeHours (boolean) and viewBy (granularity) src/tools/index.ts198-205buildUserReportQueryParams: Scopes parameters to a specific user src/tools/index.ts207-214Sources: src/tools/index.ts182-214 src/schema/types.ts379-388
These tools provide the "Pulse" of the support organization, focusing on volume and high-level trends.
getCompanyReport: Summary of overall performance src/tools/index.ts1310-1325getConversationsReport: High-level metrics on conversation volume src/tools/index.ts1361-1376getChannelReport: Volume breakdown by email, chat, phone, etc src/tools/index.ts1536-1551getProductivityReport: General overview of team efficiency, including response times src/tools/index.ts1570-1585getHappinessReport: Aggregates ratings from the Help Scout "Happiness" feature, providing scores and percentage breakdowns src/tools/index.ts1502-1517getUserReport: Metrics scoped to a specific team member src/tools/index.ts1670-1685getDocsReport: Analytics for the Help Scout Docs knowledge base src/tools/index.ts1772-1787Sources: src/tools/index.ts1310-1787 src/schema/types.ts65-71
The relationship between input schemas and the reporting response is defined through a union of types in the schema layer.
The reporting tools are subject to validation via the HelpScoutAPIConstraints class. This ensures that when an LLM attempts to run a report, it follows logic like ensuring start dates precede end dates src/utils/api-constraints.ts15-40
If a report request fails due to an invalid date range or missing required fields, the ToolHandler catches the ApiError and transforms it into a McpError using createMcpToolError src/utils/mcp-errors.ts25-35
Sources: src/schema/types.ts379-388 src/utils/api-constraints.ts15-40 src/utils/mcp-errors.ts25-35 src/tools/index.ts4-6
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.