superops-it 1.1.16 → 2.0.0

package/build/mcp/tools/apiSchema.js

@@ -0,0 +1,173 @@
+import * as z from "zod/v4";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { createLogger } from "../../utils/logger.js";
+import { ResponseFormatter } from "../../utils/responseFormatter.js";
+import { getSchemaCache } from "../../utils/introspection.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+let cachedExamples = null;
+async function loadExamples() {
+    if (cachedExamples)
+        return cachedExamples;
+    const examplesPath = join(__dirname, "..", "..", "examples.json");
+    const raw = await readFile(examplesPath, "utf-8");
+    cachedExamples = JSON.parse(raw);
+    return cachedExamples;
+}
+const logger = createLogger("SuperOpsApiSchema");
+export const inputSchema = z.object({
+    category: z
+        .string()
+        .optional()
+        .describe('Filter by category, e.g. "Ticket", "Asset", "Client"'),
+    operation: z
+        .string()
+        .optional()
+        .describe('Get full details for a specific operation, e.g. "getTicket"'),
+    examples: z
+        .boolean()
+        .optional()
+        .describe("Include usage examples with the response. Works with operation (specific example) or alone (all examples + general patterns)."),
+});
+// outputSchema omitted — responses vary by query mode (categories, operation details, examples).
+// structuredContent is still returned for hosts that support it.
+export const name = "superops-api-schema";
+export const description = "Discover available SuperOps API operations and their parameter schemas. " +
+    "Call with no params for a category summary, with category to list operations, " +
+    "with operation for full parameter details, or with examples:true for usage patterns and gotchas.";
+export const annotations = {
+    title: "SuperOps API Schema",
+    readOnlyHint: true,
+    idempotentHint: true,
+};
+export async function handler(input) {
+    try {
+        // Examples-only mode (no operation specified) — doesn't need API
+        if (input.examples && !input.operation && !input.category) {
+            const allExamples = await loadExamples();
+            return ResponseFormatter.success("Usage examples and common patterns", allExamples);
+        }
+        const cache = await getSchemaCache();
+        // Specific operation requested
+        if (input.operation) {
+            const op = cache.operations.get(input.operation);
+            if (!op) {
+                const suggestions = [...cache.operations.keys()]
+                    .filter((n) => n.toLowerCase().includes(input.operation.toLowerCase()))
+                    .slice(0, 5);
+                const hint = suggestions.length > 0
+                    ? `Did you mean: ${suggestions.join(", ")}?`
+                    : "Use without params to see available categories.";
+                return ResponseFormatter.error(`Operation not found: "${input.operation}"`, hint);
+            }
+            const argDetails = op.args.map((arg) => {
+                const inputType = cache.types.get(arg.typeName);
+                return {
+                    name: arg.name,
+                    type: arg.typeName,
+                    required: arg.isNonNull,
+                    isList: arg.isList,
+                    description: arg.description,
+                    ...(inputType?.inputFields && {
+                        fields: inputType.inputFields.map((f) => ({
+                            name: f.name,
+                            type: f.typeName,
+                            required: f.isNonNull,
+                            isList: f.isList,
+                            description: f.description,
+                            ...resolveInputFields(f.typeName, cache.types),
+                        })),
+                    }),
+                };
+            });
+            const returnType = cache.types.get(op.returnTypeName);
+            const returnFields = returnType?.fields?.map((f) => ({
+                name: f.name,
+                type: f.typeName,
+                isList: f.isList,
+                description: f.description,
+            }));
+            // Include usage example if requested and available
+            let example = undefined;
+            if (input.examples) {
+                const allExamples = await loadExamples();
+                example = allExamples[input.operation] || null;
+            }
+            return ResponseFormatter.success(`Schema for ${input.operation}`, {
+                name: op.name,
+                type: op.type,
+                description: op.description,
+                arguments: argDetails,
+                returnType: op.returnTypeName,
+                returnFields,
+                ...(example !== undefined && { example }),
+            });
+        }
+        // Category filter
+        if (input.category) {
+            const matchedCategory = [...cache.categories.keys()].find((c) => c.toLowerCase() === input.category.toLowerCase());
+            if (!matchedCategory) {
+                const available = [...cache.categories.keys()].sort().join(", ");
+                return ResponseFormatter.error(`Category not found: "${input.category}"`, `Available categories: ${available}`);
+            }
+            const opNames = cache.categories.get(matchedCategory) || [];
+            const ops = opNames.map((opName) => {
+                const op = cache.operations.get(opName);
+                return {
+                    name: opName,
+                    type: op?.type,
+                    description: op?.description,
+                    args: op?.args
+                        .map((a) => `${a.name}: ${a.typeName}${a.isNonNull ? "!" : ""}`)
+                        .join(", ") || "none",
+                };
+            });
+            const queries = ops.filter((o) => o.type === "query");
+            const mutations = ops.filter((o) => o.type === "mutation");
+            return ResponseFormatter.success(`Operations in ${matchedCategory}`, {
+                category: matchedCategory,
+                totalOperations: ops.length,
+                queries,
+                mutations,
+            });
+        }
+        // No filter — category summary
+        const summary = {};
+        for (const [category, opNames] of cache.categories) {
+            const queries = opNames.filter((n) => cache.operations.get(n)?.type === "query").length;
+            const mutations = opNames.filter((n) => cache.operations.get(n)?.type === "mutation").length;
+            summary[category] = {
+                total: opNames.length,
+                queries,
+                mutations,
+                operations: opNames,
+            };
+        }
+        return ResponseFormatter.success("Available API categories", {
+            totalOperations: cache.operations.size,
+            totalCategories: cache.categories.size,
+            categories: summary,
+        });
+    }
+    catch (error) {
+        logger.error("Failed to fetch API schema", {
+            error: error instanceof Error ? error.message : "Unknown error",
+        });
+        return ResponseFormatter.error("Failed to fetch API schema", `Could not retrieve schema: ${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+}
+function resolveInputFields(typeName, types) {
+    const typeInfo = types.get(typeName);
+    if (!typeInfo?.inputFields)
+        return {};
+    return {
+        fields: typeInfo.inputFields.map((f) => ({
+            name: f.name,
+            type: f.typeName,
+            required: f.isNonNull,
+            description: f.description,
+        })),
+    };
+}

package/build/mcp/tools/index.js

@@ -0,0 +1,2 @@
+export * as api from "./api.js";
+export * as apiSchema from "./apiSchema.js";

package/build/server.js

@@ -0,0 +1,22 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as api from "./mcp/tools/api.js";
+import * as apiSchema from "./mcp/tools/apiSchema.js";
+export function createServer() {
+    const server = new McpServer({
+        name: "superops-it",
+        version: "2.0.0",
+    });
+    server.registerTool(api.name, {
+        title: api.annotations.title,
+        description: api.description,
+        inputSchema: api.inputSchema,
+        annotations: api.annotations,
+    }, api.handler);
+    server.registerTool(apiSchema.name, {
+        title: apiSchema.annotations.title,
+        description: apiSchema.description,
+        inputSchema: apiSchema.inputSchema,
+        annotations: apiSchema.annotations,
+    }, apiSchema.handler);
+    return server;
+}

package/build/utils/clientConfig.js

@@ -0,0 +1,38 @@
+class ConfigManager {
+    static instance;
+    config = null;
+    constructor() { }
+    static getInstance() {
+        if (!ConfigManager.instance) {
+            ConfigManager.instance = new ConfigManager();
+        }
+        return ConfigManager.instance;
+    }
+    getConfig() {
+        if (!this.config) {
+            this.config = this.loadConfig();
+        }
+        return this.config;
+    }
+    loadConfig() {
+        const apiKey = process.env.SUPEROPS_API_KEY;
+        const subdomain = process.env.SUPEROPS_SUBDOMAIN;
+        if (!apiKey)
+            throw new Error("SUPEROPS_API_KEY is required");
+        if (!subdomain)
+            throw new Error("SUPEROPS_SUBDOMAIN is required");
+        const region = (process.env.SUPEROPS_REGION || "us");
+        const host = region === "eu" ? "euapi.superops.ai" : "api.superops.ai";
+        return {
+            apiKey,
+            subdomain,
+            region,
+            timeout: parseInt(process.env.SUPEROPS_TIMEOUT || "30000", 10),
+            readOnly: process.env.SUPEROPS_READ_ONLY === "true",
+            endpoint: `https://${host}/it`,
+        };
+    }
+}
+export function getClientConfig() {
+    return ConfigManager.getInstance().getConfig();
+}

package/build/utils/graphqlClient.js

@@ -0,0 +1,113 @@
+import { getClientConfig } from "./clientConfig.js";
+import { createLogger } from "./logger.js";
+const logger = createLogger("GraphQLClient");
+const MAX_RETRIES = 3;
+const RETRY_DELAYS = [1000, 2000, 4000];
+export class SuperOpsAPIError extends Error {
+    status;
+    body;
+    context;
+    constructor(status, body, context = {}) {
+        const message = SuperOpsAPIError.formatMessage(status, body);
+        super(message);
+        this.name = "SuperOpsAPIError";
+        this.status = status;
+        this.body = body;
+        this.context = context;
+    }
+    static formatMessage(status, body) {
+        if (status === 200 && Array.isArray(body)) {
+            const messages = body
+                .map((e) => e.message)
+                .filter(Boolean);
+            if (messages.length > 0)
+                return messages.join("; ");
+            const clientErrors = body.flatMap((e) => {
+                const ext = e.extensions;
+                const errs = ext?.clientError;
+                return errs?.map((ce) => `${ce.code}: ${ce.param?.attributes?.join(", ") || "unknown"}`) || [];
+            });
+            if (clientErrors.length > 0)
+                return clientErrors.join("; ");
+            return JSON.stringify(body, null, 2);
+        }
+        const b = body;
+        return `HTTP ${status}: ${b?.message || b?.error || "Request failed"}`;
+    }
+    isRateLimited() { return this.status === 429; }
+    isAuthError() { return this.status === 401 || this.status === 403; }
+    isServerError() { return this.status >= 500; }
+    isGraphQLError() { return this.status === 200 && Array.isArray(this.body); }
+    isRetryable() { return this.isRateLimited() || this.isServerError(); }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function withRetry(fn, maxRetries = MAX_RETRIES) {
+    let lastError;
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            if (!(error instanceof SuperOpsAPIError) || !error.isRetryable())
+                throw error;
+            if (attempt < maxRetries - 1)
+                await sleep(RETRY_DELAYS[attempt]);
+        }
+    }
+    throw lastError;
+}
+export async function executeGraphQL(query, variables = {}) {
+    const config = getClientConfig();
+    if (config.readOnly && query.trim().toLowerCase().startsWith("mutation")) {
+        throw new Error("Mutations are disabled in read-only mode. Set SUPEROPS_READ_ONLY=false to enable.");
+    }
+    const context = { query: query.substring(0, 100), variables, endpoint: config.endpoint };
+    return withRetry(async () => {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), config.timeout);
+        try {
+            logger.debug("Executing GraphQL", {
+                endpoint: config.endpoint,
+                queryPrefix: query.substring(0, 60),
+            });
+            const response = await fetch(config.endpoint, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${config.apiKey}`,
+                    CustomerSubDomain: config.subdomain,
+                    "User-Agent": "superops-it-mcp/2.0",
+                },
+                body: JSON.stringify({ query, variables }),
+                signal: controller.signal,
+            });
+            const rawText = await response.text();
+            let body;
+            try {
+                body = JSON.parse(rawText);
+            }
+            catch {
+                throw new Error(`Invalid JSON response (HTTP ${response.status}): ${rawText.substring(0, 200)}`);
+            }
+            if (!response.ok) {
+                throw new SuperOpsAPIError(response.status, body, context);
+            }
+            if (Array.isArray(body.errors) && body.errors.length > 0) {
+                throw new SuperOpsAPIError(200, body.errors, context);
+            }
+            return body.data;
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "AbortError") {
+                throw new Error(`Request timed out after ${config.timeout}ms`);
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    });
+}

package/build/utils/introspection.js

@@ -0,0 +1,197 @@
+import { executeGraphQL } from "./graphqlClient.js";
+import { createLogger } from "./logger.js";
+const logger = createLogger("Introspection");
+// --- Singleton cache ---
+let cache = null;
+export async function getSchemaCache() {
+    if (cache)
+        return cache;
+    cache = await buildSchemaCache();
+    return cache;
+}
+// --- Introspection query ---
+const INTROSPECTION_QUERY = `{
+  __schema {
+    queryType { name }
+    mutationType { name }
+    types {
+      name
+      kind
+      description
+      fields(includeDeprecated: false) {
+        name
+        description
+        type { ...TypeRef }
+        args {
+          name
+          description
+          type { ...TypeRef }
+        }
+      }
+      inputFields {
+        name
+        description
+        type { ...TypeRef }
+      }
+      enumValues(includeDeprecated: false) {
+        name
+      }
+    }
+  }
+}
+
+fragment TypeRef on __Type {
+  name
+  kind
+  ofType {
+    name
+    kind
+    ofType {
+      name
+      kind
+      ofType {
+        name
+        kind
+        ofType {
+          name
+          kind
+        }
+      }
+    }
+  }
+}`;
+function unwrapType(typeRef) {
+    let isList = false;
+    let isNonNull = false;
+    let current = typeRef;
+    while (current.kind === "NON_NULL" || current.kind === "LIST") {
+        if (current.kind === "NON_NULL")
+            isNonNull = true;
+        if (current.kind === "LIST")
+            isList = true;
+        if (!current.ofType)
+            break;
+        current = current.ofType;
+    }
+    return {
+        typeName: current.name || "Unknown",
+        kind: current.kind,
+        isList,
+        isNonNull,
+    };
+}
+// --- Schema building ---
+async function buildSchemaCache() {
+    logger.info("Running introspection query...");
+    const startTime = Date.now();
+    const data = (await executeGraphQL(INTROSPECTION_QUERY));
+    const schema = data.__schema;
+    const types = new Map();
+    const operations = new Map();
+    // Build type map
+    for (const rawType of schema.types) {
+        if (rawType.name.startsWith("__"))
+            continue;
+        const typeInfo = {
+            name: rawType.name,
+            kind: rawType.kind,
+            description: rawType.description || undefined,
+        };
+        if (rawType.fields) {
+            typeInfo.fields = rawType.fields.map((f) => ({
+                name: f.name,
+                ...unwrapType(f.type),
+                description: f.description || undefined,
+            }));
+        }
+        if (rawType.inputFields) {
+            typeInfo.inputFields = rawType.inputFields.map((f) => ({
+                name: f.name,
+                ...unwrapType(f.type),
+                description: f.description || undefined,
+            }));
+        }
+        if (rawType.enumValues) {
+            typeInfo.enumValues = rawType.enumValues.map((v) => v.name);
+        }
+        types.set(rawType.name, typeInfo);
+    }
+    // Extract operations from Query and Mutation root types
+    function extractOps(rootTypeName, opType) {
+        const rawType = schema.types.find((t) => t.name === rootTypeName);
+        if (!rawType?.fields)
+            return;
+        for (const rawField of rawType.fields) {
+            const returnInfo = unwrapType(rawField.type);
+            const args = (rawField.args || []).map((a) => ({
+                name: a.name,
+                ...unwrapType(a.type),
+                description: a.description || undefined,
+            }));
+            operations.set(rawField.name, {
+                name: rawField.name,
+                type: opType,
+                description: rawField.description || "",
+                args,
+                returnTypeName: returnInfo.typeName,
+            });
+        }
+    }
+    extractOps(schema.queryType.name, "query");
+    extractOps(schema.mutationType.name, "mutation");
+    // Derive categories
+    const categories = deriveCategories(operations);
+    // Build operations list string
+    const operationsList = buildOperationsList(categories, operations);
+    const elapsed = Date.now() - startTime;
+    logger.info(`Introspection complete: ${operations.size} operations, ${types.size} types in ${elapsed}ms`);
+    return { operations, types, categories, operationsList };
+}
+// --- Category derivation ---
+const VERB_PREFIXES = [
+    "hardDelete",
+    "softDelete",
+    "get",
+    "create",
+    "update",
+    "delete",
+    "restore",
+    "run",
+    "resolve",
+    "assign",
+    "send",
+    "search",
+    "analyze",
+    "register",
+    "reset",
+];
+function stripVerb(name) {
+    for (const prefix of VERB_PREFIXES) {
+        if (name.startsWith(prefix) && name.length > prefix.length) {
+            return name.substring(prefix.length);
+        }
+    }
+    return name;
+}
+function deriveCategories(operations) {
+    const categories = new Map();
+    for (const [name] of operations) {
+        const noun = stripVerb(name);
+        // Normalize: "TicketList" → "Ticket", trailing "V2"/"V3" → removed
+        const normalized = noun.replace(/List$/, "").replace(/V[23]$/, "").replace(/s$/, "") || name;
+        const existing = categories.get(normalized) || [];
+        existing.push(name);
+        categories.set(normalized, existing);
+    }
+    return categories;
+}
+function buildOperationsList(categories, operations) {
+    const lines = [];
+    const sorted = [...categories.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+    for (const [category, opNames] of sorted) {
+        const queries = opNames.filter((n) => operations.get(n)?.type === "query").length;
+        const mutations = opNames.filter((n) => operations.get(n)?.type === "mutation").length;
+        lines.push(`${category}: ${queries}q/${mutations}m — ${opNames.join(", ")}`);
+    }
+    return lines.join("\n");
+}

package/build/utils/logger.js

@@ -0,0 +1,29 @@
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel["ERROR"] = "error";
+    LogLevel["WARN"] = "warn";
+    LogLevel["INFO"] = "info";
+    LogLevel["DEBUG"] = "debug";
+})(LogLevel || (LogLevel = {}));
+class Logger {
+    context;
+    constructor(context = "SuperOps-MCP") {
+        this.context = context;
+    }
+    log(level, message, meta) {
+        const entry = {
+            level,
+            message,
+            timestamp: new Date().toISOString(),
+            context: { service: this.context, ...meta },
+        };
+        console.error(JSON.stringify(entry));
+    }
+    error(message, meta) { this.log(LogLevel.ERROR, message, meta); }
+    warn(message, meta) { this.log(LogLevel.WARN, message, meta); }
+    info(message, meta) { this.log(LogLevel.INFO, message, meta); }
+    debug(message, meta) { this.log(LogLevel.DEBUG, message, meta); }
+}
+export function createLogger(context) {
+    return new Logger(context);
+}

package/build/utils/queryBuilder.js

@@ -0,0 +1,86 @@
+import { getSchemaCache } from "./introspection.js";
+const MAX_DEPTH = 4;
+export async function buildQuery(operationName) {
+    const cache = await getSchemaCache();
+    const op = cache.operations.get(operationName);
+    if (!op) {
+        throw new Error(`Unknown operation: "${operationName}"`);
+    }
+    const varDeclarations = [];
+    const argPassthroughs = [];
+    const variableNames = [];
+    for (const arg of op.args) {
+        const typeStr = formatGraphQLType(arg.typeName, arg.isNonNull, arg.isList);
+        varDeclarations.push(`$${arg.name}: ${typeStr}`);
+        argPassthroughs.push(`${arg.name}: $${arg.name}`);
+        variableNames.push(arg.name);
+    }
+    const varBlock = varDeclarations.length > 0 ? `(${varDeclarations.join(", ")})` : "";
+    const argBlock = argPassthroughs.length > 0 ? `(${argPassthroughs.join(", ")})` : "";
+    const selectionSet = buildSelectionSet(op.returnTypeName, cache.types, 0, new Set());
+    const keyword = op.type;
+    const query = `${keyword} ${operationName}${varBlock} {\n  ${operationName}${argBlock}${selectionSet}\n}`;
+    return { query, variableNames };
+}
+function formatGraphQLType(typeName, isNonNull, isList) {
+    let result = typeName;
+    if (isList)
+        result = `[${result}]`;
+    if (isNonNull)
+        result = `${result}!`;
+    return result;
+}
+function buildSelectionSet(typeName, types, depth, visited) {
+    if (depth >= MAX_DEPTH)
+        return "";
+    const typeInfo = types.get(typeName);
+    if (!typeInfo)
+        return "";
+    if (typeInfo.kind === "SCALAR" || typeInfo.kind === "ENUM")
+        return "";
+    if (visited.has(typeName))
+        return "";
+    visited.add(typeName);
+    const fields = typeInfo.fields;
+    if (!fields || fields.length === 0)
+        return "";
+    const selections = [];
+    const indent = "  ".repeat(depth + 2);
+    for (const field of fields) {
+        const nested = buildSelectionSet(field.typeName, types, depth + 1, new Set(visited));
+        if (nested) {
+            selections.push(`${indent}${field.name}${nested}`);
+        }
+        else if (isLeafType(field.kind, field.typeName, types)) {
+            selections.push(`${indent}${field.name}`);
+        }
+    }
+    if (selections.length === 0)
+        return "";
+    const outerIndent = "  ".repeat(depth + 1);
+    return ` {\n${selections.join("\n")}\n${outerIndent}}`;
+}
+function isLeafType(kind, typeName, types) {
+    if (kind === "SCALAR" || kind === "ENUM")
+        return true;
+    const info = types.get(typeName);
+    return info?.kind === "SCALAR" || info?.kind === "ENUM";
+}
+/**
+ * Wraps flat params into the expected variable structure.
+ * Most SuperOps operations take a single `input` arg,
+ * so { id: "123" } becomes { input: { id: "123" } }.
+ */
+export async function wrapVariables(operationName, params) {
+    const cache = await getSchemaCache();
+    const op = cache.operations.get(operationName);
+    if (!op)
+        throw new Error(`Unknown operation: "${operationName}"`);
+    if (op.args.length === 1) {
+        const argName = op.args[0].name;
+        if (!(argName in params)) {
+            return { [argName]: params };
+        }
+    }
+    return params;
+}

package/build/utils/responseFormatter.js

@@ -0,0 +1,25 @@
+export class ResponseFormatter {
+    static success(message, data) {
+        const structured = {
+            success: true,
+            message,
+            ...(data && typeof data === "object" && data !== null ? { data } : {}),
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(structured, null, 2) }],
+            structuredContent: structured,
+        };
+    }
+    static error(message, details) {
+        const structured = {
+            success: false,
+            error: message,
+            ...(details && { details }),
+        };
+        return {
+            isError: true,
+            content: [{ type: "text", text: JSON.stringify(structured, null, 2) }],
+            structuredContent: structured,
+        };
+    }
+}