superops-it 1.0.1 → 1.1.12

package/README.md

@@ -12,40 +12,38 @@ SuperOps IT Teams is for **internal IT departments** - IT teams within a single
 
 ## Installation
 
+We recommend using [bun](https://bun.sh) for faster startup times - MCP servers start on every request, so speed matters.
+
 ```bash
-npx superops-it
+bunx superops-it@latest
 ```
 
-Or install globally:
+Or with npx:
 
 ```bash
-npm install -g superops-it
+npx superops-it@latest
 ```
 
-## Configuration
+Or install globally:
 
-### Claude Code
+```bash
+bun install -g superops-it@latest
+```
 
 ```bash
-claude mcp add superops-it -- npx -y superops-it
+npm install -g superops-it@latest
 ```
 
-<details>
-<summary>Or manually add to settings</summary>
+## Configuration
 
-Add to `~/.claude/settings.json`:
+### Claude Code
 
-```json
-{
-  "mcpServers": {
-    "superops-it": {
-      "command": "npx",
-      "args": ["-y", "superops-it"]
-    }
-  }
-}
+```bash
+claude mcp add superops-it \
+  -e SUPEROPS_API_KEY=your-api-key \
+  -e SUPEROPS_SUBDOMAIN=your-subdomain \
+  -- bunx superops-it@latest
 ```
-</details>
 
 ### Claude Desktop
 
@@ -55,13 +53,29 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 {
   "mcpServers": {
     "superops-it": {
-      "command": "npx",
-      "args": ["-y", "superops-it"]
+      "command": "bunx",
+      "args": ["superops-it@latest"],
+      "env": {
+        "SUPEROPS_API_KEY": "your-api-key",
+        "SUPEROPS_SUBDOMAIN": "your-subdomain"
+      }
     }
   }
 }
 ```
 
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `SUPEROPS_API_KEY` | Yes | Your SuperOps API key |
+| `SUPEROPS_SUBDOMAIN` | Yes | Your subdomain (e.g., `acme` from `acme.superops.ai`) |
+| `SUPEROPS_REGION` | No | `us` (default) or `eu` |
+| `SUPEROPS_TIMEOUT` | No | Request timeout in ms (default: 30000) |
+| `SUPEROPS_READ_ONLY` | No | Set to `true` to block mutations |
+
+Get your API key from **SuperOps Admin > API Settings**.
+
 ## Available Tools
 
 ### `search_superops_api`
@@ -100,6 +114,26 @@ list_superops_operations({ type: "mutations" })
 list_superops_operations({ type: "all" })
 ```
 
+### `execute_graphql`
+
+Execute a GraphQL query or mutation against the SuperOps API. Requires environment variables (see [Configuration](#configuration)).
+
+```
+execute_graphql({
+  operation: "query { getTicket(id: \"123\") { id subject status } }"
+})
+
+execute_graphql({
+  operation: "mutation createTicket($input: CreateTicketInput!) { createTicket(input: $input) { id } }",
+  variables: { input: { subject: "New ticket", departmentId: "456" } }
+})
+```
+
+**API limits and notes:**
+- Maximum 800 API requests per minute
+- Date/time values must be in UTC timezone with ISO format (e.g., `2022-04-10T10:15:30`)
+- Use `null` to clear/reset attribute values
+
 ## API Endpoints
 
 - **US**: `https://api.superops.ai/it`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superops-it",
-  "version": "1.0.1",
+  "version": "1.1.12",
   "description": "MCP server for SuperOps IT Teams GraphQL API documentation",
   "type": "module",
   "main": "src/index.mjs",
@@ -23,19 +23,18 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Limehawk/superops-mcp.git",
+    "url": "git+https://github.com/limehawk/superops-mcp.git",
     "directory": "packages/it"
   },
-  "homepage": "https://github.com/Limehawk/superops-mcp/tree/main/packages/it#readme",
+  "homepage": "https://github.com/limehawk/superops-mcp/tree/main/packages/it#readme",
   "bugs": {
-    "url": "https://github.com/Limehawk/superops-mcp/issues"
+    "url": "https://github.com/limehawk/superops-mcp/issues"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.2"
   },
   "files": [
     "src/",
-    "docs/api-index.json",
-    "docs/introduction.json"
+    "docs/api-index.json"
   ]
 }

package/src/client.mjs

@@ -0,0 +1,137 @@
+/**
+ * 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)) {
+      return body.map(e => e.message).join('; ');
+    }
+    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 body = await response.json();
+
+        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

@@ -8,15 +8,36 @@ import {
 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 = '1.0.0';
+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;
 
@@ -33,7 +54,10 @@ async function loadApiData() {
 // Create server
 const server = new Server(
     { name: SERVER_NAME, version: SERVER_VERSION },
-    { capabilities: { tools: {} } }
+    {
+        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
@@ -96,6 +120,32 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     },
                     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']
+                }
             }
         ]
     };
@@ -239,6 +289,55 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 };
             }
 
+            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: [{

package/docs/introduction.json

@@ -1,9 +0,0 @@
-{
-  "title": "SuperOps IT Teams GraphQL API",
-  "description": "Welcome to the Superops IT GraphQL API reference! This reference includes the complete set of GraphQL types, queries, mutations, and their parameters. For more tutorial-oriented API documentation, please check out our API Guide",
-  "contact": "support@superops.com",
-  "endpoints": {
-    "us": "https://api.superops.ai/it",
-    "eu": "https://euapi.superops.ai/it"
-  }
-}