@utaba/ucm-mcp-server 1.0.0

package/dist/utils/McpErrorHandler.js

@@ -0,0 +1,67 @@
+// MCP-specific error handling following MCP standards
+export var McpErrorCode;
+(function (McpErrorCode) {
+    McpErrorCode[McpErrorCode["ParseError"] = -32700] = "ParseError";
+    McpErrorCode[McpErrorCode["InvalidRequest"] = -32600] = "InvalidRequest";
+    McpErrorCode[McpErrorCode["MethodNotFound"] = -32601] = "MethodNotFound";
+    McpErrorCode[McpErrorCode["InvalidParams"] = -32602] = "InvalidParams";
+    McpErrorCode[McpErrorCode["InternalError"] = -32603] = "InternalError";
+    McpErrorCode[McpErrorCode["ExternalServiceUnavailable"] = -32001] = "ExternalServiceUnavailable"; // External resource offline/unavailable
+})(McpErrorCode || (McpErrorCode = {}));
+export class McpError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+        this.name = 'McpError';
+    }
+    toResponse() {
+        return {
+            error: {
+                code: this.code,
+                message: this.message,
+                data: this.data
+            }
+        };
+    }
+}
+export class McpErrorHandler {
+    static formatError(error) {
+        if (error instanceof McpError) {
+            return error;
+        }
+        if (error.error) {
+            error = error.error;
+        }
+        if (error instanceof McpError) {
+            return error;
+        }
+        // Extract error message from various sources
+        let message = error.message || error.toString();
+        if (!message) {
+            message = JSON.stringify(error);
+        }
+        // Map common errors to MCP error codes
+        if (message?.includes('not found')) {
+            return new McpError(McpErrorCode.InvalidParams, message, { originalError: error });
+        }
+        if (message?.includes('validation')) {
+            return new McpError(McpErrorCode.InvalidParams, 'Parameter validation failed', { originalError: error });
+        }
+        if (message?.includes('ECONNREFUSED')) {
+            return new McpError(McpErrorCode.ExternalServiceUnavailable, 'External API is unavailable, try the mcp_ucm_health_check tool', { originalError: error });
+        }
+        if (message?.includes('validation') || message?.includes('invalid') ||
+            message?.includes('required') || message?.includes('must be')) {
+            return new McpError(McpErrorCode.InvalidParams, message, { originalError: error });
+        }
+        if (message?.includes('UCM API server error')) {
+            return new McpError(McpErrorCode.InternalError, message, { originalError: error });
+        }
+        // Don't leak internal errors
+        return new McpError(McpErrorCode.InternalError, message || 'An internal error occurred');
+    }
+}
+//# sourceMappingURL=McpErrorHandler.js.map

package/dist/utils/PathUtils.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Utility functions for parsing UCM paths into component parts
+ */
+export interface ParsedPath {
+    author?: string | undefined;
+    repository?: string | undefined;
+    category?: string | undefined;
+    subcategory?: string | undefined;
+    filename?: string;
+    version?: string;
+}
+/**
+ * Parse a UCM path into its component parts
+ * Supports formats like:
+ * - "utaba/main/commands/user" (namespace only)
+ * - "utaba/main/commands/user/CreateUserCommand.ts" (with filename)
+ * - "utaba/main/commands/user/CreateUserCommand.ts@1.0.0" (with version)
+ */
+export declare function parsePath(path: string): ParsedPath;
+/**
+ * Build a namespace path from components (author/repository/category/subcategory)
+ */
+export declare function buildNamespacePath(author: string, repository: string, category: string, subcategory: string): string;
+/**
+ * Build a full path with filename and optional version
+ */
+export declare function buildFullPath(author: string, repository: string, category: string, subcategory: string, filename?: string, version?: string): string;
+/**
+ * Extract namespace from a full path
+ */
+export declare function extractNamespace(path: string): string;
+/**
+ * Validate if a path follows UCM naming conventions
+ */
+export declare function validatePath(path: string): {
+    isValid: boolean;
+    errors: string[];
+};
+/**
+ * Compare two semantic versions
+ * Returns: -1 if version1 < version2, 0 if equal, 1 if version1 > version2
+ */
+export declare function compareVersions(version1: string, version2: string): number;
+/**
+ * Check if a version is greater than another version
+ */
+export declare function isVersionGreater(version1: string, version2: string): boolean;
+/**
+ * Check if a version is less than another version
+ */
+export declare function isVersionLess(version1: string, version2: string): boolean;
+/**
+ * Check if two versions are equal
+ */
+export declare function isVersionEqual(version1: string, version2: string): boolean;
+/**
+ * Increment the patch version of a semantic version
+ * Examples: 1.0.0 -> 1.0.1, 2.1.5 -> 2.1.6
+ */
+export declare function incrementPatchVersion(version: string): string;
+//# sourceMappingURL=PathUtils.d.ts.map

package/dist/utils/PathUtils.js

@@ -0,0 +1,178 @@
+/**
+ * Utility functions for parsing UCM paths into component parts
+ */
+/**
+ * Parse a UCM path into its component parts
+ * Supports formats like:
+ * - "utaba/main/commands/user" (namespace only)
+ * - "utaba/main/commands/user/CreateUserCommand.ts" (with filename)
+ * - "utaba/main/commands/user/CreateUserCommand.ts@1.0.0" (with version)
+ */
+export function parsePath(path) {
+    if (!path)
+        path = "";
+    // Remove leading/trailing slashes
+    const cleanPath = path.replace(/^\/+|\/+$/g, '');
+    // Split into parts
+    const parts = cleanPath.split('/');
+    const result = {
+        author: parts.length > 0 ? parts[0] : undefined,
+        repository: parts.length > 1 ? parts[1] : undefined,
+        category: parts.length > 2 ? parts[2] : undefined,
+        subcategory: parts.length > 3 ? parts[3] : undefined,
+    };
+    if (parts.length > 4) {
+        let filenameParts = parts[4].split('@');
+        //filename
+        result.filename = filenameParts[0];
+        if (filenameParts.length > 1) {
+            result.version = filenameParts[1];
+        }
+    }
+    return result;
+}
+/**
+ * Build a namespace path from components (author/repository/category/subcategory)
+ */
+export function buildNamespacePath(author, repository, category, subcategory) {
+    return `${author}/${repository}/${category}/${subcategory}`;
+}
+/**
+ * Build a full path with filename and optional version
+ */
+export function buildFullPath(author, repository, category, subcategory, filename, version) {
+    let path = buildNamespacePath(author, repository, category, subcategory);
+    if (filename) {
+        path += `/${filename}`;
+        if (version) {
+            path += `@${version}`;
+        }
+    }
+    return path;
+}
+/**
+ * Extract namespace from a full path
+ */
+export function extractNamespace(path) {
+    const parsed = parsePath(path);
+    return buildNamespacePath(parsed.author || '', parsed.repository || '', parsed.category || '', parsed.subcategory || '');
+}
+/**
+ * Validate if a path follows UCM naming conventions
+ */
+export function validatePath(path) {
+    const errors = [];
+    try {
+        const parsed = parsePath(path);
+        // Validate author (lowercase alphanumeric and hyphens)
+        if (!/^[a-z0-9-]+$/.test(parsed.author || '')) {
+            errors.push('Author must contain only lowercase letters, numbers, and hyphens');
+        }
+        // Validate repository (lowercase alphanumeric and hyphens)
+        if (!/^[a-z0-9-]+$/.test(parsed.repository || '')) {
+            errors.push('Repository must contain only lowercase letters, numbers, and hyphens');
+        }
+        // Validate category (must be valid UCM category)
+        const validCategories = ['commands', 'services', 'patterns', 'implementations', 'contracts', 'guidance', 'project'];
+        if (!validCategories.includes(parsed.category || '')) {
+            errors.push(`Category must be one of: ${validCategories.join(', ')}`);
+        }
+        // Validate subcategory (lowercase alphanumeric and hyphens)
+        if (!/^[a-z0-9-]+$/.test(parsed.subcategory || '')) {
+            errors.push('Subcategory must contain only lowercase letters, numbers, and hyphens');
+        }
+        // Validate filename if present
+        if (parsed.filename) {
+            if (!/^[a-zA-Z0-9._-]+\.[a-z]+$/.test(parsed.filename)) {
+                errors.push('Filename must be valid with an extension');
+            }
+        }
+        // Validate version if present
+        if (parsed.version) {
+            if (!/^v?\d+\.\d+\.\d+(-[a-z0-9-]+)?(\+[a-z0-9-]+)?$/.test(parsed.version)) {
+                errors.push('Version must follow semantic versioning (e.g., 1.0.0, v2.1.0)');
+            }
+        }
+    }
+    catch (error) {
+        errors.push(error instanceof Error ? error.message : 'Invalid path format');
+    }
+    return {
+        isValid: errors.length === 0,
+        errors
+    };
+}
+/**
+ * Compare two semantic versions
+ * Returns: -1 if version1 < version2, 0 if equal, 1 if version1 > version2
+ */
+export function compareVersions(version1, version2) {
+    // Normalize versions by removing 'v' prefix if present
+    const v1 = version1.replace(/^v/, '');
+    const v2 = version2.replace(/^v/, '');
+    // Split versions into parts
+    const parts1 = v1.split(/[.-]/);
+    const parts2 = v2.split(/[.-]/);
+    // Compare major, minor, patch
+    for (let i = 0; i < 3; i++) {
+        const num1 = parseInt(parts1[i] || '0', 10);
+        const num2 = parseInt(parts2[i] || '0', 10);
+        if (num1 > num2)
+            return 1;
+        if (num1 < num2)
+            return -1;
+    }
+    // If major.minor.patch are equal, compare pre-release versions
+    const preRelease1 = parts1.slice(3).join('.');
+    const preRelease2 = parts2.slice(3).join('.');
+    // No pre-release is greater than pre-release
+    if (!preRelease1 && preRelease2)
+        return 1;
+    if (preRelease1 && !preRelease2)
+        return -1;
+    if (!preRelease1 && !preRelease2)
+        return 0;
+    // Compare pre-release versions lexically
+    return preRelease1.localeCompare(preRelease2);
+}
+/**
+ * Check if a version is greater than another version
+ */
+export function isVersionGreater(version1, version2) {
+    return compareVersions(version1, version2) > 0;
+}
+/**
+ * Check if a version is less than another version
+ */
+export function isVersionLess(version1, version2) {
+    return compareVersions(version1, version2) < 0;
+}
+/**
+ * Check if two versions are equal
+ */
+export function isVersionEqual(version1, version2) {
+    return compareVersions(version1, version2) === 0;
+}
+/**
+ * Increment the patch version of a semantic version
+ * Examples: 1.0.0 -> 1.0.1, 2.1.5 -> 2.1.6
+ */
+export function incrementPatchVersion(version) {
+    // Normalize version by removing 'v' prefix if present
+    const normalized = version.replace(/^v/, '');
+    // Split version into parts
+    const parts = normalized.split('.');
+    if (parts.length < 3) {
+        throw new Error(`Invalid semantic version format: ${version}`);
+    }
+    // Parse major, minor, patch
+    const major = parseInt(parts[0], 10);
+    const minor = parseInt(parts[1], 10);
+    const patch = parseInt(parts[2].split('-')[0], 10); // Handle pre-release versions
+    if (isNaN(major) || isNaN(minor) || isNaN(patch)) {
+        throw new Error(`Invalid semantic version format: ${version}`);
+    }
+    // Increment patch version
+    return `${major}.${minor}.${patch + 1}`;
+}
+//# sourceMappingURL=PathUtils.js.map

package/dist/utils/ResponseChunker.d.ts

@@ -0,0 +1,25 @@
+export interface ChunkedResponse {
+    chunk: {
+        id: string;
+        sequence: number;
+        total: number;
+        data: string;
+    };
+    hasMore: boolean;
+}
+export declare class ResponseChunker {
+    private static readonly MAX_CHUNK_SIZE;
+    private static chunks;
+    private static readonly CHUNK_TTL;
+    private static chunkTimestamps;
+    static chunk(data: any, chunkId?: string): ChunkedResponse | any;
+    static getNextChunk(chunkId: string, sequence: number): ChunkedResponse | null;
+    static cleanup(chunkId: string): void;
+    static cleanupExpired(): void;
+    static getChunkInfo(chunkId: string): {
+        exists: boolean;
+        total?: number;
+        expires?: number;
+    };
+}
+//# sourceMappingURL=ResponseChunker.d.ts.map

package/dist/utils/ResponseChunker.js

@@ -0,0 +1,79 @@
+export class ResponseChunker {
+    static MAX_CHUNK_SIZE = 20000; // ~20k characters to stay under token limit
+    static chunks = new Map();
+    static CHUNK_TTL = 5 * 60 * 1000; // 5 minutes
+    static chunkTimestamps = new Map();
+    static chunk(data, chunkId) {
+        const serialized = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
+        // If small enough, return as-is
+        if (serialized.length < this.MAX_CHUNK_SIZE) {
+            return data;
+        }
+        // Generate chunk ID if not provided
+        const id = chunkId || `ucm_chunk_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
+        // Split into chunks
+        const chunks = [];
+        for (let i = 0; i < serialized.length; i += this.MAX_CHUNK_SIZE) {
+            chunks.push(serialized.slice(i, i + this.MAX_CHUNK_SIZE));
+        }
+        // Store chunks for retrieval with timestamp
+        this.chunks.set(id, chunks);
+        this.chunkTimestamps.set(id, Date.now());
+        // Schedule cleanup after TTL
+        setTimeout(() => {
+            this.cleanup(id);
+        }, this.CHUNK_TTL);
+        // Return first chunk with metadata
+        return {
+            chunk: {
+                id,
+                sequence: 0,
+                total: chunks.length,
+                data: chunks[0]
+            },
+            hasMore: chunks.length > 1
+        };
+    }
+    static getNextChunk(chunkId, sequence) {
+        const chunks = this.chunks.get(chunkId);
+        if (!chunks || sequence >= chunks.length || sequence < 0) {
+            return null;
+        }
+        // Update timestamp to extend TTL
+        this.chunkTimestamps.set(chunkId, Date.now());
+        return {
+            chunk: {
+                id: chunkId,
+                sequence,
+                total: chunks.length,
+                data: chunks[sequence]
+            },
+            hasMore: sequence < chunks.length - 1
+        };
+    }
+    static cleanup(chunkId) {
+        this.chunks.delete(chunkId);
+        this.chunkTimestamps.delete(chunkId);
+    }
+    static cleanupExpired() {
+        const now = Date.now();
+        for (const [id, timestamp] of this.chunkTimestamps.entries()) {
+            if (now - timestamp > this.CHUNK_TTL) {
+                this.cleanup(id);
+            }
+        }
+    }
+    static getChunkInfo(chunkId) {
+        const chunks = this.chunks.get(chunkId);
+        const timestamp = this.chunkTimestamps.get(chunkId);
+        if (!chunks || !timestamp) {
+            return { exists: false };
+        }
+        return {
+            exists: true,
+            total: chunks.length,
+            expires: timestamp + this.CHUNK_TTL
+        };
+    }
+}
+//# sourceMappingURL=ResponseChunker.js.map

package/dist/utils/ValidationUtils.d.ts

@@ -0,0 +1,10 @@
+export declare class ValidationUtils {
+    static validateArtifactPath(path: string): void;
+    static sanitizeSearchQuery(query: string): string;
+    static validateContentSize(content: string, maxSize?: number): void;
+    static validatePageParams(offset?: number, limit?: number): void;
+    static validateAuthorId(authorId: string): void;
+    static validateCategory(category: string): void;
+    static validateVersion(version: string): void;
+}
+//# sourceMappingURL=ValidationUtils.d.ts.map

package/dist/utils/ValidationUtils.js

@@ -0,0 +1,50 @@
+import { McpError, McpErrorCode } from './McpErrorHandler.js';
+export class ValidationUtils {
+    static validateArtifactPath(path) {
+        // Prevent path traversal
+        if (path.includes('..') || path.includes('//')) {
+            throw new McpError(McpErrorCode.InvalidParams, 'Invalid artifact path');
+        }
+    }
+    static sanitizeSearchQuery(query) {
+        // Remove potentially dangerous characters
+        return query.replace(/[<>\"'&]/g, '').trim();
+    }
+    static validateContentSize(content, maxSize = 1024 * 1024) {
+        if (content.length > maxSize) {
+            throw new McpError(McpErrorCode.InvalidParams, 'Content size exceeds maximum allowed');
+        }
+    }
+    static validatePageParams(offset = 0, limit = 20) {
+        if (offset < 0) {
+            throw new McpError(McpErrorCode.InvalidParams, 'Offset must be non-negative');
+        }
+        if (limit < 1 || limit > 100) {
+            throw new McpError(McpErrorCode.InvalidParams, 'Limit must be between 1 and 100');
+        }
+    }
+    static validateAuthorId(authorId) {
+        if (!authorId || typeof authorId !== 'string') {
+            throw new McpError(McpErrorCode.InvalidParams, 'Author ID is required and must be a string');
+        }
+        // Basic validation - alphanumeric, hyphens, underscores
+        const authorRegex = /^[a-zA-Z0-9\-_]+$/;
+        if (!authorRegex.test(authorId)) {
+            throw new McpError(McpErrorCode.InvalidParams, 'Author ID contains invalid characters');
+        }
+    }
+    static validateCategory(category) {
+        const validCategories = ['commands', 'services', 'patterns', 'implementations', 'contracts', 'guidance'];
+        if (!validCategories.includes(category)) {
+            throw new McpError(McpErrorCode.InvalidParams, `Invalid category. Must be one of: ${validCategories.join(', ')}`);
+        }
+    }
+    static validateVersion(version) {
+        // Semantic version validation
+        const versionRegex = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[a-zA-Z0-9\-_]+)?$/;
+        if (!versionRegex.test(version)) {
+            throw new McpError(McpErrorCode.InvalidParams, 'Version must follow semantic versioning format');
+        }
+    }
+}
+//# sourceMappingURL=ValidationUtils.js.map

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@utaba/ucm-mcp-server",
+  "version": "1.0.0",
+  "description": "Universal Context Manager MCP Server - AI-native artifact management",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "ucm-mcp-server": "dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ucm",
+    "universal-context-manager",
+    "ai",
+    "context-manager",
+    "micro-blocks",
+    "utaba"
+  ],
+  "author": {
+    "name": "Utaba AI",
+    "url": "https://utaba.ai"
+  },
+  "license": "BSD-3-Clause",
+  "homepage": "https://ucm.utaba.ai",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "commander": "^14.0.0",
+    "axios": "^1.10.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/package.json.backup

@@ -0,0 +1,37 @@
+{
+  "name": "ucm-mcp-server",
+  "version": "1.0.0",
+  "description": "Universal Context Manager MCP Server - AI-native artifact management",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "ucm-mcp-server": "dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ucm",
+    "universal-context-manager",
+    "ai",
+    "context-manager",
+    "micro-blocks",
+    "utaba"
+  ],
+  "author": {
+    "name": "Utaba AI",
+    "url": "https://utaba.ai"
+  },
+  "license": "BSD-3-Clause",
+  "homepage": "https://ucm.utaba.ai",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "commander": "^14.0.0",
+    "axios": "^1.10.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}