@wilnertech/halopsa-mcp-server 1.0.0

package/dist/index.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * HaloPSA MCP Server v1.0
+ * Provides direct API access to HaloPSA for Claude Code with token optimization
+ *
+ * CRITICAL: HaloPSA is WilnerTech's billing backbone
+ * - Asset/user counts determine client charges
+ * - Accuracy is essential for revenue protection
+ * - Deduplication prevents billing errors
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, InitializeRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { HaloPSAAPIClient } from './api/client.js';
+import { globalCache } from './cache/memory-cache.js';
+import { ToolRegistry } from './tools/registry.js';
+import { registerAllTools } from './tools/registrations.js';
+import { prewarmCache } from './cache/prewarm.js';
+// =============================================================================
+// Environment Variable Validation
+// =============================================================================
+const HALOPSA_CLIENT_ID = process.env.HALOPSA_CLIENT_ID;
+const HALOPSA_CLIENT_SECRET = process.env.HALOPSA_CLIENT_SECRET;
+const HALOPSA_BASE_URL = process.env.HALOPSA_BASE_URL || 'https://support.wilnertech.com';
+if (!HALOPSA_CLIENT_ID) {
+    console.error('Error: HALOPSA_CLIENT_ID environment variable is required');
+    process.exit(1);
+}
+if (!HALOPSA_CLIENT_SECRET) {
+    console.error('Error: HALOPSA_CLIENT_SECRET environment variable is required');
+    process.exit(1);
+}
+// =============================================================================
+// Initialize API Client + Tool Registry
+// =============================================================================
+const client = new HaloPSAAPIClient({
+    clientId: HALOPSA_CLIENT_ID,
+    clientSecret: HALOPSA_CLIENT_SECRET,
+    baseUrl: HALOPSA_BASE_URL,
+});
+const registry = new ToolRegistry();
+registerAllTools(registry);
+// =============================================================================
+// Create MCP Server
+// =============================================================================
+const server = new Server({
+    name: 'halopsa-mcp-server',
+    version: '1.0.0',
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// =============================================================================
+// Register Initialization Handler
+// =============================================================================
+server.setRequestHandler(InitializeRequestSchema, async () => {
+    return {
+        protocolVersion: '2024-11-05',
+        capabilities: {
+            tools: {},
+        },
+        serverInfo: {
+            name: 'halopsa-mcp-server',
+            version: '1.0.0',
+        },
+    };
+});
+// =============================================================================
+// Register Tool List Handler
+// =============================================================================
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools: registry.getToolSchemas() };
+});
+// =============================================================================
+// Register Tool Execution Handler
+// =============================================================================
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        const result = await registry.dispatch(client, name, (args ?? {}));
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: result,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error executing tool ${name}: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Unknown error executing tool ${name}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// =============================================================================
+// Graceful Shutdown Handlers
+// =============================================================================
+process.on('SIGINT', () => {
+    globalCache.stopCleanupTimer();
+    process.exit(0);
+});
+process.on('SIGTERM', () => {
+    globalCache.stopCleanupTimer();
+    process.exit(0);
+});
+// =============================================================================
+// Start Server
+// =============================================================================
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Cache prewarm — fire-and-forget (don't await, don't block server startup)
+    prewarmCache(client).catch((error) => {
+        console.error('Cache prewarm error:', error);
+    });
+    console.error(`HaloPSA MCP Server v1.0 running on stdio (${registry.size} tools registered)`);
+}
+main().catch((error) => {
+    console.error('Fatal error in main():', 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":"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"}

package/dist/schemas/common.d.ts

@@ -0,0 +1,212 @@
+/**
+ * Common Zod schemas shared across HaloPSA MCP Server tools
+ * Centralizes reusable validation schemas for consistency and maintainability
+ */
+import { z } from 'zod';
+/**
+ * Format options schema for token optimization
+ * Used by all tools that return formatted responses
+ */
+export declare const FormatOptionsSchema: z.ZodOptional<z.ZodObject<{
+    format: z.ZodOptional<z.ZodEnum<["compact", "standard", "detailed"]>>;
+    fields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    omit_empty: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    format?: "compact" | "standard" | "detailed" | undefined;
+    fields?: string[] | undefined;
+    omit_empty?: boolean | undefined;
+}, {
+    format?: "compact" | "standard" | "detailed" | undefined;
+    fields?: string[] | undefined;
+    omit_empty?: boolean | undefined;
+}>>;
+/**
+ * Type alias for format options
+ */
+export type FormatOptionsInput = z.infer<typeof FormatOptionsSchema>;
+/**
+ * Pagination schema for list operations
+ */
+export declare const PaginationSchema: z.ZodObject<{
+    count: z.ZodOptional<z.ZodNumber>;
+    page_no: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    count?: number | undefined;
+    page_no?: number | undefined;
+}, {
+    count?: number | undefined;
+    page_no?: number | undefined;
+}>;
+/**
+ * Type alias for pagination options
+ */
+export type PaginationInput = z.infer<typeof PaginationSchema>;
+/**
+ * Confidence score result schema for deduplication operations
+ */
+export declare const ConfidenceResultSchema: z.ZodObject<{
+    match: z.ZodNullable<z.ZodAny>;
+    confidence: z.ZodNumber;
+    matchField: z.ZodString;
+    action: z.ZodEnum<["Update", "CreateNew", "ManualReview"]>;
+    warning: z.ZodOptional<z.ZodString>;
+    matches: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
+}, "strip", z.ZodTypeAny, {
+    confidence: number;
+    matchField: string;
+    action: "Update" | "CreateNew" | "ManualReview";
+    match?: any;
+    warning?: string | undefined;
+    matches?: any[] | undefined;
+}, {
+    confidence: number;
+    matchField: string;
+    action: "Update" | "CreateNew" | "ManualReview";
+    match?: any;
+    warning?: string | undefined;
+    matches?: any[] | undefined;
+}>;
+/**
+ * Type alias for confidence result
+ */
+export type ConfidenceResult = z.infer<typeof ConfidenceResultSchema>;
+/**
+ * Duplicate group schema for scan results
+ */
+export declare const DuplicateGroupSchema: z.ZodObject<{
+    type: z.ZodEnum<["asset", "user", "site"]>;
+    matchField: z.ZodString;
+    matchValue: z.ZodString;
+    confidence: z.ZodEnum<["High", "Medium"]>;
+    entity_count: z.ZodNumber;
+    entities: z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        name: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        id: z.ZodNumber;
+        name: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        id: z.ZodNumber;
+        name: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>, "many">;
+}, "strip", z.ZodTypeAny, {
+    type: "asset" | "user" | "site";
+    confidence: "High" | "Medium";
+    matchField: string;
+    matchValue: string;
+    entity_count: number;
+    entities: z.objectOutputType<{
+        id: z.ZodNumber;
+        name: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">[];
+}, {
+    type: "asset" | "user" | "site";
+    confidence: "High" | "Medium";
+    matchField: string;
+    matchValue: string;
+    entity_count: number;
+    entities: z.objectInputType<{
+        id: z.ZodNumber;
+        name: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">[];
+}>;
+/**
+ * Type alias for duplicate group
+ */
+export type DuplicateGroup = z.infer<typeof DuplicateGroupSchema>;
+/**
+ * Asset custom field schema
+ */
+export declare const AssetFieldSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    name: z.ZodString;
+    value: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+}, "strip", z.ZodTypeAny, {
+    value: string | number | boolean | null;
+    name: string;
+    id: number;
+}, {
+    value: string | number | boolean | null;
+    name: string;
+    id: number;
+}>;
+/**
+ * Type alias for asset field
+ */
+export type AssetField = z.infer<typeof AssetFieldSchema>;
+/**
+ * User custom field schema
+ */
+export declare const UserCustomFieldSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    name: z.ZodString;
+    value: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    name: string;
+    id: number;
+}, {
+    value: string;
+    name: string;
+    id: number;
+}>;
+/**
+ * Type alias for user custom field
+ */
+export type UserCustomField = z.infer<typeof UserCustomFieldSchema>;
+/**
+ * Address schema for sites
+ */
+export declare const AddressSchema: z.ZodObject<{
+    addressline1: z.ZodOptional<z.ZodString>;
+    addressline2: z.ZodOptional<z.ZodString>;
+    city: z.ZodOptional<z.ZodString>;
+    state: z.ZodOptional<z.ZodString>;
+    postalcode: z.ZodOptional<z.ZodString>;
+    country: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    addressline1?: string | undefined;
+    addressline2?: string | undefined;
+    city?: string | undefined;
+    state?: string | undefined;
+    postalcode?: string | undefined;
+    country?: string | undefined;
+}, {
+    addressline1?: string | undefined;
+    addressline2?: string | undefined;
+    city?: string | undefined;
+    state?: string | undefined;
+    postalcode?: string | undefined;
+    country?: string | undefined;
+}>;
+/**
+ * Type alias for address
+ */
+export type Address = z.infer<typeof AddressSchema>;
+/**
+ * Status ID constants for assets
+ * CRITICAL: status_id=1 (Active) determines billing eligibility
+ */
+export declare const AssetStatusId: {
+    readonly Active: 1;
+    readonly Inactive: 2;
+    readonly Retired: 3;
+    readonly Deleted: 4;
+};
+/**
+ * Confidence thresholds for deduplication
+ * Based on WilnerTech deduplication requirements
+ */
+export declare const ConfidenceThresholds: {
+    readonly ASSET_SERIAL_EXACT: 1;
+    readonly ASSET_HOSTNAME_ONLY: 0.85;
+    readonly USER_EMAIL_EXACT: 1;
+    readonly USER_UPN_MATCH: 0.95;
+    readonly USER_USERNAME_ONLY: 0.7;
+    readonly SITE_NAME_EXACT: 1;
+    readonly SITE_FUZZY_WITH_ADDRESS: 0.95;
+    readonly SITE_FUZZY_ONLY: 0.85;
+    readonly AUTO_UPDATE: 0.95;
+    readonly MANUAL_REVIEW: 0.7;
+};
+//# sourceMappingURL=common.d.ts.map

package/dist/schemas/common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/schemas/common.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;GAOnB,CAAC;AAEd;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAErE;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;EAK3B,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE/D;;GAEG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;EAajC,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgB/B,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;EAO3B,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;GAEG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;EAOhC,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;GAEG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;EAOxB,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAEpD;;;GAGG;AACH,eAAO,MAAM,aAAa;;;;;CAKhB,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;CAkBvB,CAAC"}

package/dist/schemas/common.js

@@ -0,0 +1,127 @@
+/**
+ * Common Zod schemas shared across HaloPSA MCP Server tools
+ * Centralizes reusable validation schemas for consistency and maintainability
+ */
+import { z } from 'zod';
+/**
+ * Format options schema for token optimization
+ * Used by all tools that return formatted responses
+ */
+export const FormatOptionsSchema = z.object({
+    format: z.enum(['compact', 'standard', 'detailed']).optional()
+        .describe('Output format: compact (minimal), standard (default), detailed (pretty-printed)'),
+    fields: z.array(z.string()).optional()
+        .describe('Specific fields to include in response'),
+    omit_empty: z.boolean().optional()
+        .describe('Remove null/empty fields from response'),
+}).optional();
+/**
+ * Pagination schema for list operations
+ */
+export const PaginationSchema = z.object({
+    count: z.number().int().min(1).max(100).optional()
+        .describe('Number of results per page (max 100, default 50)'),
+    page_no: z.number().int().min(1).optional()
+        .describe('Page number (1-indexed, default 1)'),
+});
+/**
+ * Confidence score result schema for deduplication operations
+ */
+export const ConfidenceResultSchema = z.object({
+    match: z.any().nullable()
+        .describe('Matched entity or null if no match'),
+    confidence: z.number().min(0).max(1)
+        .describe('Confidence score (0.0 to 1.0)'),
+    matchField: z.string()
+        .describe('Field used for matching'),
+    action: z.enum(['Update', 'CreateNew', 'ManualReview'])
+        .describe('Recommended action based on confidence'),
+    warning: z.string().optional()
+        .describe('Warning message if applicable'),
+    matches: z.array(z.any()).optional()
+        .describe('Multiple matches if duplicates detected'),
+});
+/**
+ * Duplicate group schema for scan results
+ */
+export const DuplicateGroupSchema = z.object({
+    type: z.enum(['asset', 'user', 'site'])
+        .describe('Entity type'),
+    matchField: z.string()
+        .describe('Field used for matching'),
+    matchValue: z.string()
+        .describe('Value that matched'),
+    confidence: z.enum(['High', 'Medium'])
+        .describe('Confidence level'),
+    entity_count: z.number().int()
+        .describe('Number of duplicate entities'),
+    entities: z.array(z.object({
+        id: z.number(),
+        name: z.string(),
+    }).passthrough())
+        .describe('Array of duplicate entities'),
+});
+/**
+ * Asset custom field schema
+ */
+export const AssetFieldSchema = z.object({
+    id: z.number().int()
+        .describe('Custom field ID'),
+    name: z.string()
+        .describe('Custom field name'),
+    value: z.union([z.string(), z.number(), z.boolean(), z.null()])
+        .describe('Custom field value'),
+});
+/**
+ * User custom field schema
+ */
+export const UserCustomFieldSchema = z.object({
+    id: z.number().int()
+        .describe('Custom field ID'),
+    name: z.string()
+        .describe('Custom field name'),
+    value: z.string()
+        .describe('Custom field value'),
+});
+/**
+ * Address schema for sites
+ */
+export const AddressSchema = z.object({
+    addressline1: z.string().optional(),
+    addressline2: z.string().optional(),
+    city: z.string().optional(),
+    state: z.string().optional(),
+    postalcode: z.string().optional(),
+    country: z.string().optional(),
+});
+/**
+ * Status ID constants for assets
+ * CRITICAL: status_id=1 (Active) determines billing eligibility
+ */
+export const AssetStatusId = {
+    Active: 1, // Counts for billing
+    Inactive: 2, // Does NOT count for billing
+    Retired: 3, // Does NOT count for billing
+    Deleted: 4, // Does NOT count for billing (soft delete)
+};
+/**
+ * Confidence thresholds for deduplication
+ * Based on WilnerTech deduplication requirements
+ */
+export const ConfidenceThresholds = {
+    // Assets
+    ASSET_SERIAL_EXACT: 1.0, // 100% - exact serial match
+    ASSET_HOSTNAME_ONLY: 0.85, // 85% - hostname match, serial mismatch
+    // Users
+    USER_EMAIL_EXACT: 1.0, // 100% - exact email match
+    USER_UPN_MATCH: 0.95, // 95% - UPN match (Entra source of truth)
+    USER_USERNAME_ONLY: 0.70, // 70% - username match only
+    // Sites
+    SITE_NAME_EXACT: 1.0, // 100% - exact name match
+    SITE_FUZZY_WITH_ADDRESS: 0.95, // 95% - fuzzy name + address validation
+    SITE_FUZZY_ONLY: 0.85, // 85% - fuzzy name only
+    // Action thresholds
+    AUTO_UPDATE: 0.95, // >= 95% confidence -> auto-update
+    MANUAL_REVIEW: 0.70, // 70-94% confidence -> manual review
+};
+//# sourceMappingURL=common.js.map

package/dist/schemas/common.js.map

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