@uluops/ops-mcp 0.2.1

package/dist/types/server.d.ts

@@ -0,0 +1,59 @@
+/**
+ * MCP Server interface types
+ *
+ * Defines the interface for SecureMcpServer to avoid using generic Function type.
+ */
+import type { ZodRawShape } from 'zod';
+import type { McpToolResponse } from './mcp.js';
+/**
+ * Tool handler function signature
+ */
+export type ToolHandler = (args: unknown) => Promise<McpToolResponse>;
+/**
+ * Resource content item in MCP resource response
+ */
+export interface ResourceContent {
+    uri: string;
+    mimeType?: string;
+    text?: string;
+    blob?: string;
+}
+/**
+ * Resource response format returned by resource handlers
+ */
+export interface ResourceResponse {
+    contents: ResourceContent[];
+}
+/**
+ * Resource handler function signature
+ */
+export type ResourceHandler = () => Promise<ResourceResponse>;
+/**
+ * Resource metadata for registration
+ */
+export interface ResourceMetadata {
+    description?: string;
+    mimeType?: string;
+}
+/**
+ * Interface for MCP server tool registration
+ */
+export interface McpServerToolRegistration {
+    tool: (name: string, description: string, schema: ZodRawShape, handler: ToolHandler) => void;
+}
+/**
+ * Interface for MCP server resource registration
+ *
+ * Supports two overloads:
+ * - resource(name, uri, handler)
+ * - resource(name, uri, metadata, handler)
+ */
+export interface McpServerResourceRegistration {
+    resource: (name: string, uri: string, metadataOrHandler: ResourceMetadata | ResourceHandler, handler?: ResourceHandler) => void;
+}
+/**
+ * Combined interface for MCP server with both tools and resources
+ */
+export interface McpServer extends McpServerToolRegistration, McpServerResourceRegistration {
+}
+//# sourceMappingURL=server.d.ts.map

package/dist/types/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/types/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AACvC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAEhD;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,KAAK,IAAI,CAAC;CAC9F;AAED;;;;;;GAMG;AACH,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,EAAE,CACR,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,iBAAiB,EAAE,gBAAgB,GAAG,eAAe,EACrD,OAAO,CAAC,EAAE,eAAe,KACtB,IAAI,CAAC;CACX;AAED;;GAEG;AACH,MAAM,WAAW,SAAU,SAAQ,yBAAyB,EAAE,6BAA6B;CAAG"}

package/dist/types/server.js

@@ -0,0 +1,7 @@
+/**
+ * MCP Server interface types
+ *
+ * Defines the interface for SecureMcpServer to avoid using generic Function type.
+ */
+export {};
+//# sourceMappingURL=server.js.map

package/dist/types/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/types/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Structured logger with optional file output
+ *
+ * Logs to stderr (for MCP compatibility) and optionally to files.
+ */
+import type { LogLevel } from '../types/index.js';
+export interface LoggerConfig {
+    level: LogLevel;
+    enableFileLogging?: boolean;
+    logDir?: string;
+}
+export interface Logger {
+    debug: (message: string, context?: Record<string, unknown>) => void;
+    info: (message: string, context?: Record<string, unknown>) => void;
+    warn: (message: string, context?: Record<string, unknown>) => void;
+    error: (message: string, context?: Record<string, unknown>) => void;
+}
+/**
+ * Create a structured logger
+ *
+ * @param config - Logger configuration (or simple log level string for backwards compatibility)
+ */
+export declare function createLogger(config: LoggerConfig | LogLevel): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,QAAQ,CAAC;IAChB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACpE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACnE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACnE,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CACrE;AA2CD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,QAAQ,GAAG,MAAM,CAkDpE"}

package/dist/utils/logger.js

@@ -0,0 +1,90 @@
+/**
+ * Structured logger with optional file output
+ *
+ * Logs to stderr (for MCP compatibility) and optionally to files.
+ */
+import { appendFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+const LOG_LEVELS = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+/**
+ * Format a log entry as JSON
+ */
+function formatLogEntry(level, message, context) {
+    const entry = {
+        timestamp: new Date().toISOString(),
+        level: level.toUpperCase(),
+        message,
+        ...(context && Object.keys(context).length > 0 ? { context } : {}),
+    };
+    return JSON.stringify(entry);
+}
+/**
+ * Get the log file path for today
+ */
+function getLogFilePath(logDir) {
+    const date = new Date().toISOString().split('T')[0] ?? 'unknown'; // YYYY-MM-DD
+    return join(logDir, `mcp-client-${date}.log`);
+}
+/**
+ * Ensure the log directory exists
+ */
+function ensureLogDir(logDir) {
+    if (!existsSync(logDir)) {
+        mkdirSync(logDir, { recursive: true });
+    }
+}
+/**
+ * Create a structured logger
+ *
+ * @param config - Logger configuration (or simple log level string for backwards compatibility)
+ */
+export function createLogger(config) {
+    // Support simple string level for backwards compatibility
+    const resolvedConfig = typeof config === 'string' ? { level: config } : config;
+    const { level, enableFileLogging = false, logDir } = resolvedConfig;
+    const minLevel = LOG_LEVELS[level];
+    // Resolve log directory - use project-local logs/ folder like mcp-secure-server
+    const resolvedLogDir = logDir ?? join(process.cwd(), 'logs');
+    // Ensure log directory exists if file logging is enabled
+    if (enableFileLogging) {
+        ensureLogDir(resolvedLogDir);
+    }
+    const log = (logLevel, message, context) => {
+        if (LOG_LEVELS[logLevel] < minLevel) {
+            return;
+        }
+        const formatted = formatLogEntry(logLevel, message, context);
+        // Always log to stderr (MCP uses stdout for protocol)
+        console.error(formatted);
+        // Optionally log to file
+        if (enableFileLogging) {
+            try {
+                const filePath = getLogFilePath(resolvedLogDir);
+                appendFileSync(filePath, formatted + '\n', 'utf-8');
+            }
+            catch {
+                // Silently ignore file logging errors to avoid disrupting MCP
+            }
+        }
+    };
+    return {
+        debug: (message, context) => {
+            log('debug', message, context);
+        },
+        info: (message, context) => {
+            log('info', message, context);
+        },
+        warn: (message, context) => {
+            log('warn', message, context);
+        },
+        error: (message, context) => {
+            log('error', message, context);
+        },
+    };
+}
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"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"}

package/dist/utils/normalize-keys.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Key normalization utilities for snake_case → camelCase conversion
+ *
+ * MCP tool inputs use snake_case (matching the MCP protocol convention).
+ * The SDK expects camelCase. This module provides recursive conversion.
+ *
+ * Same pattern used by the CLI (utils.ts) and API (case-transform.ts).
+ */
+/**
+ * Recursively convert all object keys from snake_case to camelCase.
+ *
+ * - Arrays are recursed into (each element is normalized)
+ * - Primitives and null pass through unchanged
+ * - Nested objects are recursed
+ *
+ * @param input - The value to normalize
+ * @returns The value with all object keys converted to camelCase
+ */
+export declare function normalizeKeys(input: unknown): unknown;
+//# sourceMappingURL=normalize-keys.d.ts.map

package/dist/utils/normalize-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-keys.d.ts","sourceRoot":"","sources":["../../src/utils/normalize-keys.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAYrD"}

package/dist/utils/normalize-keys.js

@@ -0,0 +1,38 @@
+/**
+ * Key normalization utilities for snake_case → camelCase conversion
+ *
+ * MCP tool inputs use snake_case (matching the MCP protocol convention).
+ * The SDK expects camelCase. This module provides recursive conversion.
+ *
+ * Same pattern used by the CLI (utils.ts) and API (case-transform.ts).
+ */
+/**
+ * Convert a single snake_case string to camelCase
+ */
+function toCamelCase(str) {
+    return str.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+/**
+ * Recursively convert all object keys from snake_case to camelCase.
+ *
+ * - Arrays are recursed into (each element is normalized)
+ * - Primitives and null pass through unchanged
+ * - Nested objects are recursed
+ *
+ * @param input - The value to normalize
+ * @returns The value with all object keys converted to camelCase
+ */
+export function normalizeKeys(input) {
+    if (Array.isArray(input)) {
+        return input.map(normalizeKeys);
+    }
+    if (input !== null && typeof input === 'object') {
+        const result = {};
+        for (const [key, value] of Object.entries(input)) {
+            result[toCamelCase(key)] = normalizeKeys(value);
+        }
+        return result;
+    }
+    return input;
+}
+//# sourceMappingURL=normalize-keys.js.map

package/dist/utils/normalize-keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-keys.js","sourceRoot":"","sources":["../../src/utils/normalize-keys.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,SAAS,WAAW,CAAC,GAAW;IAC9B,OAAO,GAAG,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,EAAE,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;AACxE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAClC,CAAC;IACD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;YAC5E,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;QAClD,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/utils/tool-handler.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Tool handler factory
+ *
+ * Creates standardized MCP tool handlers with consistent error handling.
+ * Eliminates boilerplate across tool implementations.
+ */
+import { z } from 'zod';
+import { type McpToolResponse } from '../types/index.js';
+/**
+ * Sentinel used by preProcess hooks to short-circuit the handler with a
+ * tool response (typically an error). Discriminating on a dedicated symbol
+ * avoids accidental collision with tool input schemas that may legitimately
+ * contain a top-level `content` field.
+ */
+declare const SHORT_CIRCUIT: unique symbol;
+type ShortCircuit = McpToolResponse & {
+    readonly [SHORT_CIRCUIT]: true;
+};
+/**
+ * Construct a short-circuit response from a preProcess hook. The returned
+ * value is a normal MCP tool response plus a non-enumerable marker symbol
+ * that createToolHandler recognises.
+ */
+export declare function shortCircuit(response: McpToolResponse): ShortCircuit;
+/**
+ * Creates a standardized tool handler with Zod validation, key normalization,
+ * and SDK error mapping.
+ *
+ * All handlers follow the same flow:
+ * 1. Parse input with Zod schema (validates snake_case MCP input)
+ * 2. Normalize keys from snake_case → camelCase for SDK
+ * 3. Call SDK method with normalized input
+ * 4. Return success response or mapped error
+ *
+ * @param schema - Zod schema for input validation (snake_case fields)
+ * @param sdkCall - Function that receives the normalized (camelCase) input as
+ *   `Record<string, unknown>` and calls the SDK. The runtime contract is upheld
+ *   by Zod validation immediately upstream.
+ * @returns MCP-compatible handler function
+ *
+ * @example
+ * ```typescript
+ * server.tool(
+ *   'query_issues',
+ *   'Query issues...',
+ *   QueryIssuesInputSchema.shape,
+ *   createToolHandler(QueryIssuesInputSchema, (n) =>
+ *     opsClient.projects.listIssues(n['project'] as string, n)
+ *   )
+ * );
+ * ```
+ */
+export declare function createToolHandler<TInput>(schema: z.ZodSchema<TInput>, sdkCall: (normalized: any) => Promise<unknown>, options?: {
+    /** Tool name for error context. Included in error responses to help MCP clients diagnose failures. */
+    toolName?: string;
+    /**
+     * Transform parsed input before normalization. Return the value produced
+     * by `shortCircuit(response)` to bypass the SDK call and return `response`
+     * directly to the caller.
+     */
+    preProcess?: (input: TInput) => TInput | ShortCircuit;
+}): (args: unknown) => Promise<McpToolResponse>;
+export {};
+//# sourceMappingURL=tool-handler.d.ts.map

package/dist/utils/tool-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-handler.d.ts","sourceRoot":"","sources":["../../src/utils/tool-handler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAwChF;;;;;GAKG;AACH,QAAA,MAAM,aAAa,eAAmC,CAAC;AAEvD,KAAK,YAAY,GAAG,eAAe,GAAG;IAAE,QAAQ,CAAC,CAAC,aAAa,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAEzE;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG,YAAY,CAOpE;AAUD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EACtC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,EAQ3B,OAAO,EAAE,CAAC,UAAU,EAAE,GAAG,KAAK,OAAO,CAAC,OAAO,CAAC,EAC9C,OAAO,CAAC,EAAE;IACR,sGAAsG;IACtG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,YAAY,CAAC;CACvD,GACA,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,eAAe,CAAC,CAiC7C"}

package/dist/utils/tool-handler.js

@@ -0,0 +1,138 @@
+/**
+ * Tool handler factory
+ *
+ * Creates standardized MCP tool handlers with consistent error handling.
+ * Eliminates boilerplate across tool implementations.
+ */
+import { z } from 'zod';
+import { mapSdkErrorToMcp, mapZodErrorToMcp } from '../client/sdk-error-mapper.js';
+import { normalizeKeys } from './normalize-keys.js';
+import { createSuccessResponse } from '../types/index.js';
+/**
+ * Coerce string values to numbers for fields that the Zod schema expects as numeric.
+ * MCP JSON-RPC sometimes serializes numeric parameters as strings (e.g., "50" instead of 50).
+ * This runs before Zod validation to prevent spurious type errors at the boundary.
+ */
+function coerceNumericFields(args, schema) {
+    if (typeof args !== 'object' || args === null)
+        return args;
+    if (!(schema instanceof z.ZodObject))
+        return args;
+    const shape = schema.shape;
+    const obj = { ...args };
+    for (const [key, fieldSchema] of Object.entries(shape)) {
+        if (key in obj && typeof obj[key] === 'string') {
+            if (isNumericSchema(fieldSchema)) {
+                const num = Number(obj[key]);
+                // Number.isFinite rejects NaN, Infinity, and -Infinity
+                if (Number.isFinite(num)) {
+                    obj[key] = num;
+                }
+            }
+        }
+    }
+    return obj;
+}
+/** Check if a Zod schema (possibly wrapped in optional/nullable/default) expects a number. */
+function isNumericSchema(schema) {
+    if (schema instanceof z.ZodNumber)
+        return true;
+    if (schema instanceof z.ZodOptional || schema instanceof z.ZodNullable) {
+        return isNumericSchema(schema.unwrap());
+    }
+    if (schema instanceof z.ZodDefault) {
+        return isNumericSchema(schema.removeDefault());
+    }
+    return false;
+}
+/**
+ * Sentinel used by preProcess hooks to short-circuit the handler with a
+ * tool response (typically an error). Discriminating on a dedicated symbol
+ * avoids accidental collision with tool input schemas that may legitimately
+ * contain a top-level `content` field.
+ */
+const SHORT_CIRCUIT = Symbol('mcp.tool.short-circuit');
+/**
+ * Construct a short-circuit response from a preProcess hook. The returned
+ * value is a normal MCP tool response plus a non-enumerable marker symbol
+ * that createToolHandler recognises.
+ */
+export function shortCircuit(response) {
+    return Object.defineProperty({ ...response }, SHORT_CIRCUIT, {
+        value: true,
+        enumerable: false,
+        writable: false,
+        configurable: false,
+    });
+}
+function isShortCircuit(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value[SHORT_CIRCUIT] === true);
+}
+/**
+ * Creates a standardized tool handler with Zod validation, key normalization,
+ * and SDK error mapping.
+ *
+ * All handlers follow the same flow:
+ * 1. Parse input with Zod schema (validates snake_case MCP input)
+ * 2. Normalize keys from snake_case → camelCase for SDK
+ * 3. Call SDK method with normalized input
+ * 4. Return success response or mapped error
+ *
+ * @param schema - Zod schema for input validation (snake_case fields)
+ * @param sdkCall - Function that receives the normalized (camelCase) input as
+ *   `Record<string, unknown>` and calls the SDK. The runtime contract is upheld
+ *   by Zod validation immediately upstream.
+ * @returns MCP-compatible handler function
+ *
+ * @example
+ * ```typescript
+ * server.tool(
+ *   'query_issues',
+ *   'Query issues...',
+ *   QueryIssuesInputSchema.shape,
+ *   createToolHandler(QueryIssuesInputSchema, (n) =>
+ *     opsClient.projects.listIssues(n['project'] as string, n)
+ *   )
+ * );
+ * ```
+ */
+export function createToolHandler(schema, 
+// SAFETY: `normalized` is `any` because normalizeKeys performs a runtime
+// snake_case → camelCase key transformation that TypeScript cannot track
+// statically. Zod validation immediately upstream enforces the shape; the
+// SDK call signatures further constrain field types. createToolHandler is
+// an internal utility (not re-exported from src/index.ts), so this `any`
+// does not leak to the public npm surface.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+sdkCall, options) {
+    const toolName = options?.toolName;
+    return async (args) => {
+        try {
+            let input = schema.parse(coerceNumericFields(args, schema));
+            if (options?.preProcess) {
+                const preResult = options.preProcess(input);
+                if (isShortCircuit(preResult)) {
+                    return preResult;
+                }
+                input = preResult;
+            }
+            const normalized = normalizeKeys(input);
+            const result = await sdkCall(normalized);
+            return createSuccessResponse(result);
+        }
+        catch (error) {
+            // Log errors to stderr for debugging (MCP transport uses stdout)
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            const errorType = error instanceof z.ZodError ? 'validation' :
+                error instanceof Error ? error.constructor.name : 'unknown';
+            process.stderr.write(`[mcp-tool-error] tool=${toolName ?? 'unknown'} type=${errorType} message=${errorMsg.slice(0, 200)}\n`);
+            if (error instanceof z.ZodError) {
+                return mapZodErrorToMcp(error, toolName);
+            }
+            return mapSdkErrorToMcp(error, toolName);
+        }
+    };
+}
+//# sourceMappingURL=tool-handler.js.map

package/dist/utils/tool-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-handler.js","sourceRoot":"","sources":["../../src/utils/tool-handler.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@uluops/ops-mcp",
+  "version": "0.2.1",
+  "description": "MCP server for the UluOps Platform API — validation tracking, analytics, and issue management",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "uluops-ops-mcp": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "tool-policies.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "clean": "rm -rf dist",
+    "prebuild": "npm run clean",
+    "postbuild": "chmod +x dist/index.js",
+    "lint": "eslint src/",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:unit": "vitest run test/unit",
+    "test:integration": "vitest run test/integration",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "uluops",
+    "validation",
+    "analytics",
+    "claude",
+    "claude-code",
+    "model-context-protocol"
+  ],
+  "author": "aself101",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Uluops/ops-uluops-mcp.git"
+  },
+  "homepage": "https://github.com/Uluops/ops-uluops-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/Uluops/ops-uluops-mcp/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "@uluops/ops-sdk": "3.1.0",
+    "mcp-secure-server": "0.0.14-security",
+    "zod": "3.25.76"
+  },
+  "devDependencies": {
+    "@eslint/js": "9.39.4",
+    "@types/node": "22.19.19",
+    "@typescript-eslint/eslint-plugin": "8.59.4",
+    "@typescript-eslint/parser": "8.59.4",
+    "@vitest/coverage-v8": "2.1.9",
+    "eslint": "9.39.4",
+    "prettier": "3.8.3",
+    "tsx": "4.22.3",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.59.4",
+    "vitest": "2.1.9"
+  }
+}

package/tool-policies.json

@@ -0,0 +1,96 @@
+{
+  "version": "2.0",
+  "tools": {
+    "save_run": {
+      "level": "STORAGE",
+      "relaxedFields": ["description", "title", "recommendations", "file_path", "raw_markdown"],
+      "description": "Stores validation results - may contain code snippets in markdown"
+    },
+    "validate_run": {
+      "level": "STORAGE",
+      "relaxedFields": ["description", "title", "recommendations", "file_path", "raw_markdown"],
+      "description": "Previews validation results - may contain code snippets in markdown"
+    },
+    "create_issue": {
+      "level": "STORAGE",
+      "relaxedFields": ["description", "title", "file_path"],
+      "description": "Creates issues - file paths may reference sensitive files being reported on"
+    },
+    "add_issue_note": {
+      "level": "STORAGE",
+      "relaxedFields": ["content", "issue_id"],
+      "description": "Issue notes may contain code snippets. issue_id is UUID (can trigger CC false positive)"
+    },
+    "update_status": {
+      "level": "STORAGE",
+      "relaxedFields": ["updates", "id", "issue_id", "fingerprint", "reason"],
+      "description": "Status updates contain UUIDs that can trigger credit card pattern false positives"
+    },
+    "bulk_update_status": {
+      "level": "STORAGE",
+      "relaxedFields": ["updates", "id", "issue_id", "reason"],
+      "description": "Bulk status updates contain UUIDs that can trigger credit card pattern false positives"
+    },
+    "get_issue_details": {
+      "level": "QUERY",
+      "relaxedFields": ["id"],
+      "description": "Issue ID is UUID that can trigger credit card pattern false positives"
+    },
+    "get_issue_history": {
+      "level": "QUERY",
+      "relaxedFields": ["issue_id"],
+      "description": "Issue ID is UUID that can trigger credit card pattern false positives"
+    },
+    "edit_issue": {
+      "level": "STORAGE",
+      "relaxedFields": ["issue_id", "title", "file_path", "category"],
+      "description": "Edit issue metadata - issue_id is UUID"
+    },
+    "merge_issues": {
+      "level": "STORAGE",
+      "relaxedFields": ["target_issue_id", "source_issue_ids"],
+      "description": "Merge issues - IDs are UUIDs that can trigger credit card pattern false positives"
+    },
+    "update_run": {
+      "level": "STORAGE",
+      "relaxedFields": ["raw_markdown", "validators"],
+      "description": "Update run metadata - raw_markdown may contain code snippets"
+    },
+    "soft_delete_project": {
+      "level": "STORAGE",
+      "relaxedFields": ["confirmation_phrase"],
+      "description": "Soft delete project - confirmation_phrase is user-provided text"
+    },
+    "delete_run": {
+      "level": "STORAGE",
+      "relaxedFields": ["run_id"],
+      "description": "Delete run - run_id is UUID that can trigger false positives"
+    },
+    "get_run": {
+      "level": "QUERY",
+      "relaxedFields": ["run_id"],
+      "description": "Get run by UUID - run_id can trigger credit card pattern false positives"
+    },
+    "update_issue_by_fingerprint": {
+      "level": "STORAGE",
+      "relaxedFields": ["fingerprint", "reason"],
+      "description": "Update issue by fingerprint - fingerprint is SHA-256 hash"
+    },
+    "get_issue_by_fingerprint": {
+      "level": "QUERY",
+      "relaxedFields": ["fingerprint"],
+      "description": "Get issue by fingerprint - fingerprint is SHA-256 hash"
+    },
+    "restore_issue": {
+      "level": "STORAGE",
+      "relaxedFields": ["issue_id"],
+      "description": "Restore issue - issue_id is UUID"
+    },
+    "undo_issue_status": {
+      "level": "STORAGE",
+      "relaxedFields": ["issue_id"],
+      "description": "Undo issue status - issue_id is UUID"
+    }
+  },
+  "defaultLevel": "QUERY"
+}