@mindstone-engineering/mcp-server-servicenow 0.1.0

package/dist/auth.d.ts

@@ -0,0 +1,36 @@
+/**
+ * ServiceNow authentication module.
+ *
+ * Manages instance name + username/password lifecycle — env var on startup,
+ * runtime update via configure tool, and bridge integration for host-app
+ * credential management.
+ *
+ * Uses Basic auth: Authorization: Basic base64(username:password)
+ */
+/**
+ * Normalizes a user-provided ServiceNow instance input to just the subdomain label.
+ * Accepts: "acme", "acme.service-now.com", "https://acme.service-now.com", etc.
+ * Returns undefined if the input is invalid.
+ */
+export declare function normalizeServiceNowInstanceInput(input: string | undefined): string | undefined;
+/**
+ * Returns the current ServiceNow instance name (subdomain label).
+ */
+export declare function getInstance(): string;
+/**
+ * Returns the current ServiceNow username.
+ */
+export declare function getUsername(): string;
+/**
+ * Returns the current ServiceNow password.
+ */
+export declare function getPassword(): string;
+/**
+ * Returns true if all three credentials are configured.
+ */
+export declare function isConfigured(): boolean;
+/**
+ * Update credentials at runtime (e.g. after configure_servicenow).
+ */
+export declare function setCredentials(inst: string, user: string, pass: string): void;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.js

@@ -0,0 +1,90 @@
+/**
+ * ServiceNow authentication module.
+ *
+ * Manages instance name + username/password lifecycle — env var on startup,
+ * runtime update via configure tool, and bridge integration for host-app
+ * credential management.
+ *
+ * Uses Basic auth: Authorization: Basic base64(username:password)
+ */
+import { SINGLE_LABEL_INSTANCE_REGEX } from './types.js';
+let instance = '';
+let username = process.env.SERVICENOW_USERNAME || '';
+let password = process.env.SERVICENOW_PASSWORD || '';
+/**
+ * Extracts a hostname from a user-provided input string.
+ * Handles URLs, bare hostnames, and various formats.
+ */
+function extractHostnameFromUserInput(input) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return '';
+    const candidate = trimmed.includes('://') ? trimmed : `https://${trimmed}`;
+    try {
+        return new URL(candidate).hostname.toLowerCase();
+    }
+    catch {
+        return trimmed
+            .toLowerCase()
+            .replace(/^[a-z]+:\/\//, '')
+            .split('/')[0]
+            .split('?')[0]
+            .split('#')[0]
+            .split(':')[0];
+    }
+}
+/**
+ * Normalizes a user-provided ServiceNow instance input to just the subdomain label.
+ * Accepts: "acme", "acme.service-now.com", "https://acme.service-now.com", etc.
+ * Returns undefined if the input is invalid.
+ */
+export function normalizeServiceNowInstanceInput(input) {
+    if (!input)
+        return undefined;
+    const hostname = extractHostnameFromUserInput(input);
+    if (!hostname)
+        return undefined;
+    const normalizedHostname = hostname.trim().toLowerCase().replace(/\.$/, '');
+    const withoutSuffix = normalizedHostname.endsWith('.service-now.com')
+        ? normalizedHostname.slice(0, -'.service-now.com'.length)
+        : normalizedHostname;
+    if (!withoutSuffix || withoutSuffix.includes('.') || !SINGLE_LABEL_INSTANCE_REGEX.test(withoutSuffix)) {
+        return undefined;
+    }
+    return withoutSuffix;
+}
+// Initialize instance from env on module load
+instance = normalizeServiceNowInstanceInput(process.env.SERVICENOW_INSTANCE) || '';
+/**
+ * Returns the current ServiceNow instance name (subdomain label).
+ */
+export function getInstance() {
+    return instance;
+}
+/**
+ * Returns the current ServiceNow username.
+ */
+export function getUsername() {
+    return username;
+}
+/**
+ * Returns the current ServiceNow password.
+ */
+export function getPassword() {
+    return password;
+}
+/**
+ * Returns true if all three credentials are configured.
+ */
+export function isConfigured() {
+    return instance.length > 0 && username.length > 0 && password.length > 0;
+}
+/**
+ * Update credentials at runtime (e.g. after configure_servicenow).
+ */
+export function setCredentials(inst, user, pass) {
+    instance = inst;
+    username = user;
+    password = pass;
+}
+//# sourceMappingURL=auth.js.map

package/dist/bridge.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Path to bridge state file, supporting both current and legacy env vars.
+ */
+export declare const BRIDGE_STATE_PATH: string;
+/**
+ * Send a request to the host app bridge.
+ *
+ * The bridge is an HTTP server running inside the host app (e.g. Rebel)
+ * that handles credential management and other cross-process operations.
+ */
+export declare const bridgeRequest: (urlPath: string, body: Record<string, unknown>) => Promise<{
+    success: boolean;
+    warning?: string;
+    error?: string;
+}>;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.js

@@ -0,0 +1,43 @@
+import * as fs from 'fs';
+import { REQUEST_TIMEOUT_MS } from './types.js';
+/**
+ * Path to bridge state file, supporting both current and legacy env vars.
+ */
+export const BRIDGE_STATE_PATH = process.env.MCP_HOST_BRIDGE_STATE || process.env.MINDSTONE_REBEL_BRIDGE_STATE || '';
+const loadBridgeState = () => {
+    if (!BRIDGE_STATE_PATH)
+        return null;
+    try {
+        const raw = fs.readFileSync(BRIDGE_STATE_PATH, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Send a request to the host app bridge.
+ *
+ * The bridge is an HTTP server running inside the host app (e.g. Rebel)
+ * that handles credential management and other cross-process operations.
+ */
+export const bridgeRequest = async (urlPath, body) => {
+    const bridge = loadBridgeState();
+    if (!bridge) {
+        return { success: false, error: 'Bridge not available' };
+    }
+    const response = await fetch(`http://127.0.0.1:${bridge.port}${urlPath}`, {
+        method: 'POST',
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${bridge.token}`,
+        },
+        body: JSON.stringify(body),
+    });
+    if (response.status === 401 || response.status === 403) {
+        return { success: false, error: `Bridge returned ${response.status}: unauthorized. Check host app authentication.` };
+    }
+    return response.json();
+};
+//# sourceMappingURL=bridge.js.map

package/dist/client.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ServiceNow API HTTP client.
+ *
+ * Centralises Basic auth header injection, error handling, rate-limit
+ * messaging, and instance URL construction for all ServiceNow API calls.
+ *
+ * Auth: Authorization: Basic base64(username:password)
+ * Base URL: https://{instance}.service-now.com/api/now/table
+ */
+/**
+ * Builds a query string from key-value pairs, omitting undefined/empty values.
+ */
+export declare function buildQueryParams(params: Record<string, string | number | undefined>): string;
+/**
+ * Make an authenticated request to the ServiceNow Table API.
+ *
+ * @param tablePath  Path relative to /api/now/table, e.g. `/incident`
+ * @param options    Additional fetch options (method, body, headers)
+ * @returns Parsed JSON result from the ServiceNow response
+ */
+export declare function servicenowFetch<T>(tablePath: string, options?: RequestInit): Promise<T>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -0,0 +1,94 @@
+/**
+ * ServiceNow API HTTP client.
+ *
+ * Centralises Basic auth header injection, error handling, rate-limit
+ * messaging, and instance URL construction for all ServiceNow API calls.
+ *
+ * Auth: Authorization: Basic base64(username:password)
+ * Base URL: https://{instance}.service-now.com/api/now/table
+ */
+import { getInstance, getUsername, getPassword, isConfigured } from './auth.js';
+import { ServiceNowError, REQUEST_TIMEOUT_MS } from './types.js';
+/**
+ * Returns the ServiceNow Table API base URL for the current instance.
+ */
+function getBaseUrl() {
+    return `https://${getInstance()}.service-now.com/api/now/table`;
+}
+/**
+ * Builds a query string from key-value pairs, omitting undefined/empty values.
+ */
+export function buildQueryParams(params) {
+    const entries = Object.entries(params)
+        .filter(([, v]) => v !== undefined && v !== '')
+        .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
+    return entries.length > 0 ? `?${entries.join('&')}` : '';
+}
+/**
+ * Make an authenticated request to the ServiceNow Table API.
+ *
+ * @param tablePath  Path relative to /api/now/table, e.g. `/incident`
+ * @param options    Additional fetch options (method, body, headers)
+ * @returns Parsed JSON result from the ServiceNow response
+ */
+export async function servicenowFetch(tablePath, options = {}) {
+    if (!isConfigured()) {
+        throw new ServiceNowError('ServiceNow not configured', 'AUTH_REQUIRED', 'Use configure_servicenow to set your instance name, username, and password first.');
+    }
+    const url = `${getBaseUrl()}${tablePath}`;
+    const authHeader = 'Basic ' + Buffer.from(`${getUsername()}:${getPassword()}`).toString('base64');
+    let response;
+    try {
+        response = await fetch(url, {
+            ...options,
+            signal: options.signal ?? AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            headers: {
+                Authorization: authHeader,
+                Accept: 'application/json',
+                'Content-Type': 'application/json',
+                ...options.headers,
+            },
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'TimeoutError') {
+            throw new ServiceNowError('Request to ServiceNow API timed out', 'TIMEOUT', 'The request took too long. Try again or check if the ServiceNow instance is available.');
+        }
+        throw error;
+    }
+    if (response.status === 401 || response.status === 403) {
+        throw new ServiceNowError('Authentication failed. Check your instance name, username, and password.', 'AUTH_FAILED', 'Re-configure with configure_servicenow. Ensure the account has itil and knowledge roles.');
+    }
+    if (response.status === 429) {
+        throw new ServiceNowError('Rate limited by ServiceNow. Please wait before retrying.', 'RATE_LIMITED', 'Please wait before retrying. ServiceNow has rate limits based on your instance configuration.');
+    }
+    if (response.status === 404) {
+        throw new ServiceNowError('Resource not found', 'NOT_FOUND', 'The requested record does not exist. Verify the identifier.');
+    }
+    // Check for non-JSON responses (hibernating instance, login page, etc.)
+    const contentType = (response.headers.get('content-type') || '').toLowerCase();
+    if (!response.ok) {
+        let errorText;
+        try {
+            const errorBody = (await response.json());
+            errorText =
+                errorBody?.error?.message || errorBody?.error?.detail || JSON.stringify(errorBody);
+        }
+        catch {
+            errorText = await response.text().catch(() => 'Unknown error');
+        }
+        throw new ServiceNowError(`ServiceNow API error (${response.status}): ${errorText}`, 'API_ERROR', 'Check the request parameters and try again.');
+    }
+    if (!contentType.includes('application/json')) {
+        const bodyPreview = await response.text().catch(() => '(could not read body)');
+        const isHibernating = bodyPreview.toLowerCase().includes('hibernat');
+        throw new ServiceNowError(isHibernating
+            ? `ServiceNow instance '${getInstance()}' is hibernating. Wake it at https://developer.servicenow.com and try again in a few minutes.`
+            : `ServiceNow returned non-JSON response (Content-Type: ${contentType}). The instance may be down, misconfigured, or returning a login page.`, isHibernating ? 'INSTANCE_HIBERNATING' : 'UNEXPECTED_CONTENT_TYPE', isHibernating
+            ? 'Wake the instance at https://developer.servicenow.com, wait a few minutes, then try again.'
+            : 'Check that the instance name is correct and the instance is active.');
+    }
+    const body = (await response.json());
+    return body.result;
+}
+//# sourceMappingURL=client.js.map

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * ServiceNow MCP Server
+ *
+ * Provides ServiceNow ITSM integration via Model Context Protocol.
+ * Covers incidents, change requests, knowledge base articles, and users.
+ *
+ * Environment variables:
+ * - SERVICENOW_INSTANCE: ServiceNow instance name (e.g., "acme" for acme.service-now.com)
+ * - SERVICENOW_USERNAME: ServiceNow username
+ * - SERVICENOW_PASSWORD: ServiceNow password
+ * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (optional)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path (optional)
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * ServiceNow MCP Server
+ *
+ * Provides ServiceNow ITSM integration via Model Context Protocol.
+ * Covers incidents, change requests, knowledge base articles, and users.
+ *
+ * Environment variables:
+ * - SERVICENOW_INSTANCE: ServiceNow instance name (e.g., "acme" for acme.service-now.com)
+ * - SERVICENOW_USERNAME: ServiceNow username
+ * - SERVICENOW_PASSWORD: ServiceNow password
+ * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (optional)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path (optional)
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('ServiceNow MCP server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createServer(): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,15 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerConfigureTools, registerIncidentTools, registerChangeTools, registerKnowledgeTools, registerUserTools, } from './tools/index.js';
+export function createServer() {
+    const server = new McpServer({
+        name: 'servicenow-mcp-server',
+        version: '0.1.0',
+    });
+    registerConfigureTools(server);
+    registerIncidentTools(server);
+    registerChangeTools(server);
+    registerKnowledgeTools(server);
+    registerUserTools(server);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/tools/changes.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerChangeTools(server: McpServer): void;
+//# sourceMappingURL=changes.d.ts.map

package/dist/tools/changes.js

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import { servicenowFetch, buildQueryParams } from '../client.js';
+import { withErrorHandling } from '../utils.js';
+export function registerChangeTools(server) {
+    // ── list_servicenow_change_requests ───────────────────────────
+    server.registerTool('list_servicenow_change_requests', {
+        description: 'List or search change requests in ServiceNow. ' +
+            'Returns: number, short_description, state, type, priority, assigned_to, start_date, end_date. ' +
+            'Use ServiceNow encoded query syntax for filtering. ' +
+            'Type values: "normal", "standard", "emergency".',
+        inputSchema: z.object({
+            query: z
+                .string()
+                .optional()
+                .describe('ServiceNow encoded query (e.g., "state=implement^type=normal")'),
+            limit: z
+                .number()
+                .optional()
+                .default(20)
+                .describe('Max results to return (default: 20)'),
+            offset: z
+                .number()
+                .optional()
+                .default(0)
+                .describe('Offset for pagination (default: 0)'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        const params = buildQueryParams({
+            sysparm_limit: args.limit ?? 20,
+            sysparm_offset: args.offset ?? 0,
+            sysparm_display_value: 'true',
+            sysparm_fields: 'number,short_description,state,type,priority,assigned_to,start_date,end_date',
+            sysparm_query: args.query,
+        });
+        const changeRequests = await servicenowFetch(`/change_request${params}`);
+        return JSON.stringify({
+            ok: true,
+            change_requests: changeRequests,
+            count: changeRequests.length,
+        });
+    }));
+    // ── get_servicenow_change_request ─────────────────────────────
+    server.registerTool('get_servicenow_change_request', {
+        description: 'Get a single change request by number (e.g., CHG0010001) or sys_id. ' +
+            'Returns the full change request record with all fields.',
+        inputSchema: z.object({
+            identifier: z
+                .string()
+                .min(1)
+                .describe('Change request number (e.g., CHG0010001) or sys_id'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        if (args.identifier.toUpperCase().startsWith('CHG')) {
+            const params = buildQueryParams({
+                sysparm_query: `number=${args.identifier}`,
+                sysparm_limit: 1,
+                sysparm_display_value: 'true',
+            });
+            const results = await servicenowFetch(`/change_request${params}`);
+            if (results.length === 0) {
+                return JSON.stringify({
+                    ok: false,
+                    error: `Change request ${args.identifier} not found.`,
+                });
+            }
+            return JSON.stringify({ ok: true, change_request: results[0] });
+        }
+        const changeRequest = await servicenowFetch(`/change_request/${encodeURIComponent(args.identifier)}?sysparm_display_value=true`);
+        return JSON.stringify({ ok: true, change_request: changeRequest });
+    }));
+}
+//# sourceMappingURL=changes.js.map

package/dist/tools/configure.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerConfigureTools(server: McpServer): void;
+//# sourceMappingURL=configure.d.ts.map

package/dist/tools/configure.js

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+import { normalizeServiceNowInstanceInput, setCredentials } from '../auth.js';
+import { bridgeRequest, BRIDGE_STATE_PATH } from '../bridge.js';
+import { ServiceNowError } from '../types.js';
+import { withErrorHandling } from '../utils.js';
+export function registerConfigureTools(server) {
+    server.registerTool('configure_servicenow', {
+        description: 'Configure ServiceNow credentials. Call this when the user provides their instance name, username, and password. ' +
+            'The instance name is the subdomain part of the URL (e.g., "acme" for acme.service-now.com). ' +
+            'You can also paste the full URL. The account needs read/write access to incident, change_request, kb_knowledge, and sys_user tables. ' +
+            'For production use, consider creating a dedicated integration user with appropriate roles (itil, knowledge).',
+        inputSchema: z.object({
+            instance: z
+                .string()
+                .min(1)
+                .describe('ServiceNow instance name (e.g., "acme") or full URL (e.g., "https://acme.service-now.com")'),
+            username: z.string().min(1).describe('ServiceNow username'),
+            password: z.string().min(1).describe('ServiceNow password'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        const normalized = normalizeServiceNowInstanceInput(args.instance);
+        const trimmedUsername = args.username.trim();
+        const trimmedPassword = args.password.trim();
+        if (!normalized) {
+            return JSON.stringify({
+                ok: false,
+                error: 'Invalid instance. Enter just the instance name (e.g., "acme"), or paste your ServiceNow URL (e.g., https://acme.service-now.com).',
+            });
+        }
+        if (!trimmedUsername || !trimmedPassword) {
+            return JSON.stringify({
+                ok: false,
+                error: 'instance, username, and password are all required.',
+            });
+        }
+        // If bridge is available, persist via bridge
+        if (BRIDGE_STATE_PATH) {
+            try {
+                const result = await bridgeRequest('/bundled/servicenow/configure', {
+                    instance: normalized,
+                    username: trimmedUsername,
+                    password: trimmedPassword,
+                });
+                if (result.success) {
+                    setCredentials(normalized, trimmedUsername, trimmedPassword);
+                    const message = result.warning
+                        ? `ServiceNow configured successfully for ${normalized}.service-now.com. Note: ${result.warning}`
+                        : `ServiceNow configured successfully for ${normalized}.service-now.com! Try list_servicenow_incidents or search_servicenow_knowledge.`;
+                    return JSON.stringify({ ok: true, message });
+                }
+                // Bridge returned failure — surface as error, do NOT fall through
+                throw new ServiceNowError(result.error || 'Bridge configuration failed', 'BRIDGE_ERROR', 'The host app bridge rejected the configuration request. Check the host app logs.');
+            }
+            catch (error) {
+                if (error instanceof ServiceNowError)
+                    throw error;
+                // Bridge request failed (network, timeout, etc.) — surface as error
+                throw new ServiceNowError(`Bridge request failed: ${error instanceof Error ? error.message : String(error)}`, 'BRIDGE_ERROR', 'Could not reach the host app bridge. Ensure the host app is running.');
+            }
+        }
+        // No bridge configured — configure in-memory only
+        setCredentials(normalized, trimmedUsername, trimmedPassword);
+        return JSON.stringify({
+            ok: true,
+            message: `ServiceNow configured successfully for ${normalized}.service-now.com! Try list_servicenow_incidents or search_servicenow_knowledge.`,
+        });
+    }));
+}
+//# sourceMappingURL=configure.js.map

package/dist/tools/incidents.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerIncidentTools(server: McpServer): void;
+//# sourceMappingURL=incidents.d.ts.map

package/dist/tools/incidents.js

@@ -0,0 +1,177 @@
+import { z } from 'zod';
+import { servicenowFetch, buildQueryParams } from '../client.js';
+import { withErrorHandling } from '../utils.js';
+export function registerIncidentTools(server) {
+    // ── list_servicenow_incidents ─────────────────────────────────
+    server.registerTool('list_servicenow_incidents', {
+        description: 'List or search incidents in ServiceNow. ' +
+            'Returns: number, short_description, state, priority, assigned_to, sys_created_on, sys_updated_on, urgency, impact. ' +
+            'Use ServiceNow encoded query syntax for filtering (^ as AND separator). ' +
+            'Use get_servicenow_incident for full details of a specific incident.',
+        inputSchema: z.object({
+            query: z
+                .string()
+                .optional()
+                .describe('ServiceNow encoded query (e.g., "active=true^priority=1")'),
+            limit: z
+                .number()
+                .optional()
+                .default(20)
+                .describe('Max results to return (default: 20)'),
+            offset: z
+                .number()
+                .optional()
+                .default(0)
+                .describe('Offset for pagination (default: 0)'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        const params = buildQueryParams({
+            sysparm_limit: args.limit ?? 20,
+            sysparm_offset: args.offset ?? 0,
+            sysparm_display_value: 'true',
+            sysparm_fields: 'number,short_description,state,priority,assigned_to,sys_created_on,sys_updated_on,urgency,impact',
+            sysparm_query: args.query,
+        });
+        const incidents = await servicenowFetch(`/incident${params}`);
+        return JSON.stringify({ ok: true, incidents, count: incidents.length });
+    }));
+    // ── get_servicenow_incident ───────────────────────────────────
+    server.registerTool('get_servicenow_incident', {
+        description: 'Get a single incident by number (e.g., INC0010001) or sys_id. ' +
+            'Returns the full incident record with all fields.',
+        inputSchema: z.object({
+            identifier: z
+                .string()
+                .min(1)
+                .describe('Incident number (e.g., INC0010001) or sys_id'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        if (args.identifier.toUpperCase().startsWith('INC')) {
+            const params = buildQueryParams({
+                sysparm_query: `number=${args.identifier}`,
+                sysparm_limit: 1,
+                sysparm_display_value: 'true',
+            });
+            const results = await servicenowFetch(`/incident${params}`);
+            if (results.length === 0) {
+                return JSON.stringify({
+                    ok: false,
+                    error: `Incident ${args.identifier} not found.`,
+                });
+            }
+            return JSON.stringify({ ok: true, incident: results[0] });
+        }
+        // Treat as sys_id
+        const incident = await servicenowFetch(`/incident/${encodeURIComponent(args.identifier)}?sysparm_display_value=true`);
+        return JSON.stringify({ ok: true, incident });
+    }));
+    // ── create_servicenow_incident ────────────────────────────────
+    server.registerTool('create_servicenow_incident', {
+        description: 'Create a new incident in ServiceNow. ' +
+            'Provide at minimum a short_description. ' +
+            'Set urgency and impact to control priority (1=High, 2=Medium, 3=Low). ' +
+            'Note: urgency and impact are strings "1", "2", "3".',
+        inputSchema: z.object({
+            short_description: z.string().min(1).describe('Brief description of the incident'),
+            description: z.string().optional().describe('Detailed description'),
+            urgency: z
+                .string()
+                .optional()
+                .describe('Urgency: "1" (High), "2" (Medium), "3" (Low)'),
+            impact: z
+                .string()
+                .optional()
+                .describe('Impact: "1" (High), "2" (Medium), "3" (Low)'),
+            assignment_group: z.string().optional().describe('Assignment group name'),
+            caller_id: z.string().optional().describe('Caller user name or sys_id'),
+            category: z.string().optional().describe('Incident category'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        const body = {};
+        if (args.short_description)
+            body.short_description = args.short_description;
+        if (args.description)
+            body.description = args.description;
+        if (args.urgency)
+            body.urgency = args.urgency;
+        if (args.impact)
+            body.impact = args.impact;
+        if (args.assignment_group)
+            body.assignment_group = args.assignment_group;
+        if (args.caller_id)
+            body.caller_id = args.caller_id;
+        if (args.category)
+            body.category = args.category;
+        const params = buildQueryParams({ sysparm_display_value: 'true' });
+        const incident = await servicenowFetch(`/incident${params}`, {
+            method: 'POST',
+            body: JSON.stringify(body),
+        });
+        return JSON.stringify({ ok: true, message: 'Incident created.', incident });
+    }));
+    // ── update_servicenow_incident ────────────────────────────────
+    server.registerTool('update_servicenow_incident', {
+        description: 'Update an existing incident in ServiceNow by sys_id. ' +
+            'Use get_servicenow_incident to find the sys_id first. ' +
+            'State values: "1" (New), "2" (In Progress), "3" (On Hold), "6" (Resolved), "7" (Closed).',
+        inputSchema: z.object({
+            sys_id: z
+                .string()
+                .min(1)
+                .describe('Incident sys_id (use get_servicenow_incident to find it)'),
+            short_description: z.string().optional().describe('Brief description'),
+            description: z.string().optional().describe('Detailed description'),
+            state: z
+                .string()
+                .optional()
+                .describe('State: "1" (New), "2" (In Progress), "3" (On Hold), "6" (Resolved), "7" (Closed)'),
+            urgency: z
+                .string()
+                .optional()
+                .describe('Urgency: "1" (High), "2" (Medium), "3" (Low)'),
+            impact: z
+                .string()
+                .optional()
+                .describe('Impact: "1" (High), "2" (Medium), "3" (Low)'),
+            assigned_to: z.string().optional().describe('Assigned to user name or sys_id'),
+            assignment_group: z.string().optional().describe('Assignment group name'),
+            close_code: z
+                .string()
+                .optional()
+                .describe('Close code (required when resolving)'),
+            close_notes: z
+                .string()
+                .optional()
+                .describe('Close notes (required when resolving)'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        const body = {};
+        const updatableFields = [
+            'short_description',
+            'description',
+            'state',
+            'urgency',
+            'impact',
+            'assigned_to',
+            'assignment_group',
+            'close_code',
+            'close_notes',
+        ];
+        for (const field of updatableFields) {
+            if (args[field] !== undefined) {
+                body[field] = args[field];
+            }
+        }
+        const params = buildQueryParams({ sysparm_display_value: 'true' });
+        const incident = await servicenowFetch(`/incident/${encodeURIComponent(args.sys_id)}${params}`, {
+            method: 'PATCH',
+            body: JSON.stringify(body),
+        });
+        return JSON.stringify({ ok: true, message: 'Incident updated.', incident });
+    }));
+}
+//# sourceMappingURL=incidents.js.map

package/dist/tools/index.d.ts

@@ -0,0 +1,6 @@
+export { registerConfigureTools } from './configure.js';
+export { registerIncidentTools } from './incidents.js';
+export { registerChangeTools } from './changes.js';
+export { registerKnowledgeTools } from './knowledge.js';
+export { registerUserTools } from './users.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.js

@@ -0,0 +1,6 @@
+export { registerConfigureTools } from './configure.js';
+export { registerIncidentTools } from './incidents.js';
+export { registerChangeTools } from './changes.js';
+export { registerKnowledgeTools } from './knowledge.js';
+export { registerUserTools } from './users.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/knowledge.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerKnowledgeTools(server: McpServer): void;
+//# sourceMappingURL=knowledge.d.ts.map

package/dist/tools/knowledge.js

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+import { servicenowFetch, buildQueryParams } from '../client.js';
+import { withErrorHandling } from '../utils.js';
+export function registerKnowledgeTools(server) {
+    // ── search_servicenow_knowledge ───────────────────────────────
+    server.registerTool('search_servicenow_knowledge', {
+        description: 'Search knowledge base articles in ServiceNow. ' +
+            'Returns: number, short_description, sys_created_on, author, kb_knowledge_base, workflow_state. ' +
+            'Simple text queries are automatically converted to LIKE queries. ' +
+            'For advanced filtering, use ServiceNow encoded query syntax directly.',
+        inputSchema: z.object({
+            query: z
+                .string()
+                .optional()
+                .describe('Search keywords or ServiceNow encoded query'),
+            limit: z
+                .number()
+                .optional()
+                .default(20)
+                .describe('Max results to return (default: 20)'),
+            offset: z
+                .number()
+                .optional()
+                .default(0)
+                .describe('Offset for pagination (default: 0)'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        let query = args.query;
+        // If the query doesn't look like an encoded query, treat it as a keyword search
+        if (query && !query.includes('=') && !query.includes('^')) {
+            query = `short_descriptionLIKE${query}^ORtextLIKE${query}`;
+        }
+        const params = buildQueryParams({
+            sysparm_limit: args.limit ?? 20,
+            sysparm_offset: args.offset ?? 0,
+            sysparm_display_value: 'true',
+            sysparm_fields: 'number,short_description,sys_created_on,author,kb_knowledge_base,workflow_state',
+            sysparm_query: query,
+        });
+        const articles = await servicenowFetch(`/kb_knowledge${params}`);
+        return JSON.stringify({ ok: true, articles, count: articles.length });
+    }));
+    // ── get_servicenow_knowledge_article ──────────────────────────
+    server.registerTool('get_servicenow_knowledge_article', {
+        description: 'Get a full knowledge base article by sys_id or number (e.g., KB0010001). ' +
+            'Returns the full article record including the article body text.',
+        inputSchema: z.object({
+            identifier: z
+                .string()
+                .min(1)
+                .describe('KB article number (e.g., KB0010001) or sys_id'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        if (args.identifier.toUpperCase().startsWith('KB')) {
+            const params = buildQueryParams({
+                sysparm_query: `number=${args.identifier}`,
+                sysparm_limit: 1,
+                sysparm_display_value: 'true',
+            });
+            const results = await servicenowFetch(`/kb_knowledge${params}`);
+            if (results.length === 0) {
+                return JSON.stringify({
+                    ok: false,
+                    error: `Knowledge article ${args.identifier} not found.`,
+                });
+            }
+            return JSON.stringify({ ok: true, article: results[0] });
+        }
+        const article = await servicenowFetch(`/kb_knowledge/${encodeURIComponent(args.identifier)}?sysparm_display_value=true`);
+        return JSON.stringify({ ok: true, article });
+    }));
+}
+//# sourceMappingURL=knowledge.js.map

package/dist/tools/users.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerUserTools(server: McpServer): void;
+//# sourceMappingURL=users.d.ts.map

package/dist/tools/users.js

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { servicenowFetch, buildQueryParams } from '../client.js';
+import { withErrorHandling } from '../utils.js';
+export function registerUserTools(server) {
+    // ── list_servicenow_users ─────────────────────────────────────
+    server.registerTool('list_servicenow_users', {
+        description: 'List or search users in ServiceNow. ' +
+            'Returns: sys_id, user_name, first_name, last_name, email, title, department, active. ' +
+            'user_name is the login username, not the display name. ' +
+            'For name searches, use first_nameLIKE or last_nameLIKE in the query.',
+        inputSchema: z.object({
+            query: z
+                .string()
+                .optional()
+                .describe('ServiceNow encoded query (e.g., "active=true^departmentLIKEengineering")'),
+            limit: z
+                .number()
+                .optional()
+                .default(20)
+                .describe('Max results to return (default: 20)'),
+            offset: z
+                .number()
+                .optional()
+                .default(0)
+                .describe('Offset for pagination (default: 0)'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        const params = buildQueryParams({
+            sysparm_limit: args.limit ?? 20,
+            sysparm_offset: args.offset ?? 0,
+            sysparm_display_value: 'true',
+            sysparm_fields: 'sys_id,user_name,first_name,last_name,email,title,department,active',
+            sysparm_query: args.query,
+        });
+        const users = await servicenowFetch(`/sys_user${params}`);
+        return JSON.stringify({ ok: true, users, count: users.length });
+    }));
+}
+//# sourceMappingURL=users.js.map

package/dist/types.d.ts

@@ -0,0 +1,16 @@
+export declare const REQUEST_TIMEOUT_MS = 30000;
+export interface BridgeState {
+    port: number;
+    token: string;
+}
+export declare class ServiceNowError extends Error {
+    readonly code: string;
+    readonly resolution: string;
+    constructor(message: string, code: string, resolution: string);
+}
+/**
+ * Regex for a valid single-label ServiceNow instance name:
+ * lowercase alphanumeric with optional hyphens between segments.
+ */
+export declare const SINGLE_LABEL_INSTANCE_REGEX: RegExp;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,17 @@
+export const REQUEST_TIMEOUT_MS = 30_000;
+export class ServiceNowError extends Error {
+    code;
+    resolution;
+    constructor(message, code, resolution) {
+        super(message);
+        this.code = code;
+        this.resolution = resolution;
+        this.name = 'ServiceNowError';
+    }
+}
+/**
+ * Regex for a valid single-label ServiceNow instance name:
+ * lowercase alphanumeric with optional hyphens between segments.
+ */
+export const SINGLE_LABEL_INSTANCE_REGEX = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+//# sourceMappingURL=types.js.map

package/dist/utils.d.ts

@@ -0,0 +1,14 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+type ToolHandler<T> = (args: T, extra: unknown) => Promise<CallToolResult>;
+/**
+ * Wraps a tool handler with standard error handling.
+ *
+ * - On success: returns the string result as a text content block.
+ * - On ServiceNowError: returns a structured JSON error with code and resolution.
+ * - On unknown error: returns a generic error message.
+ *
+ * Secrets are never exposed in error messages.
+ */
+export declare function withErrorHandling<T>(fn: (args: T, extra: unknown) => Promise<string>): ToolHandler<T>;
+export {};
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.js

@@ -0,0 +1,42 @@
+import { ServiceNowError } from './types.js';
+/**
+ * Wraps a tool handler with standard error handling.
+ *
+ * - On success: returns the string result as a text content block.
+ * - On ServiceNowError: returns a structured JSON error with code and resolution.
+ * - On unknown error: returns a generic error message.
+ *
+ * Secrets are never exposed in error messages.
+ */
+export function withErrorHandling(fn) {
+    return async (args, extra) => {
+        try {
+            const result = await fn(args, extra);
+            return { content: [{ type: 'text', text: result }] };
+        }
+        catch (error) {
+            if (error instanceof ServiceNowError) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                ok: false,
+                                error: error.message,
+                                code: error.code,
+                                resolution: error.resolution,
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ ok: false, error: errorMessage }) }],
+                isError: true,
+            };
+        }
+    };
+}
+//# sourceMappingURL=utils.js.map

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@mindstone-engineering/mcp-server-servicenow",
+  "version": "0.1.0",
+  "description": "ServiceNow ITSM MCP server for Model Context Protocol hosts",
+  "license": "FSL-1.1-MIT",
+  "type": "module",
+  "bin": {
+    "mcp-server-servicenow": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nspr-io/mcp-servers.git",
+    "directory": "connectors/servicenow"
+  },
+  "homepage": "https://github.com/nspr-io/mcp-servers/tree/main/connectors/servicenow",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && shx chmod +x dist/index.js",
+    "prepare": "npm run build",
+    "watch": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@mindstone-engineering/mcp-test-harness": "file:../../test-harness",
+    "@types/node": "^22",
+    "@vitest/coverage-v8": "^4.1.3",
+    "msw": "^2.13.2",
+    "shx": "^0.3.4",
+    "typescript": "^5.8.2",
+    "vitest": "^4.1.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}