@utaba/ucm-mcp-server 6.6.0 → 6.7.0

package/dist/mcp-server/tools/utility/AuthorRecentsTool.js

@@ -1,49 +0,0 @@
-import { BaseToolController } from '../base/BaseToolController.js';
-export class AuthorRecentsTool extends BaseToolController {
-    constructor(ucmClient, logger, publishingAuthorId) {
-        super(ucmClient, logger, publishingAuthorId);
-    }
-    get name() {
-        return 'ucm_workspace_get_recents';
-    }
-    get description() {
-        return 'Generate workspace activity tracking showing the 20 most recently modified artifacts within a workspace.';
-    }
-    get inputSchema() {
-        return {
-            type: 'object',
-            properties: {
-                workspace: {
-                    type: 'string',
-                    description: `Workspace identifier: ${this.publishingAuthorId || '1234567890'}`
-                }
-            },
-            required: ['workspace']
-        };
-    }
-    async handleExecute(params) {
-        const { workspace } = params;
-        const author = workspace;
-        this.logger.debug('AuthorRecentsTool', `Retrieving author recents for: ${author}`);
-        try {
-            // Get author recent activity content from API
-            const authorRecentsContent = await this.ucmClient.getAuthorRecents(author);
-            this.logger.info('AuthorRecentsTool', 'Author recents retrieved successfully', '', {
-                author,
-                contentLength: authorRecentsContent.length,
-                source: `UCM API /api/v1/resources/author/${author}/recents`
-            });
-            return authorRecentsContent;
-        }
-        catch (error) {
-            let errorMessage = `Failed to retrieve author recents for ${author}.`;
-            if (this.publishingAuthorId && author != this.publishingAuthorId) {
-                errorMessage += ` did you mean '${this.publishingAuthorId}'?`;
-                error.message = error.message += ` did you mean '${this.publishingAuthorId}'?`;
-            }
-            this.logger.error('AuthorRecentsTool', `${errorMessage}`, '', error);
-            throw error;
-        }
-    }
-}
-//# sourceMappingURL=AuthorRecentsTool.js.map

package/dist/mcp-server/tools/utility/ListRepositoriesTool.d.ts

@@ -1,11 +0,0 @@
-import { BaseToolController } from '../base/BaseToolController.js';
-import { UcmLocalApiClient } from '../../clients/UcmLocalApiClient.js';
-import { ILogger } from '../../interfaces/ILogger.js';
-export declare class ListRepositoriesTool extends BaseToolController {
-    constructor(ucmClient: UcmLocalApiClient, logger: ILogger, publishingAuthorId?: string);
-    get name(): string;
-    get description(): string;
-    get inputSchema(): any;
-    protected handleExecute(params: any): Promise<any>;
-}
-//# sourceMappingURL=ListRepositoriesTool.d.ts.map

package/dist/mcp-server/tools/utility/ListRepositoriesTool.js

@@ -1,68 +0,0 @@
-import { BaseToolController } from '../base/BaseToolController.js';
-export class ListRepositoriesTool extends BaseToolController {
-    constructor(ucmClient, logger, publishingAuthorId) {
-        super(ucmClient, logger, publishingAuthorId);
-    }
-    get name() {
-        return 'ucm_workspace_list_repos';
-    }
-    get description() {
-        return 'List all repositories for a specific workspace with pagination and statistics';
-    }
-    get inputSchema() {
-        return {
-            type: 'object',
-            properties: {
-                workspace: {
-                    type: 'string',
-                    description: `Workspace identifier (e.g., "${this.publishingAuthorId || '1234567890'}")`,
-                    minLength: 1,
-                    maxLength: 50
-                },
-                offset: {
-                    type: 'number',
-                    description: 'Number of items to skip for pagination (default: 0)',
-                    minimum: 0
-                },
-                limit: {
-                    type: 'number',
-                    description: 'Maximum number of items to return (default: 20, max: 100)',
-                    minimum: 1,
-                    maximum: 100
-                }
-            },
-            required: ['workspace']
-        };
-    }
-    async handleExecute(params) {
-        const { workspace, offset, limit } = params;
-        const author = workspace;
-        this.logger.debug('ListRepositoriesTool', `Listing repositories for author: ${author}`, '', {
-            offset: offset || 0,
-            limit: limit || 'default'
-        });
-        try {
-            // Use listRepositories to get repositories for the author
-            const response = await this.ucmClient.listRepositories(author, offset, limit);
-            this.logger.info('ListRepositoriesTool', `Listed ${response.data.length} repositories for author: ${author}`, '', {
-                total: response.pagination?.total,
-                offset: response.pagination?.offset,
-                limit: response.pagination?.limit
-            });
-            // Return the full response with pagination metadata and context
-            return {
-                author,
-                listingType: 'repositories',
-                data: response.data,
-                pagination: response.pagination,
-                hasMore: response.pagination.offset + response.pagination.limit < response.pagination.total,
-                _links: response._links
-            };
-        }
-        catch (error) {
-            this.logger.error('ListRepositoriesTool', `Failed to list repositories for author: ${author}`, '', error);
-            throw error;
-        }
-    }
-}
-//# sourceMappingURL=ListRepositoriesTool.js.map

package/dist/mcp-server/tools/utility/QuickstartTool.d.ts

@@ -1,11 +0,0 @@
-import { BaseToolController } from '../base/BaseToolController.js';
-import { UcmLocalApiClient } from '../../clients/UcmLocalApiClient.js';
-import { ILogger } from '../../interfaces/ILogger.js';
-export declare class QuickstartTool extends BaseToolController {
-    constructor(ucmClient: UcmLocalApiClient, logger: ILogger, publishingAuthorId?: string);
-    get name(): string;
-    get description(): string;
-    get inputSchema(): any;
-    protected handleExecute(params: any): Promise<any>;
-}
-//# sourceMappingURL=QuickstartTool.d.ts.map

package/dist/mcp-server/tools/utility/QuickstartTool.js

@@ -1,36 +0,0 @@
-import { BaseToolController } from '../base/BaseToolController.js';
-export class QuickstartTool extends BaseToolController {
-    constructor(ucmClient, logger, publishingAuthorId) {
-        super(ucmClient, logger, publishingAuthorId);
-    }
-    get name() {
-        return 'ucm_connect';
-    }
-    get description() {
-        return 'Connect to UCM and initialise operational context for the conversation. Call this tool FIRST at the start of every conversation — it loads your personalized account information, workspace IDs, repositories, policies, and connected services. Required for conversation initialisation before using any other UCM tools.';
-    }
-    get inputSchema() {
-        return {
-            type: 'object',
-            properties: {},
-            required: []
-        };
-    }
-    async handleExecute(params) {
-        this.logger.debug('QuickstartTool', 'Retrieving UCM quickstart guide');
-        try {
-            // Get quickstart content from API
-            const quickstartContent = await this.ucmClient.getQuickstart();
-            this.logger.info('QuickstartTool', 'Quickstart guide retrieved successfully', '', {
-                contentLength: quickstartContent.length,
-                source: 'UCM API /api/v1/quickstart'
-            });
-            return quickstartContent;
-        }
-        catch (error) {
-            this.logger.error('QuickstartTool', 'Failed to retrieve quickstart guide', '', error);
-            throw error;
-        }
-    }
-}
-//# sourceMappingURL=QuickstartTool.js.map

package/dist/mcp-server/types/UcmApiTypes.d.ts

@@ -1,40 +0,0 @@
-export interface ArtifactMetadata {
-    name: string;
-    description: string;
-    version: string;
-    contractVersion?: string;
-    author: string;
-    repository: string;
-    category: string;
-    subcategory: string;
-    technology?: string;
-    tags?: string[];
-    dependencies?: {
-        services?: string[];
-        commands?: string[];
-        external?: Record<string, string>;
-    };
-}
-export interface ArtifactData {
-    id: string;
-    path: string;
-    metadata: ArtifactMetadata;
-    content?: string;
-    examples?: any[];
-    lastUpdated: string;
-    publishedAt: string;
-}
-export interface AuthorData {
-    id: string;
-    name: string;
-    email?: string;
-    createdAt: string;
-    artifactCount?: number;
-}
-export interface UcmApiResponse<T = any> {
-    data: T;
-    success: boolean;
-    message?: string;
-    error?: string;
-}
-//# sourceMappingURL=UcmApiTypes.d.ts.map

package/dist/mcp-server/types/UcmApiTypes.js

@@ -1,4 +0,0 @@
-// Source: Duplicated from ../types/Artifact.ts for MCP Server independence
-// Sync with Next.js app types when schema changes are made
-export {};
-//# sourceMappingURL=UcmApiTypes.js.map

package/dist/mcp-server/utils/McpErrorHandler.d.ts

@@ -1,25 +0,0 @@
-export declare enum McpErrorCode {
-    ParseError = -32700,// Invalid JSON received
-    InvalidRequest = -32600,// Request is not valid MCP
-    MethodNotFound = -32601,// Method does not exist
-    InvalidParams = -32602,// Invalid method parameters
-    InternalError = -32603,// Internal server error
-    ExternalServiceUnavailable = -32001
-}
-export interface McpErrorResponse {
-    error: {
-        code: McpErrorCode;
-        message: string;
-        data?: any;
-    };
-}
-export declare class McpError extends Error {
-    code: McpErrorCode;
-    data?: any | undefined;
-    constructor(code: McpErrorCode, message: string, data?: any | undefined);
-    toResponse(): McpErrorResponse;
-}
-export declare class McpErrorHandler {
-    static formatError(error: any): McpError;
-}
-//# sourceMappingURL=McpErrorHandler.d.ts.map

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

@@ -1,67 +0,0 @@
-// 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 ucm_connect to verify your connection', { 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/mcp-server/utils/PathUtils.d.ts

@@ -1,61 +0,0 @@
-/**
- * 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/mcp-server/utils/PathUtils.js

@@ -1,178 +0,0 @@
-/**
- * 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

@@ -1,25 +0,0 @@
-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

@@ -1,79 +0,0 @@
-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