@wilnertech/halopsa-mcp-server 1.0.0

package/dist/utils/zod-to-schema.js

@@ -0,0 +1,182 @@
+/**
+ * Converts Zod schemas to MCP-compatible JSON Schema objects.
+ *
+ * The MCP SDK expects inputSchema as:
+ *   { type: 'object', properties: Record<string, unknown>, required?: string[] }
+ *
+ * This utility traverses Zod's internal _def structure to produce that shape,
+ * handling the types used across ITGlue MCP tool schemas: string, number,
+ * boolean, array, object, enum, literal, optional, default, and effects
+ * (z.coerce). Descriptions and numeric min/max checks are preserved.
+ */
+/**
+ * Convert a single Zod type to a JSON Schema property descriptor.
+ * Handles wrapper types (optional, default, effects/coerce, nullable)
+ * by recursing into their inner types.
+ */
+function zodTypeToJsonSchema(schema) {
+    const def = schema._def;
+    const typeName = def.typeName;
+    const result = {};
+    // Preserve .describe() text
+    if (typeof def.description === 'string') {
+        result.description = def.description;
+    }
+    switch (typeName) {
+        case 'ZodString': {
+            result.type = 'string';
+            break;
+        }
+        case 'ZodNumber': {
+            result.type = 'number';
+            // Propagate min/max constraints from .min()/.max() checks
+            const checks = def.checks;
+            if (checks) {
+                for (const check of checks) {
+                    if (check.kind === 'min') {
+                        result.minimum = check.value;
+                    }
+                    else if (check.kind === 'max') {
+                        result.maximum = check.value;
+                    }
+                }
+            }
+            break;
+        }
+        case 'ZodBoolean': {
+            result.type = 'boolean';
+            break;
+        }
+        case 'ZodEnum': {
+            result.type = 'string';
+            result.enum = def.values;
+            break;
+        }
+        case 'ZodLiteral': {
+            const value = def.value;
+            if (typeof value === 'string') {
+                result.type = 'string';
+            }
+            else if (typeof value === 'number') {
+                result.type = 'number';
+            }
+            else if (typeof value === 'boolean') {
+                result.type = 'boolean';
+            }
+            result.const = value;
+            break;
+        }
+        case 'ZodArray': {
+            result.type = 'array';
+            const itemSchema = def.type;
+            result.items = zodTypeToJsonSchema(itemSchema);
+            break;
+        }
+        case 'ZodObject': {
+            result.type = 'object';
+            const shape = schema._def.shape();
+            const properties = {};
+            const required = [];
+            for (const [key, fieldSchema] of Object.entries(shape)) {
+                properties[key] = zodTypeToJsonSchema(fieldSchema);
+                if (!isOptionalType(fieldSchema)) {
+                    required.push(key);
+                }
+            }
+            result.properties = properties;
+            if (required.length > 0) {
+                result.required = required;
+            }
+            break;
+        }
+        // Wrapper types: unwrap and recurse
+        case 'ZodOptional': {
+            const innerOptional = def.innerType;
+            const inner = zodTypeToJsonSchema(innerOptional);
+            // Merge description from the optional wrapper if present, inner takes precedence
+            if (result.description && !inner.description) {
+                inner.description = result.description;
+            }
+            return inner;
+        }
+        case 'ZodDefault': {
+            const innerDefault = def.innerType;
+            const inner = zodTypeToJsonSchema(innerDefault);
+            if (result.description && !inner.description) {
+                inner.description = result.description;
+            }
+            return inner;
+        }
+        case 'ZodNullable': {
+            const innerNullable = def.innerType;
+            const inner = zodTypeToJsonSchema(innerNullable);
+            if (result.description && !inner.description) {
+                inner.description = result.description;
+            }
+            return inner;
+        }
+        case 'ZodEffects': {
+            // z.coerce.number(), z.coerce.string(), z.preprocess(), z.transform()
+            const innerEffects = def.schema;
+            const inner = zodTypeToJsonSchema(innerEffects);
+            if (result.description && !inner.description) {
+                inner.description = result.description;
+            }
+            return inner;
+        }
+        case 'ZodAny': {
+            // z.any() — no type constraint, description carries the semantics
+            break;
+        }
+        case 'ZodRecord': {
+            // z.record() — open-ended object
+            result.type = 'object';
+            break;
+        }
+        default: {
+            // Fallback for unknown types - warn and treat as opaque object
+            console.warn(`zod-to-schema: unhandled Zod type "${typeName}" — falling back to { type: "object" }`);
+            result.type = 'object';
+            break;
+        }
+    }
+    return result;
+}
+/**
+ * Check whether a Zod type represents an optional field.
+ * Optional, default, and nullable wrappers all make a field non-required.
+ */
+function isOptionalType(schema) {
+    const def = schema._def;
+    const typeName = def.typeName;
+    if (typeName === 'ZodOptional' || typeName === 'ZodDefault') {
+        return true;
+    }
+    // ZodNullable wrapping an optional
+    if (typeName === 'ZodNullable') {
+        const inner = def.innerType;
+        return isOptionalType(inner);
+    }
+    // ZodEffects wrapping an optional (e.g., z.coerce.number().optional() piped through transform)
+    if (typeName === 'ZodEffects') {
+        const inner = def.schema;
+        return isOptionalType(inner);
+    }
+    return false;
+}
+/**
+ * Convert a top-level Zod object schema to an MCP-compatible inputSchema.
+ *
+ * The input is expected to be a z.ZodObject (possibly wrapped in optional/effects).
+ * Returns { type: 'object', properties: {...}, required?: [...] }.
+ */
+export function zodToJsonSchema(schema) {
+    const converted = zodTypeToJsonSchema(schema);
+    // The top-level must always be type: 'object'
+    return {
+        type: 'object',
+        properties: converted.properties || {},
+        ...(converted.required ? { required: converted.required } : {}),
+    };
+}
+//# sourceMappingURL=zod-to-schema.js.map

package/dist/utils/zod-to-schema.js.map

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

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@wilnertech/halopsa-mcp-server",
+  "version": "1.0.0",
+  "description": "Model Context Protocol server for HaloPSA API integration - WilnerTech billing backbone",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "halopsa-mcp-server": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    ".env.example"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "test:smoke": "node tests/smoke-crud.mjs",
+    "lint": "eslint src --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "axios": "^1.7.9",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "@typescript-eslint/eslint-plugin": "^8.20.0",
+    "@typescript-eslint/parser": "^8.20.0",
+    "eslint": "^9.18.0",
+    "prettier": "^3.4.2",
+    "typescript": "^5.7.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "halopsa",
+    "api",
+    "psa",
+    "wilnertech"
+  ],
+  "author": "WilnerTech <dev@wilnertech.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/WilnerTech/halopsa-mcp-server.git"
+  },
+  "homepage": "https://github.com/WilnerTech/halopsa-mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/WilnerTech/halopsa-mcp-server/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}