@uluops/ops-mcp 0.2.1

package/dist/client/sdk-error-mapper.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Error mapper for converting SDK errors to MCP-safe responses
+ *
+ * Maps @uluops/ops-sdk error hierarchy to sanitized MCP tool responses.
+ * Strips actual credentials (API keys, bearer tokens) before exposure
+ * while preserving field names, validation details, and actionable context.
+ */
+import type { McpToolResponse } from '../types/index.js';
+/**
+ * Map an SDK error to an MCP tool response.
+ *
+ * Preserves error context including:
+ * - Original error messages (with credential redaction only)
+ * - HTTP status codes when available
+ * - Retry-after information for rate limits
+ * - Field-level validation details
+ */
+export declare function mapSdkErrorToMcp(error: unknown, toolName?: string): McpToolResponse;
+/**
+ * Map a Zod validation error to an MCP tool response.
+ * Shows all validation errors with field paths and expected values.
+ */
+export declare function mapZodErrorToMcp(error: unknown, toolName?: string): McpToolResponse;
+//# sourceMappingURL=sdk-error-mapper.d.ts.map

package/dist/client/sdk-error-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-error-mapper.d.ts","sourceRoot":"","sources":["../../src/client/sdk-error-mapper.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAcH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAiGzD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,eAAe,CAuInF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,eAAe,CAoBnF"}

package/dist/client/sdk-error-mapper.js

@@ -0,0 +1,205 @@
+/**
+ * Error mapper for converting SDK errors to MCP-safe responses
+ *
+ * Maps @uluops/ops-sdk error hierarchy to sanitized MCP tool responses.
+ * Strips actual credentials (API keys, bearer tokens) before exposure
+ * while preserving field names, validation details, and actionable context.
+ */
+import { isOpsApiError, isNotFoundError, isRateLimitError, isValidationError, isNetworkError, isTimeoutError, UnauthorizedError, ForbiddenError, isConflictError, isUnprocessableError, } from '@uluops/ops-sdk/errors';
+const MAX_ERROR_MESSAGE_LENGTH = 1000;
+/**
+ * Patterns that indicate actual credential values in error messages.
+ * Only matches credential values, not field names that mention credentials.
+ */
+const CREDENTIAL_PATTERNS = [
+    // Actual key/token values (not field names)
+    /(?:api[_-]?key|apiKey)\s*[:=]\s*\S+/i,
+    /bearer\s+[a-zA-Z0-9_\-.]+/i,
+    /authorization:\s*\S+/i,
+    /ulr_[a-zA-Z0-9]{20,}/,
+    // Token/secret assignments with actual values
+    /(?:token|secret)\s*[:=]\s*\S+/i,
+    // Stack traces (internal implementation details)
+    /at\s+\S+\s+\(\S+:\d+:\d+\)/,
+];
+/**
+ * Check if a message contains actual credential values
+ */
+function containsCredentials(message) {
+    return CREDENTIAL_PATTERNS.some((pattern) => pattern.test(message));
+}
+/**
+ * Redact credential values from a message while preserving the rest.
+ * Returns the original message with only credential values replaced.
+ */
+function redactCredentials(message) {
+    let redacted = message;
+    for (const pattern of CREDENTIAL_PATTERNS) {
+        redacted = redacted.replace(pattern, '[REDACTED]');
+    }
+    return redacted;
+}
+/**
+ * Sanitize an error message for safe client exposure.
+ * Redacts credentials and truncates if needed, but preserves all other context.
+ */
+function sanitizeErrorMessage(message) {
+    let safe = containsCredentials(message) ? redactCredentials(message) : message;
+    if (safe.length > MAX_ERROR_MESSAGE_LENGTH) {
+        safe = safe.slice(0, MAX_ERROR_MESSAGE_LENGTH) + '... (truncated)';
+    }
+    return safe;
+}
+/**
+ * Extract HTTP status code from SDK errors when available
+ */
+function getStatusCode(error) {
+    if (error && typeof error === 'object' && 'statusCode' in error) {
+        return error.statusCode;
+    }
+    return undefined;
+}
+/** Actionable suggestions per error type to help MCP clients self-correct. */
+const ERROR_SUGGESTIONS = {
+    NotFoundError: 'Verify the resource ID/name exists. Use a query or list tool to find valid identifiers.',
+    RateLimitError: 'Wait for the retry_after_seconds period, then retry.',
+    ValidationError: 'Check parameter types and required fields against the tool schema.',
+    UnauthorizedError: 'Verify ULUOPS_API_KEY is set to a valid ulr_* key.',
+    ForbiddenError: 'This operation requires elevated permissions or a different subscription tier.',
+    NetworkError: 'The API server may be down. Check that the service is running.',
+    TimeoutError: 'The request took too long. Try reducing payload size or increasing timeout.',
+    ConflictError: 'The resource was modified concurrently. Refresh and retry.',
+    UnprocessableError: 'The request is well-formed but cannot be processed. Check business logic constraints.',
+    InputValidationError: 'SDK-level validation failed before reaching the API. Check input shapes.',
+};
+/**
+ * Build a structured error response with context for MCP clients.
+ */
+function buildErrorResponse(message, metadata) {
+    const payload = { error: message };
+    if (metadata) {
+        Object.assign(payload, metadata);
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(payload) }],
+        isError: true,
+    };
+}
+function getErrorTypeName(error) {
+    if (error instanceof Error)
+        return error.constructor.name;
+    return 'unknown';
+}
+/**
+ * Map an SDK error to an MCP tool response.
+ *
+ * Preserves error context including:
+ * - Original error messages (with credential redaction only)
+ * - HTTP status codes when available
+ * - Retry-after information for rate limits
+ * - Field-level validation details
+ */
+export function mapSdkErrorToMcp(error, toolName) {
+    const statusCode = getStatusCode(error);
+    const errorType = getErrorTypeName(error);
+    const suggestion = ERROR_SUGGESTIONS[errorType];
+    const context = {
+        ...(statusCode ? { status: statusCode } : {}),
+        error_type: errorType,
+        ...(toolName ? { tool: toolName } : {}),
+        ...(suggestion ? { suggestion } : {}),
+    };
+    if (isNotFoundError(error)) {
+        return buildErrorResponse(sanitizeErrorMessage(error.message || 'Resource not found'), context);
+    }
+    if (isRateLimitError(error)) {
+        const retryAfter = error.retryAfter;
+        return buildErrorResponse(retryAfter
+            ? `Rate limit exceeded. Retry after ${String(retryAfter)} seconds.`
+            : 'Rate limit exceeded, please retry later.', { ...context, status: 429, ...(retryAfter ? { retry_after_seconds: retryAfter } : {}) });
+    }
+    if (isValidationError(error)) {
+        return buildErrorResponse(sanitizeErrorMessage(error.message || 'Invalid request parameters'), context);
+    }
+    if (error instanceof UnauthorizedError) {
+        return buildErrorResponse('Authentication required. Verify ULUOPS_API_KEY is set to a valid ulr_* key.', { ...context, status: 401 });
+    }
+    if (error instanceof ForbiddenError) {
+        return buildErrorResponse(sanitizeErrorMessage(error.message || 'Access denied'), { ...context, status: 403 });
+    }
+    if (isNetworkError(error)) {
+        return buildErrorResponse(sanitizeErrorMessage(error.message || 'Network error: verify the API server is running'), context);
+    }
+    if (isTimeoutError(error)) {
+        return buildErrorResponse(sanitizeErrorMessage(error.message || 'Request timed out. Consider increasing ULUOPS_TRACKER_TIMEOUT.'), context);
+    }
+    // 402 Subscription Required — run submission tier gating (spec Section 9.2)
+    if (statusCode === 402) {
+        const rawDetails = error.details;
+        const details = typeof rawDetails === 'object' && rawDetails !== null
+            ? rawDetails
+            : {};
+        const defs = Array.isArray(details['definitions'])
+            ? details['definitions'].filter((d) => typeof d === 'object' && d !== null)
+            : undefined;
+        const currentTier = typeof details['currentTier'] === 'string' ? details['currentTier'] : undefined;
+        const upgradeUrl = typeof details['upgradeUrl'] === 'string' ? details['upgradeUrl'] : undefined;
+        const sep = upgradeUrl?.includes('?') ? '&' : '?';
+        const trackedUrl = upgradeUrl ? `${upgradeUrl}${sep}source=mcp` : undefined;
+        const defList = defs?.map(d => {
+            const name = typeof d['name'] === 'string' ? d['name'] : 'unknown';
+            const tier = typeof d['requiredTier'] === 'string' ? d['requiredTier'] : 'unknown';
+            return `${name} (requires ${tier})`;
+        }).join(', ') ?? 'above-tier definitions';
+        return buildErrorResponse(`Subscription required. Run references: ${defList}.` +
+            (currentTier ? ` Your current tier: ${currentTier}.` : '') +
+            (trackedUrl ? ` Upgrade: ${trackedUrl}` : ''), {
+            ...context,
+            status: 402,
+            ...(currentTier ? { current_tier: currentTier } : {}),
+            ...(defs ? { rejected_definitions: defs } : {}),
+            ...(trackedUrl ? { upgrade_url: trackedUrl } : {}),
+        });
+    }
+    if (isConflictError(error)) {
+        return buildErrorResponse(sanitizeErrorMessage(error.message || 'Resource conflict'), {
+            ...context,
+            status: error.statusCode,
+            ...error.details,
+        });
+    }
+    if (isUnprocessableError(error)) {
+        return buildErrorResponse(sanitizeErrorMessage(error.message || 'Unprocessable request'), context);
+    }
+    if (isOpsApiError(error)) {
+        return buildErrorResponse(sanitizeErrorMessage(error.message), context);
+    }
+    if (error instanceof Error) {
+        return buildErrorResponse(sanitizeErrorMessage(error.message), context);
+    }
+    return buildErrorResponse('An unexpected error occurred', context);
+}
+/**
+ * Map a Zod validation error to an MCP tool response.
+ * Shows all validation errors with field paths and expected values.
+ */
+export function mapZodErrorToMcp(error, toolName) {
+    let message = 'Invalid input parameters';
+    if (error instanceof Error) {
+        const zodError = error;
+        if (zodError.errors && Array.isArray(zodError.errors)) {
+            const details = zodError.errors
+                .map((e) => `${e.path.join('.')}: ${e.message}`)
+                .join('; ');
+            const count = zodError.errors.length;
+            message = `Validation failed (${String(count)} error${count > 1 ? 's' : ''}): ${details}`;
+        }
+    }
+    return buildErrorResponse(message, {
+        status: 400,
+        error_type: 'ZodValidationError',
+        ...(toolName ? { tool: toolName } : {}),
+        suggestion: 'Check parameter types and required fields against the tool schema.',
+    });
+}
+//# sourceMappingURL=sdk-error-mapper.js.map

package/dist/client/sdk-error-mapper.js.map

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

package/dist/config/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Configuration loader for @uluops/ops-mcp.
+ *
+ * Loads configuration from environment variables with sensible defaults.
+ */
+import type { UluopsTrackerConfig } from '../types/index.js';
+/**
+ * Load configuration from environment variables.
+ *
+ * @returns Object with `config` and `warnings` (deprecation messages for deferred logging)
+ */
+export declare function loadConfig(): {
+    config: UluopsTrackerConfig;
+    warnings: string[];
+};
+/**
+ * Build a short, redacted fingerprint for the API key so operators can
+ * distinguish which key the server loaded across multiple deployments
+ * without leaking the secret. Returns "ulr_…XXXX" using the last 4 chars.
+ */
+export declare function apiKeyFingerprint(apiKey: string | undefined): string;
+/**
+ * Validate that required configuration is present and well-formed.
+ */
+export declare function validateConfig(config: UluopsTrackerConfig): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAY,MAAM,mBAAmB,CAAC;AA2CvE;;;;GAIG;AACH,wBAAgB,UAAU,IAAI;IAAE,MAAM,EAAE,mBAAmB,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAuChF;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAGpE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI,CA+BhE"}

package/dist/config/index.js

@@ -0,0 +1,121 @@
+/**
+ * Configuration loader for @uluops/ops-mcp.
+ *
+ * Loads configuration from environment variables with sensible defaults.
+ */
+const DEFAULT_BASE_URL = 'https://api.uluops.ai/api/v1';
+const DEFAULT_TIMEOUT = 30000;
+const DEFAULT_RETRIES = 3;
+const DEFAULT_LOG_LEVEL = 'info';
+/**
+ * Parse a log level string, returning a valid LogLevel.
+ * @param value - Raw string from environment variable
+ * @returns Valid LogLevel, defaults to 'info' if undefined or invalid
+ */
+function parseLogLevel(value) {
+    const validLevels = ['debug', 'info', 'warn', 'error'];
+    if (value !== undefined && value !== '' && validLevels.includes(value)) {
+        return value;
+    }
+    return DEFAULT_LOG_LEVEL;
+}
+/**
+ * Parse a boolean environment variable ('true'/'1' = true).
+ * @param value - Raw string from environment variable
+ * @param defaultValue - Value to return if undefined
+ * @returns Parsed boolean or default
+ */
+function parseBoolean(value, defaultValue) {
+    if (value === undefined)
+        return defaultValue;
+    return value.toLowerCase() === 'true' || value === '1';
+}
+/**
+ * Parse an integer environment variable (base 10).
+ * @param value - Raw string from environment variable
+ * @param defaultValue - Value to return if undefined or NaN
+ * @returns Parsed integer or default
+ */
+function parseInteger(value, defaultValue) {
+    if (value === undefined)
+        return defaultValue;
+    const parsed = parseInt(value, 10);
+    return isNaN(parsed) ? defaultValue : parsed;
+}
+/**
+ * Load configuration from environment variables.
+ *
+ * @returns Object with `config` and `warnings` (deprecation messages for deferred logging)
+ */
+export function loadConfig() {
+    const warnings = [];
+    const apiUrl = process.env['ULUOPS_BASE_URL'] ?? DEFAULT_BASE_URL;
+    const apiKey = process.env['ULUOPS_API_KEY'];
+    const orgSlug = process.env['ULUOPS_ORG_SLUG'];
+    const config = {
+        api: {
+            baseUrl: apiUrl,
+            apiKey,
+            orgSlug,
+            timeout: parseInteger(process.env['ULUOPS_TRACKER_TIMEOUT'], DEFAULT_TIMEOUT),
+            retries: parseInteger(process.env['ULUOPS_TRACKER_RETRIES'], DEFAULT_RETRIES),
+        },
+        security: {
+            logLevel: parseLogLevel(process.env['LOG_LEVEL']),
+            enableLogging: parseBoolean(process.env['ENABLE_FILE_LOGGING'], false),
+            logDir: process.env['LOG_DIR'],
+            verboseLogging: parseBoolean(process.env['VERBOSE_LOGGING'], false),
+            logPerformanceMetrics: parseBoolean(process.env['LOG_PERFORMANCE_METRICS'], false),
+        },
+    };
+    // Warn on non-HTTPS base URL outside development — ULUOPS_API_KEY would be
+    // transmitted in cleartext.
+    try {
+        const parsed = new URL(apiUrl);
+        if (parsed.protocol !== 'https:' && process.env['NODE_ENV'] !== 'development') {
+            warnings.push(`ULUOPS_BASE_URL uses ${parsed.protocol} (not HTTPS). Your API key will be transmitted in cleartext. Set NODE_ENV=development to silence this warning for local testing.`);
+        }
+    }
+    catch {
+        // URL parse failure is handled in validateConfig with a clearer error.
+    }
+    return { config, warnings };
+}
+/**
+ * Build a short, redacted fingerprint for the API key so operators can
+ * distinguish which key the server loaded across multiple deployments
+ * without leaking the secret. Returns "ulr_…XXXX" using the last 4 chars.
+ */
+export function apiKeyFingerprint(apiKey) {
+    if (apiKey === undefined || apiKey.length < 4)
+        return 'unknown';
+    return `ulr_…${apiKey.slice(-4)}`;
+}
+/**
+ * Validate that required configuration is present and well-formed.
+ */
+export function validateConfig(config) {
+    if (!config.api.baseUrl) {
+        throw new Error('API base URL is required');
+    }
+    // Validate URL format
+    try {
+        new URL(config.api.baseUrl);
+    }
+    catch {
+        throw new Error(`Invalid API URL: ${config.api.baseUrl}`);
+    }
+    if (config.api.apiKey === undefined || config.api.apiKey === '') {
+        throw new Error('API key is required. Set ULUOPS_API_KEY to a value starting with "ulr_" (min 20 chars).');
+    }
+    if (!/^ulr_[A-Za-z0-9_-]{16,}$/.test(config.api.apiKey)) {
+        throw new Error('ULUOPS_API_KEY must start with "ulr_" and be at least 20 characters. Check for typos or leading whitespace.');
+    }
+    if (config.api.timeout <= 0) {
+        throw new Error('Timeout must be a positive number');
+    }
+    if (config.api.retries < 0) {
+        throw new Error('Retries must be a non-negative number');
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/config/index.js.map

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

package/dist/config/tool-registry.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Tool Registry Configuration
+ *
+ * Per-tool security policies for the MCP server.
+ * Required by mcp-secure-server's semantic validation layer.
+ *
+ * Since this is a thin client adapter (security enforced at API layer),
+ * we use permissive defaults with generous limits.
+ */
+import type { ToolSpec } from 'mcp-secure-server';
+/**
+ * All uluops-tracker tools (P0 + P1 + P2)
+ *
+ * Limits are set high since:
+ * 1. Security is enforced at the API layer
+ * 2. Claude Code is trusted automation
+ * 3. Validation workflows can produce large payloads
+ *
+ * Quota rationale (per-tool rate limits):
+ * - quotaPerMinute: 240 for reads (4/sec), 120 for writes (2/sec), 60 for bulk ops
+ * - quotaPerHour: 5000 for frequent reads, 2000 for writes, 1000 for batch ops
+ * - Destructive ops (delete_*): 10/min, 50/hr to prevent accidental mass deletion
+ */
+export declare const toolRegistry: ToolSpec[];
+//# sourceMappingURL=tool-registry.d.ts.map

package/dist/config/tool-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-registry.d.ts","sourceRoot":"","sources":["../../src/config/tool-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAMlD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,YAAY,EAAE,QAAQ,EAialC,CAAC"}