{"_id":"@damianhodgkiss/helpscout-docs-mcp","_rev":"2-82147c8d81bc9b967cc3123d4bdbdca5","name":"@damianhodgkiss/helpscout-docs-mcp","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.0":{"name":"@damianhodgkiss/helpscout-docs-mcp","version":"1.0.0","keywords":["helpscout","docs","mcp","model-context-protocol","claude"],"author":{"name":"Damian Hodgkiss"},"license":"MIT","_id":"@damianhodgkiss/helpscout-docs-mcp@1.0.0","maintainers":[{"name":"damianhodgkiss","email":"damian@hodgkiss.id.au"}],"bin":{"helpscout-docs-mcp":"dist/index.js"},"dist":{"shasum":"39e6b2e6d44cc94157b0258e5bedf823c90ecb90","tarball":"https://registry.npmjs.org/@damianhodgkiss/helpscout-docs-mcp/-/helpscout-docs-mcp-1.0.0.tgz","fileCount":6,"integrity":"sha512-G+jl9RWfH44zIH9QUv31zijze/3uHbGv48iHN4Sxw/6veoQoDPY18iB6LaJxbZZUb9h5YC3iJnubRVFf4ND2gg==","signatures":[{"sig":"MEQCIGFVCW/1QsxFcNDzGkej0CHG86ILal0o2qXBHujHU/8QAiBDmnZhT8PVSoe/laLQ0D/Y2osqarWHXuVRz35/Qj4rfw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":50792},"type":"module","engines":{"node":">=18.0.0"},"gitHead":"cf6b65bbcedd76c60a48e006739d607fe2582518","scripts":{"lint":"eslint src --ext .ts","build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"damianhodgkiss","email":"damian@hodgkiss.id.au"},"_npmVersion":"10.2.4","description":"Model Context Protocol server for Help Scout Docs API","directories":{},"_nodeVersion":"20.11.1","dependencies":{"@modelcontextprotocol/sdk":"^1.0.4","@damianhodgkiss/helpscout-docs-api":"^1.0.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/helpscout-docs-mcp_1.0.0_1763505883659_0.23786984408799605","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@damianhodgkiss/helpscout-docs-mcp","version":"1.1.0","description":"Model Context Protocol server for Help Scout Docs API","type":"module","bin":{"helpscout-docs-mcp":"dist/index.js"},"scripts":{"build":"tsc","lint":"eslint src --ext .ts","prepublishOnly":"npm run build"},"keywords":["helpscout","docs","mcp","model-context-protocol","claude"],"author":{"name":"Damian Hodgkiss"},"license":"MIT","engines":{"node":">=18.0.0"},"dependencies":{"@damianhodgkiss/helpscout-docs-api":"^1.0.0","@modelcontextprotocol/sdk":"^1.0.4"},"_id":"@damianhodgkiss/helpscout-docs-mcp@1.1.0","gitHead":"d75207c5971a7ecfb370c53b9fffdec48b586809","_nodeVersion":"20.11.1","_npmVersion":"10.2.4","dist":{"integrity":"sha512-cTpexYmO0v72eJNdLUsEkQhacuChJQL+2AwE/IL0seDf+4lAwh0M3d8OQqGF8CWH7j/Ff3W918ZaV9QpKxarhg==","shasum":"42312229e76b2d30d498aa41264ed03edbeaf8a2","tarball":"https://registry.npmjs.org/@damianhodgkiss/helpscout-docs-mcp/-/helpscout-docs-mcp-1.1.0.tgz","fileCount":6,"unpackedSize":56084,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBDNOb9lyJGnGpk69W44HkO2p2aPwTM3jF/mNXV2/LqMAiEAnaoZ70to3ue7+/RsAuCbHN8OyKNEKrBK6hueSdyBLMU="}]},"_npmUser":{"name":"damianhodgkiss","email":"damian@hodgkiss.id.au"},"directories":{},"maintainers":[{"name":"damianhodgkiss","email":"damian@hodgkiss.id.au"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/helpscout-docs-mcp_1.1.0_1763510281519_0.2960483750940561"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-18T22:44:43.604Z","modified":"2025-11-18T23:58:01.910Z","1.0.0":"2025-11-18T22:44:43.941Z","1.1.0":"2025-11-18T23:58:01.725Z"},"author":{"name":"Damian Hodgkiss"},"license":"MIT","keywords":["helpscout","docs","mcp","model-context-protocol","claude"],"description":"Model Context Protocol server for Help Scout Docs API","maintainers":[{"name":"damianhodgkiss","email":"damian@hodgkiss.id.au"}],"readme":"# @damianhodgkiss/helpscout-docs-mcp\n\nModel Context Protocol (MCP) server for managing Help Scout documentation through Claude Code or any MCP-compatible client.\n\n## Features\n\n- 🤖 **24 comprehensive tools** covering the full Help Scout Docs API\n- 🔗 **Native Claude Code integration**\n- 📝 **Complete CRUD operations** for Articles, Categories, Collections, and Sites\n- 💾 **Draft management** - Save and manage article drafts\n- 🔍 **Advanced filtering** - Search, sort, and filter across all resources\n- 🔒 **Type-safe** - Built with TypeScript for reliability\n- 🚀 **Zero HTTP dependencies** - Uses native fetch\n\n## Prerequisites\n\n- Node.js 18.0.0 or higher (for native fetch support)\n- Help Scout account with API access\n- Help Scout API key ([Get your API key](https://secure.helpscout.net/settings/api/))\n- Claude Code or another MCP-compatible client\n\n## Installation\n\n### From Source\n\n1. Navigate to the project directory:\n```bash\ncd helpscout-docs-api\n```\n\n2. Install dependencies:\n```bash\nnpm install\n```\n\n3. Build the MCP server:\n```bash\nnpm run build\n```\n\n## Configuration\n\n### 1. Get Your API Key\n\nGet your Help Scout API key from:\nhttps://secure.helpscout.net/settings/api/\n\n### 2. Configure Claude Code\n\n#### Using the CLI (Recommended)\n\n```bash\nclaude mcp add --transport stdio helpscout-docs \\\n  -e HELPSCOUT_API_KEY=your-api-key-here \\\n  -e HELPSCOUT_SITE_ID=your-site-id-here \\\n  -- node /absolute/path/to/helpscout-docs-api/packages/helpscout-docs-mcp/dist/index.js\n```\n\n**Important:** Replace `/absolute/path/to/helpscout-docs-api` with the actual path to this project on your system.\n\n#### Manual Configuration\n\nAdd this server to your Claude Code MCP settings file:\n\n**macOS/Linux:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n**Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"helpscout-docs\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/helpscout-docs-api/packages/helpscout-docs-mcp/dist/index.js\"],\n      \"env\": {\n        \"HELPSCOUT_API_KEY\": \"your-api-key-here\",\n        \"HELPSCOUT_SITE_ID\": \"your-site-id-here\"\n      }\n    }\n  }\n}\n```\n\n**Environment Variables:**\n- `HELPSCOUT_API_KEY` (required) - Your Help Scout API key\n- `HELPSCOUT_SITE_ID` (optional) - Default site ID to filter collections and articles. When set, operations like `list_collections`, `search_articles`, and `create_collection` will automatically use this site ID unless a different `siteId` is explicitly provided in the operation parameters. If not set, operations return results from all sites.\n\n### 3. Restart Claude Code\n\nRestart Claude Code to load the new MCP server. You should see the Help Scout Docs tools available in Claude Code.\n\n## Available Tools\n\n### Articles (8 tools)\n\n#### `list_articles`\n\nList articles in a collection or category.\n\n**Parameters:**\n- `collectionId` (string) - Collection ID (required if categoryId not provided)\n- `categoryId` (string) - Category ID (required if collectionId not provided)\n- `page` (number) - Page number (default: 1)\n- `status` (string) - Filter by status: `all`, `published`, `notpublished`\n- `sort` (string) - Sort by: `number`, `status`, `name`, `popularity`, `createdAt`, `updatedAt`\n- `order` (string) - Sort order: `asc`, `desc`\n- `pageSize` (number) - Results per page (default: 50, max: 100)\n\n#### `search_articles`\n\nSearch for articles using a query string.\n\n**Parameters:**\n- `query` (string, required) - Search query\n- `page` (number) - Page number\n- `collectionId` (string) - Filter to specific collection\n- `siteId` (string) - Filter to specific site (defaults to `HELPSCOUT_SITE_ID` env var if set)\n- `status` (string) - Filter by status\n- `visibility` (string) - Filter by visibility: `all`, `public`, `private`\n\n#### `get_article`\n\nGet complete article details including full text content.\n\n**Parameters:**\n- `articleIdOrNumber` (string/number, required) - Article ID or number\n- `draft` (boolean) - Get draft version if available (default: false)\n\n#### `create_article`\n\nCreate a new article.\n\n**Parameters:**\n- `collectionId` (string, required) - Collection ID\n- `name` (string, required) - Article title (must be unique within collection)\n- `text` (string, required) - Article content (HTML or plain text)\n- `status` (string) - Publication status: `published`, `notpublished`\n- `slug` (string) - SEO-friendly URL slug\n- `categories` (array) - Array of category IDs\n- `related` (array) - Array of related article IDs\n- `keywords` (array) - Array of search keywords\n- `reload` (boolean) - Return created article in response\n\n#### `update_article`\n\nUpdate an existing article. Only specified fields are updated.\n\n**Parameters:**\n- `articleId` (string, required) - Article ID\n- `status` (string) - Publication status\n- `slug` (string) - SEO-friendly URL slug\n- `name` (string) - Article title\n- `text` (string) - Article content\n- `categories` (array/null) - Category IDs (null to remove all)\n- `related` (array/null) - Related article IDs (null to remove all)\n- `keywords` (array/null) - Search keywords (null to remove all)\n- `reload` (boolean) - Return updated article in response\n\n#### `delete_article`\n\nDelete an article permanently.\n\n**Parameters:**\n- `articleId` (string, required) - Article ID\n\n#### `save_article_draft`\n\nSave a draft version of an article without affecting the published version.\n\n**Parameters:**\n- `articleId` (string, required) - Article ID\n- `text` (string, required) - Draft content\n\n#### `delete_article_draft`\n\nDelete the draft version of an article.\n\n**Parameters:**\n- `articleId` (string, required) - Article ID\n\n### Categories (5 tools)\n\n#### `list_categories`\n\nList all categories in a collection.\n\n**Parameters:**\n- `collectionId` (string, required) - Collection ID\n- `page` (number) - Page number\n- `sort` (string) - Sort by: `number`, `order`, `name`, `articleCount`, `createdAt`, `updatedAt`\n- `order` (string) - Sort order: `asc`, `desc`\n\n#### `get_category`\n\nGet category details.\n\n**Parameters:**\n- `categoryIdOrNumber` (string/number, required) - Category ID or number\n\n#### `create_category`\n\nCreate a new category.\n\n**Parameters:**\n- `collectionId` (string, required) - Collection ID\n- `name` (string, required) - Category name (must be unique within collection)\n- `slug` (string) - SEO-friendly URL slug\n- `visibility` (string) - Visibility: `public`, `private`\n- `order` (number) - Display order\n- `defaultSort` (string) - Default article sort: `popularity`, `name`\n- `reload` (boolean) - Return created category in response\n\n#### `update_category`\n\nUpdate an existing category.\n\n**Parameters:**\n- `categoryId` (string, required) - Category ID\n- `name` (string, required) - Category name\n- `slug` (string) - SEO-friendly URL slug\n- `visibility` (string) - Visibility: `public`, `private`\n- `order` (number) - Display order\n- `defaultSort` (string) - Default article sort: `popularity`, `name`\n- `reload` (boolean) - Return updated category in response\n\n#### `delete_category`\n\nDelete a category.\n\n**Parameters:**\n- `categoryId` (string, required) - Category ID\n\n### Collections (5 tools)\n\n#### `list_collections`\n\nList all collections.\n\n**Parameters:**\n- `page` (number) - Page number\n- `siteId` (string) - Filter to specific site (defaults to `HELPSCOUT_SITE_ID` env var if set)\n- `visibility` (string) - Filter by visibility: `all`, `public`, `private`\n- `sort` (string) - Sort by: `number`, `visibility`, `order`, `name`, `createdAt`, `updatedAt`\n- `order` (string) - Sort order: `asc`, `desc`\n\n#### `get_collection`\n\nGet collection details.\n\n**Parameters:**\n- `collectionIdOrNumber` (string/number, required) - Collection ID or number\n\n#### `create_collection`\n\nCreate a new collection.\n\n**Parameters:**\n- `siteId` (string) - Site ID (defaults to `HELPSCOUT_SITE_ID` env var if set, required otherwise)\n- `name` (string, required) - Collection name (must be unique for account)\n- `visibility` (string) - Visibility: `public`, `private`\n- `order` (number) - Display order\n- `description` (string) - Description (max 45 characters)\n- `reload` (boolean) - Return created collection in response\n\n#### `update_collection`\n\nUpdate an existing collection.\n\n**Parameters:**\n- `collectionId` (string, required) - Collection ID\n- `name` (string, required) - Collection name\n- `visibility` (string) - Visibility: `public`, `private`\n- `order` (number) - Display order\n- `description` (string) - Description (max 45 characters)\n- `siteId` (string) - Move to different site\n- `reload` (boolean) - Return updated collection in response\n\n#### `delete_collection`\n\nDelete a collection.\n\n**Parameters:**\n- `collectionId` (string, required) - Collection ID\n\n### Assets (1 tool)\n\n#### `create_article_asset`\n\nUpload an image or attachment to an article.\n\n**Parameters:**\n- `articleId` (string, required) - Article ID\n- `assetType` (string, required) - Asset type: `image`, `attachment`\n- `file` (string, required) - Base64-encoded file content\n- `fileName` (string) - File name\n\n### Sites (3 tools)\n\n#### `list_sites`\n\nList all sites.\n\n**Parameters:**\n- `page` (number) - Page number (default: 1)\n\n#### `get_site`\n\nGet a single site by ID.\n\n**Parameters:**\n- `siteId` (string, required) - Site ID\n\n#### `update_site`\n\nUpdate an existing site.\n\n**Parameters:**\n- `siteId` (string, required) - Site ID\n- `subDomain` (string) - Subdomain (must be unique if provided)\n- `title` (string) - Site title\n- `status` (string) - Site status\n- `cname` (string) - Custom domain\n- `hasPublicSite` (boolean) - Public availability\n- `logoUrl` (string) - Logo URL\n- `logoWidth` (number) - Logo width in pixels\n- `logoHeight` (number) - Logo height in pixels\n- `favIconUrl` (string) - Favicon URL\n- `touchIconUrl` (string) - Touch icon URL\n- `homeUrl` (string) - Company website URL\n- `homeLinkText` (string) - Navigation link text\n- `bgColor` (string) - Background color (hex value)\n- `description` (string) - Meta description\n- `hasContactForm` (boolean) - Contact form display flag\n- `mailboxId` (number) - Help Scout mailbox ID\n- `contactEmail` (string) - Contact form email\n- `styleSheetUrl` (string) - Custom stylesheet URL\n- `headerCode` (string) - Custom HTML/JavaScript code\n- `reload` (boolean) - Return updated site in response\n\n## Usage Examples\n\nOnce configured in Claude Code, you can ask Claude to help you with your Help Scout documentation:\n\n**Example prompts:**\n\n- \"List all articles in collection abc123\"\n- \"Create a new article called 'Getting Started' in collection abc123\"\n- \"Search for articles about authentication\"\n- \"Update article xyz789 to change the title to 'Quick Start Guide'\"\n- \"Delete the draft for article xyz789\"\n- \"Create a new category called 'Tutorials' in collection abc123\"\n- \"List all collections\"\n\n## Error Handling\n\nThe MCP server provides clear error messages for common API errors:\n\n- **400** - Bad Request: The request was not formatted correctly\n- **401** - Unauthorized: Invalid API Key\n- **402** - Payment Required: API key suspended\n- **403** - Forbidden: Access denied\n- **404** - Not Found: Resource not found\n- **405** - Method Not Allowed: Invalid HTTP method\n- **500** - Internal Server Error: Application or server error\n- **503** - Service Unavailable: Temporary service disruption\n\n## Rate Limiting\n\nHelp Scout Docs API has rate limits based on the number of sites:\n- 1 site: 2,000 requests per 10 minutes\n- 2 sites: 3,000 requests per 10 minutes\n- 3+ sites: 4,000 requests per 10 minutes\n\n## Development\n\n### Build\n\n```bash\nnpm run build\n```\n\n### Lint\n\n```bash\nnpm run lint\n```\n\n### Project Structure\n\n```\npackages/helpscout-docs-mcp/\n├── src/\n│   └── index.ts          # MCP server implementation\n├── dist/                 # Compiled JavaScript (generated)\n├── package.json\n└── tsconfig.json\n```\n\n## Troubleshooting\n\n### MCP Server Not Appearing in Claude Code\n\n1. Check that the path in `claude_desktop_config.json` is absolute and correct\n2. Verify that `HELPSCOUT_API_KEY` is set in the config\n3. Restart Claude Code completely\n4. Check the Claude Code logs for errors\n\n### API Key Errors\n\n1. Verify your API key is correct\n2. Check that your API key has the necessary permissions\n3. Ensure your Help Scout account is active\n\n### Build Errors\n\n1. Make sure you're using Node.js 18.0.0 or higher\n2. Delete `node_modules` and `dist` folders, then run `npm install` and `npm run build`\n\n## Resources\n\n- [Help Scout Docs API Documentation](https://developer.helpscout.com/docs-api/)\n- [Model Context Protocol](https://modelcontextprotocol.io/)\n- [Claude Code Documentation](https://claude.ai/docs)\n\n## License\n\nMIT\n\n## Support\n\n- **MCP Server Issues**: Open an issue in this repository\n- **Help Scout API Issues**: Contact [Help Scout Support](https://www.helpscout.com/support/)\n- **MCP Protocol Issues**: Visit [modelcontextprotocol.io](https://modelcontextprotocol.io/)\n","readmeFilename":"README.md"}