@helmdesk/mcp 0.1.0

package/README.md

@@ -0,0 +1,90 @@
+# @helmdesk/mcp
+
+MCP (Model Context Protocol) server for [Helmdesk](https://helmdesk.dev) — let AI agents manage support tickets, send emails, and search your knowledge base.
+
+## Quick Start
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "helmdesk": {
+      "command": "npx",
+      "args": ["-y", "@helmdesk/mcp"],
+      "env": {
+        "HELMDESK_API_KEY": "sk_live_your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add helmdesk -- npx -y @helmdesk/mcp
+```
+
+Then set the environment variable:
+```bash
+export HELMDESK_API_KEY=sk_live_your_api_key_here
+```
+
+### Direct Usage
+
+```bash
+HELMDESK_API_KEY=sk_live_xxx npx @helmdesk/mcp
+```
+
+## Available Tools
+
+| Tool | Description |
+|---|---|
+| `list_tickets` | List tickets with filters (status, priority, search, pagination) |
+| `get_ticket` | Get full ticket details with message thread |
+| `create_ticket` | Create a new support ticket |
+| `update_ticket` | Update ticket status, priority, or category |
+| `reply_to_ticket` | Send a staff reply to a ticket |
+| `send_email` | Send a transactional email using a template |
+| `preview_email` | Preview a rendered email template |
+| `get_template_schema` | Get the variable schema for an email template |
+| `search_articles` | Search the knowledge base |
+
+## Available Resources
+
+| Resource | URI | Description |
+|---|---|---|
+| Open tickets | `helmdesk://tickets/open` | All tickets with status new or open |
+| Pending tickets | `helmdesk://tickets/pending` | Tickets waiting for staff response |
+| Knowledge base | `helmdesk://articles` | All published articles |
+
+## Example Prompts
+
+Once connected, you can ask your AI agent:
+
+- "Show me all open tickets"
+- "Read ticket #42 and draft a reply"
+- "Search the knowledge base for articles about file uploads"
+- "Create a ticket for user@example.com about a billing issue"
+- "Resolve ticket abc-123 and send a follow-up email"
+- "Check my pending tickets and draft replies for any waiting more than 24 hours"
+
+## Configuration
+
+| Environment Variable | Required | Description |
+|---|---|---|
+| `HELMDESK_API_KEY` | Yes | Your Helmdesk API key (starts with `sk_live_`) |
+| `HELMDESK_BASE_URL` | No | Custom API base URL (default: `https://helmdesk.dev`) |
+
+## Getting an API Key
+
+1. Sign in at [helmdesk.dev](https://helmdesk.dev)
+2. Go to your project → **API Keys**
+3. Click **Create API Key** and copy the key
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+export { createHelmdeskMcpServer } from './server.js';
+export type { HelmdeskMcpOptions } from './server.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAMA,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AACrD,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createHelmdeskMcpServer } from './server.js';
+// Re-export for programmatic use
+export { createHelmdeskMcpServer } from './server.js';
+async function main() {
+    const apiKey = process.env.HELMDESK_API_KEY;
+    if (!apiKey) {
+        console.error('Error: HELMDESK_API_KEY environment variable is required.');
+        console.error('');
+        console.error('Usage:');
+        console.error('  HELMDESK_API_KEY=sk_live_xxx npx @helmdesk/mcp');
+        console.error('');
+        console.error('Or in Claude Desktop config (claude_desktop_config.json):');
+        console.error('  {');
+        console.error('    "mcpServers": {');
+        console.error('      "helmdesk": {');
+        console.error('        "command": "npx",');
+        console.error('        "args": ["@helmdesk/mcp"],');
+        console.error('        "env": { "HELMDESK_API_KEY": "sk_live_xxx" }');
+        console.error('      }');
+        console.error('    }');
+        console.error('  }');
+        process.exit(1);
+    }
+    const baseUrl = process.env.HELMDESK_BASE_URL;
+    const server = createHelmdeskMcpServer({ apiKey, baseUrl });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAA;AAChF,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AAErD,iCAAiC;AACjC,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AAGrD,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAA;IAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,CAAC,KAAK,CAAC,2DAA2D,CAAC,CAAA;QAC1E,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;QACjB,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAA;QACvB,OAAO,CAAC,KAAK,CAAC,kDAAkD,CAAC,CAAA;QACjE,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;QACjB,OAAO,CAAC,KAAK,CAAC,2DAA2D,CAAC,CAAA;QAC1E,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;QACpB,OAAO,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAA;QACpC,OAAO,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAA;QACpC,OAAO,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAA;QAC1C,OAAO,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAA;QACnD,OAAO,CAAC,KAAK,CAAC,sDAAsD,CAAC,CAAA;QACrE,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;QACxB,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;QACtB,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;QACpB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACjB,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAA;IAE7C,MAAM,MAAM,GAAG,uBAAuB,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAA;IAC3D,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAA;IAC5C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;AACjC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAA;IACpC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AACjB,CAAC,CAAC,CAAA"}

package/dist/resources/articles.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { HelmdeskClient } from '@helmdesk/sdk';
+export declare function registerArticleResources(server: McpServer, getClient: () => HelmdeskClient): void;
+//# sourceMappingURL=articles.d.ts.map

package/dist/resources/articles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"articles.d.ts","sourceRoot":"","sources":["../../src/resources/articles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAEnD,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,cAAc,QAoB1F"}

package/dist/resources/articles.js

@@ -0,0 +1,17 @@
+export function registerArticleResources(server, getClient) {
+    server.resource('knowledge-base', 'helmdesk://articles', {
+        description: 'All published knowledge base articles',
+        mimeType: 'application/json',
+    }, async () => {
+        const client = getClient();
+        const result = await client.articles.search({ limit: 100 });
+        return {
+            contents: [{
+                    uri: 'helmdesk://articles',
+                    mimeType: 'application/json',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+}
+//# sourceMappingURL=articles.js.map

package/dist/resources/articles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"articles.js","sourceRoot":"","sources":["../../src/resources/articles.ts"],"names":[],"mappings":"AAGA,MAAM,UAAU,wBAAwB,CAAC,MAAiB,EAAE,SAA+B;IACzF,MAAM,CAAC,QAAQ,CACb,gBAAgB,EAChB,qBAAqB,EACrB;QACE,WAAW,EAAE,uCAAuC;QACpD,QAAQ,EAAE,kBAAkB;KAC7B,EACD,KAAK,IAAI,EAAE;QACT,MAAM,MAAM,GAAG,SAAS,EAAE,CAAA;QAC1B,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAA;QAC3D,OAAO;YACL,QAAQ,EAAE,CAAC;oBACT,GAAG,EAAE,qBAAqB;oBAC1B,QAAQ,EAAE,kBAAkB;oBAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;iBACtC,CAAC;SACH,CAAA;IACH,CAAC,CACF,CAAA;AACH,CAAC"}

package/dist/resources/tickets.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { HelmdeskClient } from '@helmdesk/sdk';
+export declare function registerTicketResources(server: McpServer, getClient: () => HelmdeskClient): void;
+//# sourceMappingURL=tickets.d.ts.map

package/dist/resources/tickets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tickets.d.ts","sourceRoot":"","sources":["../../src/resources/tickets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAEnD,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,cAAc,QAiDzF"}

package/dist/resources/tickets.js

@@ -0,0 +1,39 @@
+export function registerTicketResources(server, getClient) {
+    // List of open tickets as a resource
+    server.resource('open-tickets', 'helmdesk://tickets/open', {
+        description: 'Currently open support tickets (status: new or open)',
+        mimeType: 'application/json',
+    }, async () => {
+        const client = getClient();
+        const newTickets = await client.tickets.list({ status: 'new', limit: 50 });
+        const openTickets = await client.tickets.list({ status: 'open', limit: 50 });
+        const allOpen = [...newTickets.tickets, ...openTickets.tickets]
+            .sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+        return {
+            contents: [{
+                    uri: 'helmdesk://tickets/open',
+                    mimeType: 'application/json',
+                    text: JSON.stringify({
+                        total: allOpen.length,
+                        tickets: allOpen,
+                    }, null, 2),
+                }],
+        };
+    });
+    // List of pending tickets (waiting for staff response)
+    server.resource('pending-tickets', 'helmdesk://tickets/pending', {
+        description: 'Tickets waiting for staff response (status: pending)',
+        mimeType: 'application/json',
+    }, async () => {
+        const client = getClient();
+        const result = await client.tickets.list({ status: 'pending', limit: 50 });
+        return {
+            contents: [{
+                    uri: 'helmdesk://tickets/pending',
+                    mimeType: 'application/json',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+}
+//# sourceMappingURL=tickets.js.map

package/dist/resources/tickets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tickets.js","sourceRoot":"","sources":["../../src/resources/tickets.ts"],"names":[],"mappings":"AAGA,MAAM,UAAU,uBAAuB,CAAC,MAAiB,EAAE,SAA+B;IACxF,qCAAqC;IACrC,MAAM,CAAC,QAAQ,CACb,cAAc,EACd,yBAAyB,EACzB;QACE,WAAW,EAAE,sDAAsD;QACnE,QAAQ,EAAE,kBAAkB;KAC7B,EACD,KAAK,IAAI,EAAE;QACT,MAAM,MAAM,GAAG,SAAS,EAAE,CAAA;QAC1B,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAA;QAC1E,MAAM,WAAW,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAA;QAC5E,MAAM,OAAO,GAAG,CAAC,GAAG,UAAU,CAAC,OAAO,EAAE,GAAG,WAAW,CAAC,OAAO,CAAC;aAC5D,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,CAAA;QAEpF,OAAO;YACL,QAAQ,EAAE,CAAC;oBACT,GAAG,EAAE,yBAAyB;oBAC9B,QAAQ,EAAE,kBAAkB;oBAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;wBACnB,KAAK,EAAE,OAAO,CAAC,MAAM;wBACrB,OAAO,EAAE,OAAO;qBACjB,EAAE,IAAI,EAAE,CAAC,CAAC;iBACZ,CAAC;SACH,CAAA;IACH,CAAC,CACF,CAAA;IAED,uDAAuD;IACvD,MAAM,CAAC,QAAQ,CACb,iBAAiB,EACjB,4BAA4B,EAC5B;QACE,WAAW,EAAE,sDAAsD;QACnE,QAAQ,EAAE,kBAAkB;KAC7B,EACD,KAAK,IAAI,EAAE;QACT,MAAM,MAAM,GAAG,SAAS,EAAE,CAAA;QAC1B,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAA;QAC1E,OAAO;YACL,QAAQ,EAAE,CAAC;oBACT,GAAG,EAAE,4BAA4B;oBACjC,QAAQ,EAAE,kBAAkB;oBAC5B,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;iBACtC,CAAC;SACH,CAAA;IACH,CAAC,CACF,CAAA;AACH,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,7 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export interface HelmdeskMcpOptions {
+    apiKey: string;
+    baseUrl?: string;
+}
+export declare function createHelmdeskMcpServer(options: HelmdeskMcpOptions): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAQnE,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,kBAAkB,GAAG,SAAS,CAuB9E"}

package/dist/server.js

@@ -0,0 +1,27 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { HelmdeskClient } from '@helmdesk/sdk';
+import { registerTicketTools } from './tools/tickets.js';
+import { registerEmailTools } from './tools/emails.js';
+import { registerArticleTools } from './tools/articles.js';
+import { registerTicketResources } from './resources/tickets.js';
+import { registerArticleResources } from './resources/articles.js';
+export function createHelmdeskMcpServer(options) {
+    const server = new McpServer({
+        name: 'Helmdesk',
+        version: '0.1.0',
+    });
+    const client = new HelmdeskClient({
+        apiKey: options.apiKey,
+        baseUrl: options.baseUrl,
+    });
+    const getClient = () => client;
+    // Register all tools
+    registerTicketTools(server, getClient);
+    registerEmailTools(server, getClient);
+    registerArticleTools(server, getClient);
+    // Register all resources
+    registerTicketResources(server, getClient);
+    registerArticleResources(server, getClient);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC1D,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAA;AAChE,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAA;AAOlE,MAAM,UAAU,uBAAuB,CAAC,OAA2B;IACjE,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,OAAO;KACjB,CAAC,CAAA;IAEF,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC;QAChC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC,CAAA;IAEF,MAAM,SAAS,GAAG,GAAG,EAAE,CAAC,MAAM,CAAA;IAE9B,qBAAqB;IACrB,mBAAmB,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;IACtC,kBAAkB,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;IACrC,oBAAoB,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;IAEvC,yBAAyB;IACzB,uBAAuB,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;IAC1C,wBAAwB,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;IAE3C,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/tools/articles.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { HelmdeskClient } from '@helmdesk/sdk';
+export declare function registerArticleTools(server: McpServer, getClient: () => HelmdeskClient): void;
+//# sourceMappingURL=articles.d.ts.map

package/dist/tools/articles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"articles.d.ts","sourceRoot":"","sources":["../../src/tools/articles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAEnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAEnD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,cAAc,QA0BtF"}

package/dist/tools/articles.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+export function registerArticleTools(server, getClient) {
+    server.tool('search_articles', 'Search the knowledge base for articles matching a query. Use this to find relevant help articles when drafting ticket replies.', {
+        query: z.string().optional().describe('Search query (searches title, body, and excerpt)'),
+        category: z.string().optional().describe('Filter by category name'),
+        page: z.number().optional().describe('Page number (default: 1)'),
+        limit: z.number().optional().describe('Results per page (default: 10)'),
+    }, async ({ query, category, page, limit }) => {
+        const client = getClient();
+        const result = await client.articles.search({
+            q: query,
+            category,
+            page,
+            limit,
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+}
+//# sourceMappingURL=articles.js.map

package/dist/tools/articles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"articles.js","sourceRoot":"","sources":["../../src/tools/articles.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,MAAM,UAAU,oBAAoB,CAAC,MAAiB,EAAE,SAA+B;IACrF,MAAM,CAAC,IAAI,CACT,iBAAiB,EACjB,gIAAgI,EAChI;QACE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kDAAkD,CAAC;QACzF,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,yBAAyB,CAAC;QACnE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,0BAA0B,CAAC;QAChE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gCAAgC,CAAC;KACxE,EACD,KAAK,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE;QACzC,MAAM,MAAM,GAAG,SAAS,EAAE,CAAA;QAC1B,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;YAC1C,CAAC,EAAE,KAAK;YACR,QAAQ;YACR,IAAI;YACJ,KAAK;SACN,CAAC,CAAA;QACF,OAAO;YACL,OAAO,EAAE,CAAC;oBACR,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;iBACtC,CAAC;SACH,CAAA;IACH,CAAC,CACF,CAAA;AACH,CAAC"}

package/dist/tools/emails.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { HelmdeskClient } from '@helmdesk/sdk';
+export declare function registerEmailTools(server: McpServer, getClient: () => HelmdeskClient): void;
+//# sourceMappingURL=emails.d.ts.map

package/dist/tools/emails.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emails.d.ts","sourceRoot":"","sources":["../../src/tools/emails.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAEnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAEnD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,cAAc,QAgEpF"}

package/dist/tools/emails.js

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+export function registerEmailTools(server, getClient) {
+    server.tool('send_email', 'Send a transactional email using a template. The template must exist in the project. Use preview_email first to verify the output.', {
+        templateKey: z.string().describe('Template key (e.g. "welcome", "password-reset"). Use @account/ prefix for shared templates.'),
+        to_email: z.string().email().describe('Recipient email address'),
+        to_name: z.string().optional().describe('Recipient display name'),
+        variables: z.record(z.unknown()).optional()
+            .describe('Template variables as key-value pairs (e.g. { "name": "Jane", "resetUrl": "https://..." })'),
+    }, async ({ templateKey, to_email, to_name, variables }) => {
+        const client = getClient();
+        const result = await client.emails.send({
+            templateKey,
+            to: { email: to_email, name: to_name },
+            variables,
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.tool('preview_email', 'Preview a rendered email template without sending. Returns the rendered subject and HTML body. Useful for verifying template output before sending.', {
+        templateKey: z.string().describe('Template key to preview'),
+        variables: z.record(z.unknown()).optional()
+            .describe('Template variables to render with'),
+    }, async ({ templateKey, variables }) => {
+        const client = getClient();
+        const result = await client.emails.preview({ templateKey, variables });
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Subject: ${result.subject}\n\n${result.html}`,
+                }],
+        };
+    });
+    server.tool('get_template_schema', 'Get the variable schema for an email template. Returns the list of variables, their types, and whether they are required.', {
+        templateKey: z.string().describe('Template key to get schema for'),
+    }, async ({ templateKey }) => {
+        const client = getClient();
+        const schema = await client.emails.getTemplateSchema(templateKey);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(schema, null, 2),
+                }],
+        };
+    });
+}
+//# sourceMappingURL=emails.js.map

package/dist/tools/emails.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emails.js","sourceRoot":"","sources":["../../src/tools/emails.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,MAAM,UAAU,kBAAkB,CAAC,MAAiB,EAAE,SAA+B;IACnF,MAAM,CAAC,IAAI,CACT,YAAY,EACZ,oIAAoI,EACpI;QACE,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,6FAA6F,CAAC;QAC/H,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,QAAQ,CAAC,yBAAyB,CAAC;QAChE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,wBAAwB,CAAC;QACjE,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;aACxC,QAAQ,CAAC,4FAA4F,CAAC;KAC1G,EACD,KAAK,EAAE,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,EAAE,EAAE;QACtD,MAAM,MAAM,GAAG,SAAS,EAAE,CAAA;QAC1B,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;YACtC,WAAW;YACX,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE;YACtC,SAAS;SACV,CAAC,CAAA;QACF,OAAO;YACL,OAAO,EAAE,CAAC;oBACR,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;iBACtC,CAAC;SACH,CAAA;IACH,CAAC,CACF,CAAA;IAED,MAAM,CAAC,IAAI,CACT,eAAe,EACf,qJAAqJ,EACrJ;QACE,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,yBAAyB,CAAC;QAC3D,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;aACxC,QAAQ,CAAC,mCAAmC,CAAC;KACjD,EACD,KAAK,EAAE,EAAE,WAAW,EAAE,SAAS,EAAE,EAAE,EAAE;QACnC,MAAM,MAAM,GAAG,SAAS,EAAE,CAAA;QAC1B,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC,CAAA;QACtE,OAAO;YACL,OAAO,EAAE,CAAC;oBACR,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,YAAY,MAAM,CAAC,OAAO,OAAO,MAAM,CAAC,IAAI,EAAE;iBACrD,CAAC;SACH,CAAA;IACH,CAAC,CACF,CAAA;IAED,MAAM,CAAC,IAAI,CACT,qBAAqB,EACrB,2HAA2H,EAC3H;QACE,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gCAAgC,CAAC;KACnE,EACD,KAAK,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE;QACxB,MAAM,MAAM,GAAG,SAAS,EAAE,CAAA;QAC1B,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAA;QACjE,OAAO;YACL,OAAO,EAAE,CAAC;oBACR,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;iBACtC,CAAC;SACH,CAAA;IACH,CAAC,CACF,CAAA;AACH,CAAC"}

package/dist/tools/tickets.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { HelmdeskClient } from '@helmdesk/sdk';
+export declare function registerTicketTools(server: McpServer, getClient: () => HelmdeskClient): void;
+//# sourceMappingURL=tickets.d.ts.map

package/dist/tools/tickets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tickets.d.ts","sourceRoot":"","sources":["../../src/tools/tickets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAEnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAEnD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,cAAc,QAqHrF"}

package/dist/tools/tickets.js

@@ -0,0 +1,91 @@
+import { z } from 'zod';
+export function registerTicketTools(server, getClient) {
+    server.tool('list_tickets', 'List support tickets with optional filters. Returns ticket ID, number, subject, status, priority, customer email, and timestamps.', {
+        status: z.enum(['new', 'open', 'pending', 'resolved', 'closed']).optional()
+            .describe('Filter by ticket status'),
+        priority: z.enum(['low', 'medium', 'high', 'urgent']).optional()
+            .describe('Filter by priority level'),
+        search: z.string().optional()
+            .describe('Search tickets by subject or customer email'),
+        page: z.number().optional().describe('Page number (default: 1)'),
+        limit: z.number().optional().describe('Results per page (default: 20, max: 100)'),
+    }, async (params) => {
+        const client = getClient();
+        const result = await client.tickets.list({
+            status: params.status,
+            priority: params.priority,
+            search: params.search,
+            page: params.page,
+            limit: params.limit,
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    });
+    server.tool('get_ticket', 'Get full ticket details including the complete message thread, tags, and customer info. Use this to read a specific ticket before replying.', {
+        ticketId: z.string().describe('The ticket ID (UUID)'),
+    }, async ({ ticketId }) => {
+        const client = getClient();
+        const ticket = await client.tickets.get(ticketId);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(ticket, null, 2),
+                }],
+        };
+    });
+    server.tool('create_ticket', 'Create a new support ticket on behalf of a customer. Requires subject, body, and customer email.', {
+        subject: z.string().describe('Ticket subject line'),
+        body: z.string().describe('Ticket body / initial message'),
+        customerEmail: z.string().email().describe('Customer email address'),
+        customerName: z.string().optional().describe('Customer display name'),
+        priority: z.enum(['low', 'medium', 'high', 'urgent']).optional()
+            .describe('Priority level (default: medium)'),
+        category: z.enum(['bug', 'feature_request', 'billing', 'howto', 'other']).optional()
+            .describe('Ticket category'),
+    }, async (params) => {
+        const client = getClient();
+        const ticket = await client.tickets.create(params);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(ticket, null, 2),
+                }],
+        };
+    });
+    server.tool('update_ticket', 'Update a ticket\'s status, priority, or category. Use this to resolve, close, or re-prioritize tickets.', {
+        ticketId: z.string().describe('The ticket ID to update'),
+        status: z.enum(['new', 'open', 'pending', 'resolved', 'closed']).optional()
+            .describe('New status'),
+        priority: z.enum(['low', 'medium', 'high', 'urgent']).optional()
+            .describe('New priority'),
+        category: z.enum(['bug', 'feature_request', 'billing', 'howto', 'other']).optional()
+            .describe('New category'),
+    }, async ({ ticketId, ...updates }) => {
+        const client = getClient();
+        const ticket = await client.tickets.update(ticketId, updates);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(ticket, null, 2),
+                }],
+        };
+    });
+    server.tool('reply_to_ticket', 'Add a staff reply to a ticket. This sends the reply to the customer and updates the ticket status.', {
+        ticketId: z.string().describe('The ticket ID to reply to'),
+        body: z.string().describe('Reply message body'),
+    }, async ({ ticketId, body }) => {
+        const client = getClient();
+        const message = await client.tickets.addMessage(ticketId, { body });
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(message, null, 2),
+                }],
+        };
+    });
+}
+//# sourceMappingURL=tickets.js.map

package/dist/tools/tickets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tickets.js","sourceRoot":"","sources":["../../src/tools/tickets.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@helmdesk/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Helmdesk — let AI agents manage tickets, send emails, and search your knowledge base",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "helmdesk-mcp": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "pnpm run build",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@helmdesk/sdk": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.25.23"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.3"
+  },
+  "keywords": [
+    "helmdesk",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "helpdesk",
+    "claude",
+    "llm",
+    "agent"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MoloksInc/helmdesk",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://helmdesk.dev/docs",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}