superops-it 1.1.18 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
 # SuperOps IT Teams MCP Server
 
-An MCP (Model Context Protocol) server that provides AI assistants with access to the SuperOps IT Teams GraphQL API documentation.
+An MCP server that gives AI assistants full access to the SuperOps IT Teams GraphQL API through two dynamic tools powered by live schema introspection.
 
 ## What is SuperOps IT Teams?
 
@@ -12,8 +12,6 @@ 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
 bunx superops-it@latest
 ```
@@ -24,16 +22,6 @@ Or with npx:
 npx superops-it@latest
 ```
 
-Or install globally:
-
-```bash
-bun install -g superops-it@latest
-```
-
-```bash
-npm install -g superops-it@latest
-```
-
 ## Configuration
 
 ### Claude Code
@@ -76,82 +64,52 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 
 Get your API key from **SuperOps Admin > API Settings**.
 
-## Available Tools
+## Tools
 
-### `search_superops_api`
+### `superops-api`
 
-Search the API documentation for queries, mutations, and types.
+Execute any SuperOps API operation by name. The server builds the GraphQL query automatically from the introspected schema.
 
 ```
-search_superops_api({ query: "ticket" })
+superops-api({ operation: "getTicketList", params: { page: 1, pageSize: 10 } })
+superops-api({ operation: "getAsset", params: { assetId: "12345" } })
+superops-api({ operation: "getPriorityList" })
 ```
 
-### `get_superops_operation`
+### `superops-api-schema`
 
-Get full details of a specific query or mutation.
+Discover available operations and their parameter schemas.
 
 ```
-get_superops_operation({ name: "getTicket" })
-get_superops_operation({ name: "getAsset" })
+superops-api-schema()                                    → Category summary
+superops-api-schema({ category: "Ticket" })              → Operations in category
+superops-api-schema({ operation: "getTicket" })           → Full parameter details
+superops-api-schema({ examples: true })                   → Usage patterns and gotchas
+superops-api-schema({ operation: "getTicket", examples: true })  → Schema + example
 ```
 
-### `get_superops_type`
-
-Get full details of a type definition.
-
-```
-get_superops_type({ name: "Ticket" })
-get_superops_type({ name: "Department" })
-```
+## Transport
 
-### `list_superops_operations`
+| Mode | Flag | Use Case |
+|------|------|----------|
+| stdio | *(default)* | Claude Code, Claude Desktop |
+| Streamable HTTP | `--http` | Web clients, containers |
+| Legacy SSE | `--sse` | Older MCP clients |
 
-List all available operations.
+## API Limits
 
-```
-list_superops_operations({ type: "queries" })
-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
+- Date/time values must be in UTC with ISO format (e.g., `2026-03-17T10:15:30`)
 
 ## API Endpoints
 
 - **US**: `https://api.superops.ai/it`
 - **EU**: `https://euapi.superops.ai/it`
 
-## Example Usage
-
-Once configured, ask Claude:
-
-- "How do I create a ticket in SuperOps?"
-- "What fields are available on the Asset type?"
-- "Search for department-related operations"
-- "Show me how to update a user"
-
 ## Related
 
 - [superops-msp](https://npmjs.com/package/superops-msp) - For SuperOps MSP (managed service providers)
 
 ## License
 
-GPL-3.0
+MIT

package/build/examples.json

@@ -0,0 +1,197 @@
+{
+  "_note": "Usage examples for tricky API patterns. Loaded by superops-api-schema when examples are requested.",
+
+  "getTicket": {
+    "description": "Fetch a single ticket by its ID",
+    "params": { "ticketId": "25507674456317952" },
+    "notes": "The field is `ticketId` (not `id`). Get ticket IDs from getTicketList."
+  },
+
+  "getTicketList": {
+    "description": "List tickets with optional filtering and pagination",
+    "params": { "page": 1, "pageSize": 25 },
+    "notes": "Returns `{ tickets: [...], listInfo: { totalCount, hasMore } }`. Max pageSize is 100.",
+    "filtering": {
+      "simple_filter": {
+        "description": "Filter by a single field",
+        "params": {
+          "page": 1,
+          "pageSize": 25,
+          "conditions": [
+            { "fieldName": "statusId", "operator": "is", "value": "Open" }
+          ]
+        }
+      },
+      "compound_filter": {
+        "description": "Combine multiple conditions with AND/OR",
+        "params": {
+          "page": 1,
+          "pageSize": 25,
+          "conditions": [
+            {
+              "joinOperator": "OR",
+              "operands": [
+                { "fieldName": "priorityName", "operator": "is", "value": "High" },
+                { "fieldName": "priorityName", "operator": "is", "value": "Urgent" }
+              ]
+            }
+          ]
+        },
+        "notes": "Use `joinOperator` + `operands` for compound conditions, NOT `operator` + `value` at the top level."
+      },
+      "date_filter": {
+        "description": "Filter by date range",
+        "params": {
+          "page": 1,
+          "pageSize": 25,
+          "conditions": [
+            { "fieldName": "createdTime", "operator": "after", "value": "2026-03-01T00:00:00Z" }
+          ]
+        },
+        "notes": "Date operators: `after`, `before`, `between`. NOT `greater than` or `less than`."
+      }
+    }
+  },
+
+  "createTicket": {
+    "description": "Create a new ticket",
+    "params": {
+      "subject": "Printer not working",
+      "description": "The printer on 3rd floor is showing error code E-301",
+      "requestType": "Incident",
+      "clientId": "12345",
+      "priority": { "name": "Medium" }
+    },
+    "notes": "`requestType` is required — use 'Incident' (default), 'Service Request', or 'Change Request'. `clientId` is required."
+  },
+
+  "updateTicket": {
+    "description": "Update an existing ticket",
+    "params": {
+      "ticketId": "25507674456317952",
+      "status": { "name": "In Progress" },
+      "priority": { "name": "High" }
+    },
+    "notes": "Only include the fields you want to change."
+  },
+
+  "createTicketConversation": {
+    "description": "Reply to a ticket",
+    "params": {
+      "ticketId": "25507674456317952",
+      "content": "<p>We're looking into this issue.</p>",
+      "conversationType": "REPLY"
+    },
+    "notes": "Content must be HTML. conversationType: REPLY (to requester), FORWARD, or NOTE."
+  },
+
+  "createTicketNote": {
+    "description": "Add a private note to a ticket",
+    "params": {
+      "ticketId": "25507674456317952",
+      "content": "<p>Internal note: checked the logs</p>",
+      "privacyType": "PRIVATE"
+    },
+    "notes": "privacyType: PRIVATE (technicians only) or PUBLIC (visible to requester)."
+  },
+
+  "getAsset": {
+    "description": "Fetch a single asset",
+    "params": { "assetId": "12345" },
+    "notes": "Field is `assetId`, not `id`."
+  },
+
+  "getAssetList": {
+    "description": "List assets with pagination",
+    "params": { "page": 1, "pageSize": 25 },
+    "notes": "Same pagination and filtering pattern as getTicketList."
+  },
+
+  "getClient": {
+    "description": "Fetch a single client",
+    "params": { "accountId": "12345" },
+    "notes": "Field is `accountId`, not `id` or `clientId`."
+  },
+
+  "getClientList": {
+    "description": "List clients",
+    "params": { "page": 1, "pageSize": 25 },
+    "notes": "Same pagination pattern as getTicketList."
+  },
+
+  "createClientV2": {
+    "description": "Create a new client (use V2, not createClient)",
+    "params": {
+      "name": "Acme Corp",
+      "hqSite": {
+        "name": "HQ",
+        "timeZone": "America/New_York"
+      }
+    },
+    "notes": "Use `createClientV2` (not `createClient`). `hqSite` with `name` and `timeZone` is required."
+  },
+
+  "getClientUserList": {
+    "description": "List contacts for a client",
+    "params": { "clientId": "12345", "page": 1, "pageSize": 25 },
+    "notes": "The `site` field on contacts is often null. Use `getClientUserAssociationList` to get user-site mappings."
+  },
+
+  "resolveAlerts": {
+    "description": "Resolve one or more alerts",
+    "params": { "alertIds": ["alert-id-1", "alert-id-2"] },
+    "notes": "Accepts an array of alert IDs to bulk-resolve."
+  },
+
+  "runScriptOnAsset": {
+    "description": "Execute a script on an asset",
+    "params": {
+      "scriptId": "12345",
+      "assetId": "67890"
+    },
+    "notes": "Script output (stdout/stderr) is NOT available via this API. Check the SuperOps UI for results."
+  },
+
+  "createKbArticle": {
+    "description": "Create a knowledge base article",
+    "params": {
+      "title": "How to reset password",
+      "content": "<p>Step 1: Go to settings...</p>",
+      "status": "PUBLISHED",
+      "portalType": "REQUESTER",
+      "clientSharedType": "ALL_CLIENTS",
+      "userSharedType": "ALL_USERS"
+    },
+    "notes": "For TECHNICIAN portal, you must also set `groupSharedType`. Visibility fields: portalType (REQUESTER or TECHNICIAN), clientSharedType (ALL_CLIENTS or specific), userSharedType (ALL_USERS or specific)."
+  },
+
+  "createWorklogEntries": {
+    "description": "Log time against a ticket",
+    "params": {
+      "ticketId": "25507674456317952",
+      "entries": [{
+        "qty": "1.5",
+        "billDateTime": "2026-03-16T10:00:00Z",
+        "description": "Troubleshooting printer issue",
+        "billable": true
+      }]
+    },
+    "notes": "`qty` is decimal hours as a string. `billDateTime` is ISO 8601."
+  },
+
+  "_pagination": {
+    "description": "General pagination pattern used by all list operations",
+    "params": { "page": 1, "pageSize": 25 },
+    "notes": "Most list operations accept `page` (1-indexed) and `pageSize` (max 100). Response includes `listInfo: { totalCount, hasMore }`."
+  },
+
+  "_filtering": {
+    "description": "General filtering pattern for list operations",
+    "notes": "Conditions use `{ fieldName, operator, value }`. Compound conditions use `{ joinOperator: 'AND'|'OR', operands: [...conditions] }`. Date operators are `after`, `before`, `between` (NOT `greater than`). Sort with `{ fieldName, order: 'ASC'|'DESC' }`."
+  },
+
+  "_id_fields": {
+    "description": "ID field naming conventions — a common gotcha",
+    "notes": "Ticket: `ticketId`. Asset: `assetId`. Client: `accountId`. Client User: `userId`. Site: `siteId`. Script: `scriptId`. Alert: `alertId`. These are NOT just `id`."
+  }
+}

package/build/http-server.js

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import express from "express";
+import { randomUUID } from "node:crypto";
+import { createServer } from "./server.js";
+import { createLogger } from "./utils/logger.js";
+const PORT = parseInt(process.env.MCP_PORT || "3000", 10);
+const logger = createLogger("MCP-HTTP-Server");
+export async function main() {
+    const app = express();
+    app.use(express.json());
+    const transports = {
+        streamable: {},
+        sse: {},
+    };
+    // Health check
+    app.get("/health", (_req, res) => {
+        res.json({ status: "ok", timestamp: new Date().toISOString() });
+    });
+    // Modern Streamable HTTP (POST /mcp)
+    app.post("/mcp", async (req, res) => {
+        try {
+            const sessionId = req.headers["mcp-session-id"];
+            let transport;
+            if (sessionId && transports.streamable[sessionId]) {
+                transport = transports.streamable[sessionId];
+            }
+            else if (!sessionId && isInitializeRequest(req.body)) {
+                transport = new StreamableHTTPServerTransport({
+                    sessionIdGenerator: () => randomUUID(),
+                    onsessioninitialized: (sid) => {
+                        transports.streamable[sid] = transport;
+                        logger.info("New MCP session initialized", { sessionId: sid });
+                    },
+                });
+                transport.onclose = () => {
+                    if (transport.sessionId) {
+                        logger.info("MCP session closed", {
+                            sessionId: transport.sessionId,
+                        });
+                        delete transports.streamable[transport.sessionId];
+                    }
+                };
+                const server = createServer();
+                await server.connect(transport);
+            }
+            else {
+                res.status(400).json({
+                    jsonrpc: "2.0",
+                    error: {
+                        code: -32000,
+                        message: "Bad Request: Invalid session or initialization",
+                    },
+                    id: null,
+                });
+                return;
+            }
+            await transport.handleRequest(req, res, req.body);
+        }
+        catch (error) {
+            logger.error("Error handling HTTP request", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            if (!res.headersSent) {
+                res.status(500).json({
+                    jsonrpc: "2.0",
+                    error: { code: -32603, message: "Internal server error" },
+                    id: null,
+                });
+            }
+        }
+    });
+    // Streamable HTTP GET (server-to-client notifications)
+    const handleSessionRequest = async (req, res) => {
+        const sessionId = req.headers["mcp-session-id"];
+        if (!sessionId || !transports.streamable[sessionId]) {
+            res.status(400).json({
+                jsonrpc: "2.0",
+                error: { code: -32000, message: "Invalid or missing session ID" },
+                id: null,
+            });
+            return;
+        }
+        try {
+            await transports.streamable[sessionId].handleRequest(req, res);
+        }
+        catch (error) {
+            logger.error("Error handling session request", {
+                error: error instanceof Error ? error.message : String(error),
+                sessionId,
+            });
+            if (!res.headersSent) {
+                res.status(500).json({
+                    jsonrpc: "2.0",
+                    error: { code: -32603, message: "Internal server error" },
+                    id: null,
+                });
+            }
+        }
+    };
+    app.get("/mcp", handleSessionRequest);
+    // Streamable HTTP DELETE (session termination)
+    app.delete("/mcp", async (req, res) => {
+        const sessionId = req.headers["mcp-session-id"];
+        if (!sessionId || !transports.streamable[sessionId]) {
+            res.status(400).json({
+                jsonrpc: "2.0",
+                error: { code: -32000, message: "Invalid or missing session ID" },
+                id: null,
+            });
+            return;
+        }
+        try {
+            await transports.streamable[sessionId].handleRequest(req, res);
+            if (transports.streamable[sessionId]) {
+                logger.info("MCP session terminated", { sessionId });
+                delete transports.streamable[sessionId];
+            }
+        }
+        catch (error) {
+            logger.error("Error handling DELETE request", {
+                error: error instanceof Error ? error.message : String(error),
+                sessionId,
+            });
+            if (!res.headersSent) {
+                res.status(500).json({
+                    jsonrpc: "2.0",
+                    error: { code: -32603, message: "Internal server error" },
+                    id: null,
+                });
+            }
+        }
+    });
+    // Legacy SSE endpoint
+    app.get("/sse", async (_req, res) => {
+        try {
+            const transport = new SSEServerTransport("/messages", res);
+            transports.sse[transport.sessionId] = transport;
+            res.on("close", () => {
+                logger.info("Legacy SSE session closed", {
+                    sessionId: transport.sessionId,
+                });
+                delete transports.sse[transport.sessionId];
+            });
+            const server = createServer();
+            await server.connect(transport);
+            logger.info("New legacy SSE session initialized", {
+                sessionId: transport.sessionId,
+            });
+        }
+        catch (error) {
+            logger.error("Error handling SSE request", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            if (!res.headersSent) {
+                res.status(500).json({
+                    jsonrpc: "2.0",
+                    error: { code: -32603, message: "Internal server error" },
+                    id: null,
+                });
+            }
+        }
+    });
+    // Legacy message endpoint
+    app.post("/messages", async (req, res) => {
+        try {
+            const sessionId = req.query.sessionId;
+            if (!sessionId) {
+                res.status(400).json({
+                    jsonrpc: "2.0",
+                    error: {
+                        code: -32000,
+                        message: "sessionId query parameter is required",
+                    },
+                    id: null,
+                });
+                return;
+            }
+            const transport = transports.sse[sessionId];
+            if (!transport) {
+                res.status(400).json({
+                    jsonrpc: "2.0",
+                    error: {
+                        code: -32000,
+                        message: "No transport found for sessionId",
+                    },
+                    id: null,
+                });
+                return;
+            }
+            await transport.handlePostMessage(req, res, req.body);
+        }
+        catch (error) {
+            logger.error("Error handling legacy message", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            if (!res.headersSent) {
+                res.status(500).json({
+                    jsonrpc: "2.0",
+                    error: { code: -32603, message: "Internal server error" },
+                    id: null,
+                });
+            }
+        }
+    });
+    app.listen(PORT, () => {
+        logger.info("SuperOps MSP MCP server started", {
+            port: PORT,
+            protocols: [
+                "Streamable HTTP (MCP 2025-03-26)",
+                "Legacy SSE (MCP 2024-11-05)",
+            ],
+            endpoints: {
+                modern: {
+                    mcp: `http://localhost:${PORT}/mcp`,
+                    health: `http://localhost:${PORT}/health`,
+                },
+                legacy: {
+                    sse: `http://localhost:${PORT}/sse`,
+                    messages: `http://localhost:${PORT}/messages`,
+                },
+            },
+        });
+    });
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    main().catch((error) => {
+        logger.error("Fatal error", {
+            error: error instanceof Error ? error.message : String(error),
+            stack: error instanceof Error ? error.stack : undefined,
+        });
+        process.exit(1);
+    });
+}

package/build/index.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+import { createLogger } from "./utils/logger.js";
+const logger = createLogger("MCP-Entry");
+async function main() {
+    const args = process.argv.slice(2);
+    const httpMode = args.includes("--http") ||
+        args.includes("--sse") ||
+        process.env.MCP_TRANSPORT === "http" ||
+        process.env.MCP_TRANSPORT === "sse";
+    if (httpMode) {
+        const httpModule = await import("./http-server.js");
+        return httpModule.main();
+    }
+    // Default: stdio mode
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info("SuperOps MSP MCP server running via stdio");
+}
+main().catch((error) => {
+    logger.error("Fatal error", {
+        error: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+    });
+    process.exit(1);
+});

package/build/mcp/tools/api.js

@@ -0,0 +1,82 @@
+import * as z from "zod/v4";
+import { createLogger } from "../../utils/logger.js";
+import { ResponseFormatter } from "../../utils/responseFormatter.js";
+import { executeGraphQL, SuperOpsAPIError, } from "../../utils/graphqlClient.js";
+import { getSchemaCache } from "../../utils/introspection.js";
+import { buildQuery, wrapVariables } from "../../utils/queryBuilder.js";
+const logger = createLogger("SuperOpsApi");
+export const inputSchema = z.object({
+    operation: z
+        .string()
+        .min(1)
+        .describe('The operation name, e.g. "getTicket", "createClient", "resolveAlerts"'),
+    params: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe("Parameters object — passed as GraphQL variables."),
+});
+// outputSchema omitted — responses are dynamic (different shape per operation).
+// structuredContent is still returned for hosts that support it.
+export const name = "superops-api";
+export let description = "Execute any SuperOps API operation. Use superops-api-schema to discover available operations and their parameters.";
+let descriptionInitialized = false;
+async function ensureDescription() {
+    if (descriptionInitialized)
+        return;
+    try {
+        const cache = await getSchemaCache();
+        description = `Execute any SuperOps API operation. Use superops-api-schema to discover available operations and their parameters.\n\nAvailable operations (${cache.operations.size} total):\n${cache.operationsList}`;
+        descriptionInitialized = true;
+    }
+    catch {
+        logger.warn("Could not fetch operations list for description enrichment");
+    }
+}
+export const annotations = {
+    title: "SuperOps API",
+    readOnlyHint: false,
+    openWorldHint: true,
+};
+export async function handler(input) {
+    await ensureDescription();
+    const { operation, params = {} } = input;
+    logger.info(`Executing: ${operation}`, {
+        hasParams: Object.keys(params).length > 0,
+    });
+    try {
+        const cache = await getSchemaCache();
+        const op = cache.operations.get(operation);
+        if (!op) {
+            const allNames = [...cache.operations.keys()];
+            const suggestions = allNames
+                .filter((n) => n.toLowerCase().includes(operation.toLowerCase()))
+                .slice(0, 5);
+            const hint = suggestions.length > 0
+                ? `\nDid you mean: ${suggestions.join(", ")}?`
+                : "\nUse superops-api-schema to list available operations.";
+            return ResponseFormatter.error(`Unknown operation: "${operation}"`, hint);
+        }
+        const { query } = await buildQuery(operation);
+        const variables = await wrapVariables(operation, params);
+        const data = await executeGraphQL(query, variables);
+        return ResponseFormatter.success(`${operation} succeeded`, data);
+    }
+    catch (error) {
+        logger.error(`${operation} failed`, {
+            error: error instanceof Error ? error.message : "Unknown error",
+        });
+        if (error instanceof SuperOpsAPIError) {
+            if (error.isAuthError()) {
+                return ResponseFormatter.error("Authentication failed", "Check your SUPEROPS_API_KEY and SUPEROPS_SUBDOMAIN configuration.");
+            }
+            if (error.isRateLimited()) {
+                return ResponseFormatter.error("Rate limited", "Too many requests. Please try again shortly.");
+            }
+            if (error.isGraphQLError()) {
+                return ResponseFormatter.error(`GraphQL error for ${operation}`, error.message);
+            }
+            return ResponseFormatter.error(`API error for ${operation}`, error.message);
+        }
+        return ResponseFormatter.error(`Failed: ${operation}`, `${error instanceof Error ? error.message : "Unknown error"}`);
+    }
+}