@mindstone-engineering/mcp-server-freshdesk 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,97 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 Mindstone Engineering
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+**Licensor**: Mindstone Engineering
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+**Software**: Freshdesk MCP Server
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A "Competing
+Use" means making the Software available to third parties as a commercial
+hosted service that directly competes with any product or service provided by
+the Licensor.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES, OF
+ANY CHARACTER INCLUDING DAMAGES FOR LOSS OF GOODWILL, LOST PROFITS, LOST SALES
+OR BUSINESS, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, LOST CONTENT,
+DATA OR DATA USE, BREACH OF DUTY OF GOOD FAITH, OR ANY AND ALL OTHER DAMAGES
+OR LOSSES OF ANY KIND OR NATURE WHATSOEVER (WHETHER DIRECT, INDIRECT, SPECIAL,
+COLLATERAL, INCIDENTAL, CONSEQUENTIAL OR OTHERWISE) ARISING OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THIS LICENSE, EVEN IF SUCH PARTY SHALL HAVE
+BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+### Trademark
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Change Date
+
+Four years from the date the Software is made available under these Terms and
+Conditions: **2030-04-08**
+
+## Change License
+
+MIT License
+
+## License Details
+
+| Parameter | Value |
+|---|---|
+| Licensor | Mindstone Engineering |
+| Software | Freshdesk MCP Server |
+| Use Limitation | Competing Use |
+| Change Date | 2030-04-08 |
+| Change License | MIT |

package/README.md

@@ -0,0 +1,98 @@
+# @mindstone-engineering/mcp-server-freshdesk
+
+[![npm version](https://img.shields.io/npm/v/@mindstone-engineering/mcp-server-freshdesk.svg)](https://www.npmjs.com/package/@mindstone-engineering/mcp-server-freshdesk)
+[![License: FSL-1.1-MIT](https://img.shields.io/badge/License-FSL--1.1--MIT-blue.svg)](./LICENSE)
+
+Freshdesk Support MCP server for Model Context Protocol hosts. Manage helpdesk tickets, search and filter support requests, reply to customers, add internal notes, and configure Freshdesk accounts — all through a standardised MCP interface.
+
+## Requirements
+
+- Node.js 20+
+- npm
+
+## Quick Start
+
+### Install & build
+
+```bash
+cd <path-to-repo>/connectors/freshdesk
+npm install
+npm run build
+```
+
+### npx (once published)
+
+```bash
+npx -y @mindstone-engineering/mcp-server-freshdesk
+```
+
+### Local
+
+```bash
+node dist/index.js
+```
+
+## Configuration
+
+### Environment variables
+
+- `FRESHDESK_CONFIG_PATH` — path to the config directory that stores account credentials (defaults to `~/.mcp/freshdesk`)
+- `MCP_HOST_BRIDGE_STATE` — optional path to a host bridge state file used for credential management
+- `MINDSTONE_REBEL_BRIDGE_STATE` — backwards-compatible alias for `MCP_HOST_BRIDGE_STATE`
+
+## Host configuration examples
+
+### Claude Desktop / Cursor
+
+```json
+{
+  "mcpServers": {
+    "Freshdesk": {
+      "command": "npx",
+      "args": ["-y", "@mindstone-engineering/mcp-server-freshdesk"],
+      "env": {
+        "FRESHDESK_CONFIG_PATH": "~/.mcp/freshdesk"
+      }
+    }
+  }
+}
+```
+
+### Local development (no npm publish needed)
+
+```json
+{
+  "mcpServers": {
+    "Freshdesk": {
+      "command": "node",
+      "args": ["<path-to-repo>/connectors/freshdesk/dist/index.js"],
+      "env": {
+        "FRESHDESK_CONFIG_PATH": "~/.mcp/freshdesk"
+      }
+    }
+  }
+}
+```
+
+## Tools (11)
+
+### Account management
+- `configure_freshdesk` — Connect a Freshdesk account using subdomain and API key
+- `list_freshdesk_accounts` — List connected Freshdesk accounts with agent emails
+- `remove_freshdesk_account` — Disconnect a Freshdesk account
+
+### Tickets
+- `list_freshdesk_tickets` — List tickets using predefined filters
+- `get_freshdesk_ticket` — Get a single ticket by ID with optional conversations
+- `search_freshdesk_tickets` — Search tickets using Freshdesk query syntax
+- `create_freshdesk_ticket` — Create a new ticket
+- `update_freshdesk_ticket` — Update ticket fields, status, or assignee
+- `reply_to_freshdesk_ticket` — Add a public reply to a ticket
+- `add_freshdesk_note` — Add a private or public note to a ticket
+
+### Discovery
+- `list_freshdesk_ticket_fields` — List all ticket fields including custom fields
+
+## Licence
+
+[FSL-1.1-MIT](./LICENSE) — Functional Source License, Version 1.1, with MIT future licence. The software converts to MIT licence on 2030-04-08.

package/dist/bridge.d.ts

@@ -5,7 +5,7 @@ export declare const BRIDGE_STATE_PATH: string;
 /**
  * Send a request to the host app bridge.
  *
- * The bridge is an HTTP server running inside the host app (e.g. Rebel)
+ * The bridge is an HTTP server running inside the host app (e.g. the host application)
  * that handles credential management and other cross-process operations.
  */
 export declare const bridgeRequest: (urlPath: string, body: Record<string, unknown>) => Promise<{

package/dist/bridge.js

@@ -18,7 +18,7 @@ const loadBridgeState = () => {
 /**
  * Send a request to the host app bridge.
  *
- * The bridge is an HTTP server running inside the host app (e.g. Rebel)
+ * The bridge is an HTTP server running inside the host app (e.g. the host application)
  * that handles credential management and other cross-process operations.
  */
 export const bridgeRequest = async (urlPath, body) => {

package/dist/client.js

@@ -8,6 +8,7 @@
  * Base URL: https://{domain}.freshdesk.com/api/v2
  */
 import { FreshdeskError, REQUEST_TIMEOUT_MS } from './types.js';
+import { validateSubdomain } from './utils.js';
 /**
  * Make an authenticated request to the Freshdesk API.
  *
@@ -18,6 +19,8 @@ import { FreshdeskError, REQUEST_TIMEOUT_MS } from './types.js';
  * @returns Parsed JSON response
  */
 export async function freshdeskFetch(domain, apiKey, endpoint, options = {}) {
+    // Defence-in-depth: validate domain before URL construction
+    validateSubdomain(domain);
     const { params, ...fetchOptions } = options;
     // Build URL with query params
     let url = `https://${domain}.freshdesk.com/api/v2${endpoint}`;
@@ -63,7 +66,7 @@ export async function freshdeskFetch(domain, apiKey, endpoint, options = {}) {
     }
     // Handle auth errors
     if (response.status === 401) {
-        throw new FreshdeskError('Authentication failed', 'AUTH_FAILED', 'API key is invalid or revoked. Check your Freshdesk API key, or reconnect in Mindstone settings.');
+        throw new FreshdeskError('Authentication failed', 'AUTH_FAILED', 'API key is invalid or revoked. Check your Freshdesk API key in your MCP host\'s settings.');
     }
     // Handle forbidden
     if (response.status === 403) {
@@ -82,7 +85,7 @@ export async function freshdeskFetch(domain, apiKey, endpoint, options = {}) {
             : response.status >= 500
                 ? 'Freshdesk server error - try again later'
                 : 'Request failed';
-        throw new FreshdeskError(`Freshdesk API error (${response.status}): ${statusMessage}`, 'API_ERROR', 'Check the request parameters and try again. If the problem persists, reconnect your Freshdesk account in Mindstone settings.');
+        throw new FreshdeskError(`Freshdesk API error (${response.status}): ${statusMessage}`, 'API_ERROR', 'Check the request parameters and try again. If the problem persists, reconnect your Freshdesk account in your MCP host\'s settings.');
     }
     // Handle 204 No Content
     if (response.status === 204) {

package/dist/index.d.ts

@@ -7,8 +7,8 @@
  *
  * Environment variables:
  * - FRESHDESK_CONFIG_PATH: Path to config directory containing accounts.json
- * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (optional)
- * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path (optional)
+ * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (primary, optional)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy/deprecated bridge state path (optional)
  */
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -7,8 +7,8 @@
  *
  * Environment variables:
  * - FRESHDESK_CONFIG_PATH: Path to config directory containing accounts.json
- * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (optional)
- * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path (optional)
+ * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (primary, optional)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy/deprecated bridge state path (optional)
  */
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createServer } from './server.js';

package/dist/tools/configure.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { loadAccounts, getAccountsConfig, removeAccount, upsertAccount } from '../auth.js';
 import { bridgeRequest, BRIDGE_STATE_PATH } from '../bridge.js';
 import { FreshdeskError } from '../types.js';
-import { withErrorHandling } from '../utils.js';
+import { withErrorHandling, validateSubdomain } from '../utils.js';
 export function registerConfigureTools(server) {
     // ── configure_freshdesk ─────────────────────────────────────────
     server.registerTool('configure_freshdesk', {
@@ -22,6 +22,8 @@ export function registerConfigureTools(server) {
     }, withErrorHandling(async (args) => {
         const domain = args.domain.trim();
         const apiKey = args.api_key.trim();
+        // Validate subdomain before any storage or network call
+        validateSubdomain(domain);
         // If bridge is available, persist via bridge
         if (BRIDGE_STATE_PATH) {
             try {
@@ -71,7 +73,7 @@ export function registerConfigureTools(server) {
             return JSON.stringify({
                 ok: true,
                 accounts: [],
-                message: 'No Freshdesk accounts connected. Use configure_freshdesk or go to Mindstone Settings > Integrations > Freshdesk to connect.',
+                message: 'No Freshdesk accounts connected. Use configure_freshdesk to connect your account.',
             });
         }
         const accountList = config.accounts.map((account) => ({

package/dist/tools/fields.js

@@ -21,7 +21,7 @@ export function registerFieldTools(server) {
             return JSON.stringify({
                 ok: false,
                 error: 'No Freshdesk account connected',
-                resolution: 'Use configure_freshdesk or go to Mindstone Settings > Integrations > Freshdesk to connect your account.',
+                resolution: 'Use configure_freshdesk to connect your account.',
             });
         }
         const fields = await freshdeskFetch(account.domain, account.apiKey, '/admin/ticket_fields');

package/dist/tools/tickets.js

@@ -8,7 +8,7 @@ function noAccountError() {
     return JSON.stringify({
         ok: false,
         error: 'No Freshdesk account connected',
-        resolution: 'Use configure_freshdesk or go to Mindstone Settings > Integrations > Freshdesk to connect your account.',
+        resolution: 'Use configure_freshdesk to connect your account.',
     });
 }
 export function registerTicketTools(server) {

package/dist/utils.d.ts

@@ -1,4 +1,13 @@
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Validates that a Freshdesk subdomain is a safe, single-label hostname component.
+ *
+ * Rejects any domain containing `/`, `@`, `?`, `#`, `.`, `%`, whitespace, or
+ * other characters that could redirect API requests to an attacker-controlled host.
+ *
+ * @throws {FreshdeskError} with code INVALID_SUBDOMAIN if validation fails
+ */
+export declare function validateSubdomain(domain: string): void;
 type ToolHandler<T> = (args: T, extra: unknown) => Promise<CallToolResult>;
 /**
  * Wraps a tool handler with standard error handling.

package/dist/utils.js

@@ -1,4 +1,27 @@
 import { FreshdeskError } from './types.js';
+/**
+ * Strict subdomain regex: only lowercase alphanumerics and hyphens,
+ * must start and end with an alphanumeric character.
+ * Prevents API key exfiltration via URL manipulation.
+ */
+const SUBDOMAIN_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+/**
+ * Validates that a Freshdesk subdomain is a safe, single-label hostname component.
+ *
+ * Rejects any domain containing `/`, `@`, `?`, `#`, `.`, `%`, whitespace, or
+ * other characters that could redirect API requests to an attacker-controlled host.
+ *
+ * @throws {FreshdeskError} with code INVALID_SUBDOMAIN if validation fails
+ */
+export function validateSubdomain(domain) {
+    if (!domain || !domain.trim()) {
+        throw new FreshdeskError('Freshdesk subdomain cannot be empty', 'INVALID_SUBDOMAIN', 'Provide a valid Freshdesk subdomain (e.g. "acme" for acme.freshdesk.com).');
+    }
+    const trimmed = domain.trim();
+    if (!SUBDOMAIN_RE.test(trimmed)) {
+        throw new FreshdeskError(`Invalid Freshdesk subdomain: "${trimmed}". Only lowercase alphanumeric characters and hyphens are allowed.`, 'INVALID_SUBDOMAIN', 'Provide just the subdomain part (e.g. "acme" for acme.freshdesk.com). Do not include the full URL, dots, or special characters.');
+    }
+}
 /**
  * Wraps a tool handler with standard error handling.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindstone-engineering/mcp-server-freshdesk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Freshdesk Support MCP server for Model Context Protocol hosts",
   "license": "FSL-1.1-MIT",
   "type": "module",