The Docs API Tools family provides a comprehensive interface to the Help Scout Docs v1 API, enabling interaction with knowledge base sites, collections, categories, and articles. Unlike the primary Mailbox API which uses OAuth2, the Docs API utilizes Basic Authentication with a dedicated API key.
These tools allow the MCP server to manage and retrieve knowledge base content. The system is designed with security-first principles, including mandatory HTTPS and a redaction sub-system to prevent the accidental exposure of sensitive information in documentation.
HelpScoutDocsClient: A specialized HTTP client for the Docs v1 API located in src/utils/helpscout-docs-client.ts src/utils/helpscout-docs-client.ts27ToolHandler: Orchestrates the tool execution and data transformation in src/tools/index.ts src/tools/index.ts140redactDocsSecrets: A security function that scrubs sensitive fields from API responses src/tools/index.ts1614-1629The following diagram illustrates the flow from a Natural Language request to the execution of a Docs API tool.
"Natural Language to Code Entity Space"
Sources: src/tools/index.ts140-150 src/utils/helpscout-docs-client.ts27-58 src/utils/config.ts53-63
The HelpScoutDocsClient is a dedicated class for interacting with the Help Scout Docs v1 API. It is distinct from the HelpScoutClient (used for Mailbox v2) because the Docs API requires Basic Authentication and uses a different base URL.
The client uses the following configuration parameters:
HELPSCOUT_DOCS_BASE_URL (Defaults to https://docsapi.helpscout.net/v1/) src/utils/helpscout-docs-client.ts104HELPSCOUT_DOCS_API_KEY src/utils/helpscout-docs-client.ts130http.Agent and https.Agent with keepAlive and maxSockets configuration src/utils/helpscout-docs-client.ts33-47getBaseUrl() method enforces that the URL must use the https: protocol to protect the API key src/utils/helpscout-docs-client.ts112-114transformError() method maps Axios errors to the internal ApiError type, handling specific status codes like 429 (Rate Limit), 404 (Not Found), and 401/403 (Unauthorized) src/utils/helpscout-docs-client.ts157-208Sources: src/utils/helpscout-docs-client.ts27-208 src/utils/config.ts8-35
The server exposes a suite of tools for the Docs API. All tools are registered in the ToolHandler and advertised to the MCP client src/__tests__/tools.test.ts90-105
| Tool Name | Purpose | API Endpoint |
|---|---|---|
listDocsSites | Lists all Docs sites in the account. | GET /sites |
getDocsSite | Retrieves metadata for a specific site. | GET /sites/{id} |
listDocsCollections | Lists collections within a site. | GET /collections |
getDocsCollection | Retrieves a specific collection. | GET /collections/{id} |
listDocsCategories | Lists categories within a collection. | GET /collections/{id}/categories |
getDocsCategory | Retrieves a specific category. | GET /categories/{id} |
listDocsArticles | Lists articles within a category or collection. | GET /categories/{id}/articles |
searchDocsArticles | Performs a keyword search across articles. | GET /search/articles |
getDocsArticle | Retrieves full article content (HTML/Text). | GET /articles/{id} |
listDocsRedirects | Lists URL redirects for a site. | GET /sites/{id}/redirects |
getDocsRedirect | Retrieves a specific redirect by ID. | GET /redirects/{id} |
The Docs API uses a specific envelope format for collections, defined by the DocsCollectionEnvelope<T> interface src/utils/helpscout-docs-client.ts20-25:
Sources: src/utils/helpscout-docs-client.ts20-25 src/tools/index.ts72-86 src/__tests__/tools.test.ts90-105
To maintain security and compliance, the server implements a redaction layer specifically for Docs entities.
The redactDocsSecrets function is applied to article and site objects before they are returned to the MCP client. This ensures that internal metadata or potentially sensitive configuration fields are not exposed src/tools/index.ts1614-1629
"Security Sub-system Mapping"
Sources: src/utils/helpscout-docs-client.ts103-142 src/tools/index.ts1614-1629
The Docs API uses a page and pages (total pages) model for pagination. The server implements a helper function getDocsNextPage to calculate the next available page for iterative fetching src/tools/index.ts135-138
Sources: src/tools/index.ts135-138
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.