superops-it 1.1.16 → 2.0.0

package/src/client.mjs

@@ -1,159 +0,0 @@
-/**
- * SuperOps IT Teams GraphQL Client
- *
- * Features:
- * - Bearer token authentication
- * - Configurable timeout with AbortController
- * - Exponential backoff retry for transient failures
- * - Read-only mode to block mutations
- * - Handles GraphQL errors returned with 200 status
- */
-
-const DEFAULT_TIMEOUT_MS = 30000;
-const MAX_RETRIES = 3;
-const RETRY_DELAYS = [1000, 2000, 4000];
-
-/**
- * Structured error for SuperOps API failures
- */
-export class SuperOpsAPIError extends Error {
-  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)) {
-      // Try to extract message fields first
-      const messages = body.map(e => e.message).filter(Boolean);
-      if (messages.length > 0) {
-        return messages.join('; ');
-      }
-      // SuperOps sometimes returns null message with details in extensions.clientError
-      const clientErrors = body.flatMap(e =>
-        e.extensions?.clientError?.map(ce =>
-          `${ce.code}: ${ce.param?.attributes?.join(', ') || 'unknown'}`
-        ) || []
-      );
-      if (clientErrors.length > 0) {
-        return clientErrors.join('; ');
-      }
-      // Fallback to full error structure
-      return JSON.stringify(body, null, 2);
-    }
-    return `HTTP ${status}: ${body?.message || body?.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 class SuperOpsClient {
-  constructor(config) {
-    if (!config.apiKey) {
-      throw new Error('SUPEROPS_API_KEY is required');
-    }
-    if (!config.subdomain) {
-      throw new Error('SUPEROPS_SUBDOMAIN is required');
-    }
-
-    this.apiKey = config.apiKey;
-    this.subdomain = config.subdomain;
-    this.region = config.region || 'us';
-    this.timeout = config.timeout || DEFAULT_TIMEOUT_MS;
-    this.readOnly = config.readOnly ?? false;
-
-    const host = this.region === 'eu' ? 'euapi.superops.ai' : 'api.superops.ai';
-    this.endpoint = `https://${host}/it`;
-  }
-
-  async execute(operation, variables = {}) {
-    if (this.readOnly && operation.trim().toLowerCase().startsWith('mutation')) {
-      throw new Error(
-        'Mutations are disabled in read-only mode. ' +
-        'Set SUPEROPS_READ_ONLY=false to enable mutations.'
-      );
-    }
-
-    const context = { operation, variables, endpoint: this.endpoint };
-
-    return withRetry(async () => {
-      const controller = new AbortController();
-      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-
-      try {
-        const response = await fetch(this.endpoint, {
-          method: 'POST',
-          headers: {
-            'Content-Type': 'application/json',
-            'Authorization': `Bearer ${this.apiKey}`,
-            'CustomerSubDomain': this.subdomain,
-            'User-Agent': 'superops-it-mcp/1.0'
-          },
-          body: JSON.stringify({ query: operation, variables }),
-          signal: controller.signal
-        });
-
-        const rawText = await response.text();
-
-        let body;
-        try {
-          body = JSON.parse(rawText);
-        } catch (e) {
-          throw new Error(`Invalid JSON response (HTTP ${response.status}): ${rawText.substring(0, 200)}`);
-        }
-
-        if (!response.ok) {
-          throw new SuperOpsAPIError(response.status, body, context);
-        }
-
-        if (body.errors?.length) {
-          throw new SuperOpsAPIError(200, body.errors, context);
-        }
-
-        return body.data;
-      } catch (error) {
-        if (error.name === 'AbortError') {
-          throw new Error(`Request timed out after ${this.timeout}ms`);
-        }
-        throw error;
-      } finally {
-        clearTimeout(timeoutId);
-      }
-    });
-  }
-}

package/src/index.mjs

@@ -1,367 +0,0 @@
-#!/usr/bin/env node
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import {
-    CallToolRequestSchema,
-    ListToolsRequestSchema
-} from '@modelcontextprotocol/sdk/types.js';
-import { readFile } from 'fs/promises';
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
-import { createRequire } from 'module';
-import { SuperOpsClient, SuperOpsAPIError } from './client.mjs';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const require = createRequire(import.meta.url);
-const pkg = require('../package.json');
-
-const SERVER_NAME = 'superops-it';
-const SERVER_VERSION = pkg.version;
-const PRODUCT_NAME = 'SuperOps IT Teams';
-
-// API data cache
-let apiData = null;
-
-// API client (lazy initialization)
-let client = null;
-
-function getClient() {
-    if (!client && process.env.SUPEROPS_API_KEY && process.env.SUPEROPS_SUBDOMAIN) {
-        client = new SuperOpsClient({
-            apiKey: process.env.SUPEROPS_API_KEY,
-            subdomain: process.env.SUPEROPS_SUBDOMAIN,
-            region: process.env.SUPEROPS_REGION,
-            timeout: parseInt(process.env.SUPEROPS_TIMEOUT) || undefined,
-            readOnly: process.env.SUPEROPS_READ_ONLY === 'true'
-        });
-    }
-    return client;
-}
-
-async function loadApiData() {
-    if (apiData) return apiData;
-
-    try {
-        const indexPath = join(__dirname, '..', 'docs', 'api-index.json');
-        const content = await readFile(indexPath, 'utf-8');
-        apiData = JSON.parse(content);
-        return apiData;
-    } catch (error) {
-        throw new Error(`Failed to load API data: ${error.message}`);
-    }
-}
-
-// Create server
-const server = new Server(
-    { name: SERVER_NAME, version: SERVER_VERSION },
-    {
-        instructions: 'Use this server when the user needs help with the SuperOps IT Teams GraphQL API for internal IT departments. Provides documentation for tickets, assets, departments, users, and internal service desk operations. Search for API queries, mutations, and type definitions.',
-        capabilities: { tools: {} }
-    }
-);
-
-// List available tools
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-    return {
-        tools: [
-            {
-                name: 'search_superops_api',
-                description: `Search the ${PRODUCT_NAME} API documentation for queries, mutations, and types`,
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        query: {
-                            type: 'string',
-                            description: 'Search term to find in operation names, descriptions, and types'
-                        }
-                    },
-                    required: ['query']
-                }
-            },
-            {
-                name: 'get_superops_operation',
-                description: `Get full details of a specific ${PRODUCT_NAME} API query or mutation`,
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        name: {
-                            type: 'string',
-                            description: 'Name of the query or mutation (e.g., "getTicket", "getAsset")'
-                        }
-                    },
-                    required: ['name']
-                }
-            },
-            {
-                name: 'get_superops_type',
-                description: `Get full details of a ${PRODUCT_NAME} API type definition`,
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        name: {
-                            type: 'string',
-                            description: 'Name of the type (e.g., "Ticket", "Asset", "Department")'
-                        }
-                    },
-                    required: ['name']
-                }
-            },
-            {
-                name: 'list_superops_operations',
-                description: `List all available ${PRODUCT_NAME} API operations`,
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        type: {
-                            type: 'string',
-                            enum: ['queries', 'mutations', 'all'],
-                            description: 'Type of operations to list'
-                        }
-                    },
-                    required: ['type']
-                }
-            },
-            {
-                name: 'execute_graphql',
-                description: `Execute a GraphQL query or mutation against the ${PRODUCT_NAME} API. Requires SUPEROPS_API_KEY environment variable.
-
-IMPORTANT: Before constructing queries, you MUST look up the correct field names and syntax:
-1. Call get_superops_operation to get the query template and see the input type name
-2. Call get_superops_type for the input type (e.g., ListInfoInput) to see exact field names (pageSize not limit)
-3. Call get_superops_type for any nested types (e.g., SortInput, SortOrder) to see enum values (use DESC not "desc")
-4. Call get_superops_type for the return type (e.g., Ticket, Client) to see available fields (accountId not id)
-
-Do NOT guess field names - they are non-standard. Always look them up first.`,
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        operation: {
-                            type: 'string',
-                            description: 'The GraphQL query or mutation to execute'
-                        },
-                        variables: {
-                            type: 'object',
-                            description: 'Variables for the operation (optional)'
-                        }
-                    },
-                    required: ['operation']
-                }
-            }
-        ]
-    };
-});
-
-// Handle tool calls
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const { name, arguments: args } = request.params;
-
-    try {
-        const data = await loadApiData();
-
-        switch (name) {
-            case 'search_superops_api': {
-                const query = args.query.toLowerCase();
-                const results = {
-                    queries: [],
-                    mutations: [],
-                    types: []
-                };
-
-                for (const op of data.queries) {
-                    if (op.name.toLowerCase().includes(query) ||
-                        op.description?.toLowerCase().includes(query)) {
-                        results.queries.push({
-                            name: op.name,
-                            description: op.description,
-                            returns: op.returns
-                        });
-                    }
-                }
-
-                for (const op of data.mutations) {
-                    if (op.name.toLowerCase().includes(query) ||
-                        op.description?.toLowerCase().includes(query)) {
-                        results.mutations.push({
-                            name: op.name,
-                            description: op.description,
-                            returns: op.returns
-                        });
-                    }
-                }
-
-                for (const type of data.types) {
-                    if (type.name.toLowerCase().includes(query) ||
-                        type.description?.toLowerCase().includes(query)) {
-                        results.types.push({
-                            name: type.name,
-                            kind: type.kind,
-                            description: type.description
-                        });
-                    }
-                }
-
-                const total = results.queries.length + results.mutations.length + results.types.length;
-                return {
-                    content: [{
-                        type: 'text',
-                        text: JSON.stringify({
-                            searchTerm: args.query,
-                            totalResults: total,
-                            results
-                        }, null, 2)
-                    }]
-                };
-            }
-
-            case 'get_superops_operation': {
-                const opName = args.name.toLowerCase();
-
-                let operation = data.queries.find(q => q.name.toLowerCase() === opName);
-                if (!operation) {
-                    operation = data.mutations.find(m => m.name.toLowerCase() === opName);
-                }
-
-                if (!operation) {
-                    return {
-                        content: [{
-                            type: 'text',
-                            text: `Operation "${args.name}" not found. Use search_superops_api to find available operations.`
-                        }],
-                        isError: true
-                    };
-                }
-
-                return {
-                    content: [{
-                        type: 'text',
-                        text: JSON.stringify(operation, null, 2)
-                    }]
-                };
-            }
-
-            case 'get_superops_type': {
-                const typeName = args.name.toLowerCase();
-                const type = data.types.find(t => t.name.toLowerCase() === typeName);
-
-                if (!type) {
-                    return {
-                        content: [{
-                            type: 'text',
-                            text: `Type "${args.name}" not found. Use search_superops_api to find available types.`
-                        }],
-                        isError: true
-                    };
-                }
-
-                return {
-                    content: [{
-                        type: 'text',
-                        text: JSON.stringify(type, null, 2)
-                    }]
-                };
-            }
-
-            case 'list_superops_operations': {
-                const listType = args.type;
-                let result = {};
-
-                if (listType === 'queries' || listType === 'all') {
-                    result.queries = data.queries.map(q => ({
-                        name: q.name,
-                        description: q.description
-                    }));
-                }
-
-                if (listType === 'mutations' || listType === 'all') {
-                    result.mutations = data.mutations.map(m => ({
-                        name: m.name,
-                        description: m.description
-                    }));
-                }
-
-                result.meta = data.meta;
-
-                return {
-                    content: [{
-                        type: 'text',
-                        text: JSON.stringify(result, null, 2)
-                    }]
-                };
-            }
-
-            case 'execute_graphql': {
-                const apiClient = getClient();
-
-                if (!apiClient) {
-                    return {
-                        content: [{
-                            type: 'text',
-                            text: 'API execution requires SUPEROPS_API_KEY and SUPEROPS_SUBDOMAIN environment variables.\n\nGet your API key from SuperOps Admin > API Settings.\nYour subdomain is the prefix in your SuperOps URL (e.g., "acme" from acme.superops.ai).'
-                        }],
-                        isError: true
-                    };
-                }
-
-                try {
-                    const result = await apiClient.execute(
-                        args.operation,
-                        args.variables || {}
-                    );
-
-                    return {
-                        content: [{
-                            type: 'text',
-                            text: JSON.stringify(result, null, 2)
-                        }]
-                    };
-                } catch (error) {
-                    let message;
-
-                    if (error instanceof SuperOpsAPIError) {
-                        if (error.isAuthError()) {
-                            message = 'Authentication failed. Check your SUPEROPS_API_KEY.';
-                        } else if (error.isRateLimited()) {
-                            message = 'Rate limited after retries. Try again later.';
-                        } else if (error.isGraphQLError()) {
-                            message = `GraphQL Error: ${error.message}`;
-                        } else {
-                            message = `API Error (${error.status}): ${error.message}`;
-                        }
-                    } else {
-                        message = error.message;
-                    }
-
-                    return {
-                        content: [{ type: 'text', text: message }],
-                        isError: true
-                    };
-                }
-            }
-
-            default:
-                return {
-                    content: [{
-                        type: 'text',
-                        text: `Unknown tool: ${name}`
-                    }],
-                    isError: true
-                };
-        }
-    } catch (error) {
-        return {
-            content: [{
-                type: 'text',
-                text: `Error: ${error.message}`
-            }],
-            isError: true
-        };
-    }
-});
-
-// Start server
-async function main() {
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-}
-
-main().catch(console.error);