@xalantis/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# @xalantis/mcp-server
+
+MCP server for Xalantis — manage support tickets from Claude, Cursor, and other AI tools.
+
+## Installation
+
+```bash
+npm install -g @xalantis/mcp-server
+```
+
+## Configuration
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "xalantis": {
+      "command": "npx",
+      "args": ["-y", "@xalantis/mcp-server"],
+      "env": {
+        "XALANTIS_API_KEY": "sk_live_..."
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add xalantis -- npx -y @xalantis/mcp-server
+```
+
+Then set the environment variable `XALANTIS_API_KEY` in your shell.
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "xalantis": {
+      "command": "npx",
+      "args": ["-y", "@xalantis/mcp-server"],
+      "env": {
+        "XALANTIS_API_KEY": "sk_live_..."
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_tickets` | List tickets with filters (status, priority, search, pagination) |
+| `get_ticket` | Get a single ticket by UUID |
+| `create_ticket` | Create a new support ticket |
+| `update_ticket` | Update ticket status, priority, subject, etc. |
+| `reply_to_ticket` | Add a reply or internal note |
+| `list_ticket_replies` | List all replies for a ticket |
+
+## Examples
+
+Once connected, you can ask your AI assistant:
+
+- "List all open high-priority tickets"
+- "Create a ticket about the login bug reported by user@example.com"
+- "Mark ticket abc-123 as resolved"
+- "Reply to ticket abc-123 saying the fix has been deployed"
+- "Show me the replies on ticket abc-123"
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `XALANTIS_API_KEY` | Yes | Your Xalantis API key |
+
+## License
+
+MIT

package/build/api.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Lightweight HTTP client for the Xalantis API.
+ * Used internally by the MCP server tools.
+ */
+export declare class ApiError extends Error {
+    code: string;
+    status: number;
+    details?: Record<string, string[]> | undefined;
+    constructor(message: string, code: string, status: number, details?: Record<string, string[]> | undefined);
+}
+export declare function assertUuid(value: string, label: string): void;
+export declare function apiRequest(apiKey: string, method: string, path: string, body?: unknown, params?: Record<string, unknown>): Promise<unknown>;

package/build/api.js

@@ -0,0 +1,54 @@
+/**
+ * Lightweight HTTP client for the Xalantis API.
+ * Used internally by the MCP server tools.
+ */
+const BASE_URL = 'https://xalantis.com/api/v1';
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export class ApiError extends Error {
+    code;
+    status;
+    details;
+    constructor(message, code, status, details) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.details = details;
+        this.name = 'ApiError';
+    }
+}
+export function assertUuid(value, label) {
+    if (!UUID_RE.test(value)) {
+        throw new Error(`${label} must be a valid UUID (got "${value}")`);
+    }
+}
+export async function apiRequest(apiKey, method, path, body, params) {
+    const url = new URL(`${BASE_URL}${path}`);
+    if (params) {
+        for (const [key, value] of Object.entries(params)) {
+            if (value !== undefined && value !== null) {
+                url.searchParams.set(key, String(value));
+            }
+        }
+    }
+    const response = await fetch(url.toString(), {
+        method,
+        headers: {
+            'Authorization': `Bearer ${apiKey}`,
+            'Accept': 'application/json',
+            'Content-Type': 'application/json',
+        },
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    let json;
+    try {
+        json = await response.json();
+    }
+    catch {
+        throw new ApiError(`Server returned non-JSON response (HTTP ${response.status})`, 'INVALID_RESPONSE', response.status);
+    }
+    if (!response.ok) {
+        const err = json;
+        throw new ApiError(err?.error?.message || `Request failed (HTTP ${response.status})`, err?.error?.code || 'UNKNOWN_ERROR', response.status, err?.error?.details);
+    }
+    return json;
+}

package/build/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/index.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { apiRequest, assertUuid, ApiError } from './api.js';
+const API_KEY = process.env.XALANTIS_API_KEY || '';
+if (!API_KEY) {
+    console.error('Error: XALANTIS_API_KEY environment variable is required');
+    process.exit(1);
+}
+const server = new McpServer({
+    name: 'xalantis',
+    version: '0.1.0',
+});
+// ─── Helper ────────────────────────────────────────────────
+function text(data) {
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+function error(message) {
+    return { content: [{ type: 'text', text: message }], isError: true };
+}
+// ─── list_tickets ──────────────────────────────────────────
+server.tool('list_tickets', 'List support tickets with optional filters and pagination', {
+    status: z.enum(['new', 'open', 'pending', 'on_hold', 'resolved', 'closed']).optional().describe('Filter by status'),
+    priority: z.enum(['low', 'medium', 'high', 'urgent']).optional().describe('Filter by priority'),
+    search: z.string().optional().describe('Search in subject and description'),
+    requester_email: z.string().optional().describe('Filter by requester email'),
+    sort_by: z.enum(['created_at', 'updated_at', 'priority', 'status', 'due_at', 'reference']).optional().describe('Sort field'),
+    sort_dir: z.enum(['asc', 'desc']).optional().describe('Sort direction'),
+    page: z.number().int().min(1).optional().describe('Page number'),
+    per_page: z.number().int().min(1).max(100).optional().describe('Results per page (max 100)'),
+}, async (params) => {
+    try {
+        const result = await apiRequest(API_KEY, 'GET', '/tickets', undefined, params);
+        return text(result);
+    }
+    catch (e) {
+        return error(e instanceof Error ? e.message : 'Unknown error');
+    }
+});
+// ─── get_ticket ────────────────────────────────────────────
+server.tool('get_ticket', 'Get a single ticket by UUID', {
+    uuid: z.string().describe('Ticket UUID'),
+}, async ({ uuid }) => {
+    try {
+        assertUuid(uuid, 'ticket uuid');
+        const result = await apiRequest(API_KEY, 'GET', `/tickets/${uuid}`);
+        return text(result);
+    }
+    catch (e) {
+        return error(e instanceof Error ? e.message : 'Unknown error');
+    }
+});
+// ─── create_ticket ─────────────────────────────────────────
+server.tool('create_ticket', 'Create a new support ticket', {
+    subject: z.string().min(1).max(255).describe('Ticket subject'),
+    description: z.string().min(1).describe('Ticket description'),
+    requester_email: z.string().email().describe('Email of the person reporting the issue'),
+    requester_name: z.string().optional().describe('Name of the requester'),
+    priority: z.enum(['low', 'medium', 'high', 'urgent']).optional().describe('Priority level (default: medium)'),
+    category_slug: z.string().optional().describe('Category slug'),
+    channel: z.enum(['api', 'email', 'phone', 'chat', 'web', 'widget']).optional().describe('Channel source'),
+}, async (params) => {
+    try {
+        const result = await apiRequest(API_KEY, 'POST', '/tickets', params);
+        return text(result);
+    }
+    catch (e) {
+        if (e instanceof ApiError && e.details) {
+            return error(`Validation failed: ${JSON.stringify(e.details)}`);
+        }
+        return error(e instanceof Error ? e.message : 'Unknown error');
+    }
+});
+// ─── update_ticket ─────────────────────────────────────────
+server.tool('update_ticket', 'Update an existing ticket (status, priority, subject, etc.)', {
+    uuid: z.string().describe('Ticket UUID'),
+    subject: z.string().min(1).max(255).optional().describe('New subject'),
+    description: z.string().min(1).optional().describe('New description'),
+    status: z.enum(['new', 'open', 'pending', 'on_hold', 'resolved', 'closed']).optional().describe('New status'),
+    priority: z.enum(['low', 'medium', 'high', 'urgent']).optional().describe('New priority'),
+    category_slug: z.string().optional().describe('Category slug'),
+    assignee_id: z.number().int().optional().describe('Assign to agent by ID'),
+    due_at: z.string().optional().describe('SLA due date (ISO 8601)'),
+}, async ({ uuid, ...data }) => {
+    try {
+        assertUuid(uuid, 'ticket uuid');
+        const result = await apiRequest(API_KEY, 'PATCH', `/tickets/${uuid}`, data);
+        return text(result);
+    }
+    catch (e) {
+        return error(e instanceof Error ? e.message : 'Unknown error');
+    }
+});
+// ─── reply_to_ticket ───────────────────────────────────────
+server.tool('reply_to_ticket', 'Add a reply or internal note to a ticket', {
+    ticket_uuid: z.string().describe('Ticket UUID'),
+    content: z.string().min(1).describe('Reply content'),
+    is_internal: z.boolean().optional().describe('Set to true for an internal note (not visible to requester)'),
+}, async ({ ticket_uuid, ...data }) => {
+    try {
+        assertUuid(ticket_uuid, 'ticket uuid');
+        const result = await apiRequest(API_KEY, 'POST', `/tickets/${ticket_uuid}/replies`, data);
+        return text(result);
+    }
+    catch (e) {
+        return error(e instanceof Error ? e.message : 'Unknown error');
+    }
+});
+// ─── list_ticket_replies ───────────────────────────────────
+server.tool('list_ticket_replies', 'List all replies and notes for a ticket', {
+    ticket_uuid: z.string().describe('Ticket UUID'),
+    page: z.number().int().min(1).optional().describe('Page number'),
+    per_page: z.number().int().min(1).max(100).optional().describe('Results per page'),
+}, async ({ ticket_uuid, ...params }) => {
+    try {
+        assertUuid(ticket_uuid, 'ticket uuid');
+        const result = await apiRequest(API_KEY, 'GET', `/tickets/${ticket_uuid}/replies`, undefined, params);
+        return text(result);
+    }
+    catch (e) {
+        return error(e instanceof Error ? e.message : 'Unknown error');
+    }
+});
+// ─── Start server ──────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Xalantis MCP server running');
+}
+main().catch((err) => {
+    console.error('Fatal error:', err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@xalantis/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for Xalantis — manage support tickets from Claude, Cursor, and other AI tools",
+  "type": "module",
+  "bin": {
+    "xalantis-mcp": "./build/index.js"
+  },
+  "main": "build/index.js",
+  "files": ["build"],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node build/index.js",
+    "lint": "tsc --noEmit"
+  },
+  "keywords": ["xalantis", "mcp", "model-context-protocol", "tickets", "support", "ai"],
+  "author": "WAZMINE <dev@xalantis.com>",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}