@utaba/ucm-mcp-server 6.5.1 → 6.6.0

package/dist/mcp-server/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/mcp-server/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/mcp-server/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/mcp-server/utils/SharePointErrorHandler.d.ts

@@ -0,0 +1,34 @@
+/**
+ * SharePointErrorHandler
+ * Centralized error handling for SharePoint MCP tools
+ */
+import { ILogger } from '../interfaces/ILogger.js';
+/**
+ * Standard MCP tool result with content array
+ */
+interface ToolResult {
+    content: Array<{
+        type: string;
+        text?: string;
+        uri?: string;
+        mimeType?: string;
+        resource?: {
+            uri: string;
+            text?: string;
+            blob?: string;
+            mimeType?: string;
+        };
+    }>;
+}
+export declare class SharePointErrorHandler {
+    /**
+     * Handle SharePoint API errors and return appropriate MCP responses
+     * @param error - The error from axios/API call
+     * @param logger - Logger instance for error tracking
+     * @param toolName - Name of the tool for logging context
+     * @returns ToolResult for authentication errors, throws McpError for others
+     */
+    static handle(error: any, logger: ILogger, toolName: string): ToolResult | never;
+}
+export {};
+//# sourceMappingURL=SharePointErrorHandler.d.ts.map

package/dist/mcp-server/utils/SharePointErrorHandler.js

@@ -0,0 +1,55 @@
+/**
+ * SharePointErrorHandler
+ * Centralized error handling for SharePoint MCP tools
+ */
+import { McpError, McpErrorCode } from './McpErrorHandler.js';
+export class SharePointErrorHandler {
+    /**
+     * Handle SharePoint API errors and return appropriate MCP responses
+     * @param error - The error from axios/API call
+     * @param logger - Logger instance for error tracking
+     * @param toolName - Name of the tool for logging context
+     * @returns ToolResult for authentication errors, throws McpError for others
+     */
+    static handle(error, logger, toolName) {
+        // Extract only serializable error details for logging to avoid circular reference issues
+        const sanitizedError = {
+            message: error?.message,
+            status: error?.response?.status,
+            statusText: error?.response?.statusText,
+            data: error?.response?.data,
+            url: error?.config?.url
+        };
+        logger.error(toolName, 'SharePoint operation failed', '', sanitizedError);
+        const serverError = error?.response?.data;
+        // Handle OAuth authentication required (user-delegated flow)
+        if (error?.response?.status === 401 && serverError?.error === 'AUTH_REQUIRED') {
+            const userMessage = serverError.message || 'To access SharePoint, please login then continue your conversation.';
+            // loginUrl can be in serverError directly or in details (check both)
+            const loginUrl = serverError.loginUrl || serverError.details?.loginUrl;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: userMessage
+                    },
+                    {
+                        type: 'text',
+                        text: loginUrl
+                    }
+                ]
+            };
+        }
+        // Handle not found errors
+        if (error?.response?.status === 404) {
+            throw new McpError(McpErrorCode.InvalidParams, 'SharePoint resource not found');
+        }
+        // Handle authorization errors (403 or other 401s)
+        if (error?.response?.status === 401 || error?.response?.status === 403) {
+            throw new McpError(McpErrorCode.InvalidParams, 'Not authorized to access this SharePoint resource');
+        }
+        // Handle all other errors
+        throw new McpError(McpErrorCode.InternalError, `SharePoint operation failed: ${error?.message || 'Unknown error'}`, { originalError: error?.message });
+    }
+}
+//# sourceMappingURL=SharePointErrorHandler.js.map