@utaba/ucm-mcp-server 6.5.0 → 6.6.0

package/dist/mcp-server/tools/core/GetArtifactTool.js

@@ -0,0 +1,124 @@
+import { BaseToolController } from '../base/BaseToolController.js';
+import { ResponseChunker } from '../../utils/ResponseChunker.js';
+import { parsePath } from '../../utils/PathUtils.js';
+export class GetArtifactTool extends BaseToolController {
+    trustedAuthors;
+    constructor(ucmClient, logger, publishingAuthorId, trustedAuthors = []) {
+        super(ucmClient, logger, publishingAuthorId);
+        this.trustedAuthors = trustedAuthors;
+    }
+    get name() {
+        return 'ucm_artifact_get';
+    }
+    get description() {
+        return 'Retrieve UCM artifact content with metadata. Large files are automatically chunked.';
+    }
+    get inputSchema() {
+        return {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: `Full artifact path with optional version (e.g., "${this.publishingAuthorId || '1234567890'}/main/commands/user/CreateUserCommand.ts" or "${this.publishingAuthorId || '1234567890'}/main/commands/user/CreateUserCommand.ts@1.0.0")`,
+                    minLength: 1,
+                    maxLength: 200
+                },
+                includeMetadata: {
+                    type: 'boolean',
+                    description: 'Include artifact metadata in response',
+                    default: true
+                }
+            },
+            required: ['path']
+        };
+    }
+    async handleExecute(params) {
+        let { path, includeMetadata = true } = params;
+        this.logger.debug('GetArtifactTool', `Retrieving artifact: ${path}`);
+        try {
+            // Parse the path to extract components
+            if (!path)
+                path = "";
+            const pathComponents = parsePath(path);
+            // Validate that path contains all required components including repository
+            if (!pathComponents.author || !pathComponents.repository || !pathComponents.category || !pathComponents.subcategory || !pathComponents.filename) {
+                throw new Error(`Path must include all components: author/repository/category/subcategory/filename.ext. Expected format: "author/repository/category/subcategory/filename.ext" or "author/repository/category/subcategory/filename.ext@version". Received: "${path}"`);
+            }
+            // Get artifact from API
+            const artifact = await this.ucmClient.getArtifact(pathComponents.author, pathComponents.repository, pathComponents.category, pathComponents.subcategory, pathComponents.filename, pathComponents.version);
+            // Extract content - it should always be a string in the API response
+            if (!artifact.content) {
+                throw new Error('Artifact has no content');
+            }
+            const content = artifact.content;
+            // Check if author is trusted
+            const author = artifact.metadata?.author || pathComponents.author;
+            const isTrusted = this.trustedAuthors.includes(author);
+            // Build response
+            const response = {
+                content,
+                path: artifact.path || path,
+                filename: pathComponents.filename // filename comes from parsed path
+            };
+            // Add security warning for untrusted authors
+            if (!isTrusted && this.publishingAuthorId && this.publishingAuthorId != pathComponents.author) {
+                response.securityWarning = `⚠️  SECURITY WARNING: This artifact is from author '${author}' who is not in your trusted authors list. Please review the code carefully before using it.`;
+            }
+            // Add metadata if requested
+            if (includeMetadata) {
+                response.metadata = {
+                    id: artifact.id,
+                    version: artifact.metadata?.version || pathComponents.version || 'latest',
+                    description: artifact.metadata?.description,
+                    author: author,
+                    repository: pathComponents.repository,
+                    category: artifact.metadata?.category || pathComponents.category,
+                    subcategory: artifact.metadata?.subcategory || pathComponents.subcategory,
+                    technology: artifact.metadata?.technology,
+                    tags: artifact.metadata?.tags || [],
+                    contractVersion: artifact.metadata?.contractVersion,
+                    size: content.length,
+                    mimeType: this.detectMimeType(pathComponents.filename),
+                    lastUpdated: artifact.lastUpdated,
+                    publishedAt: artifact.publishedAt,
+                };
+            }
+            // Apply chunking if needed
+            const chunkedResponse = ResponseChunker.chunk(response);
+            this.logger.info('GetArtifactTool', `Artifact retrieved: ${path}`, '', {
+                size: content.length,
+                chunked: chunkedResponse.chunk ? true : false
+            });
+            return chunkedResponse;
+        }
+        catch (error) {
+            this.logger.error('GetArtifactTool', `Failed to retrieve artifact: ${path}`, '', error);
+            throw error;
+        }
+    }
+    detectMimeType(filename) {
+        const ext = filename.split('.').pop()?.toLowerCase();
+        const mimeTypes = {
+            'ts': 'application/typescript',
+            'js': 'application/javascript',
+            'json': 'application/json',
+            'md': 'text/markdown',
+            'txt': 'text/plain',
+            'yaml': 'text/yaml',
+            'yml': 'text/yaml',
+            'html': 'text/html',
+            'css': 'text/css',
+            'py': 'text/x-python',
+            'java': 'text/x-java',
+            'cs': 'text/x-csharp',
+            'go': 'text/x-go',
+            'rs': 'text/x-rust',
+            'cpp': 'text/x-c++',
+            'c': 'text/x-c',
+            'sh': 'text/x-shellscript',
+            'xml': 'application/xml'
+        };
+        return mimeTypes[ext || ''] || 'text/plain';
+    }
+}
+//# sourceMappingURL=GetArtifactTool.js.map

package/dist/mcp-server/tools/core/GetArtifactVersionsTool.d.ts

@@ -0,0 +1,11 @@
+import { BaseToolController } from '../base/BaseToolController.js';
+import { UcmLocalApiClient } from '../../clients/UcmLocalApiClient.js';
+import { ILogger } from '../../interfaces/ILogger.js';
+export declare class GetArtifactVersionsTool 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=GetArtifactVersionsTool.d.ts.map

package/dist/mcp-server/tools/core/GetArtifactVersionsTool.js

@@ -0,0 +1,63 @@
+import { BaseToolController } from '../base/BaseToolController.js';
+import { parsePath } from '../../utils/PathUtils.js';
+export class GetArtifactVersionsTool extends BaseToolController {
+    constructor(ucmClient, logger, publishingAuthorId) {
+        super(ucmClient, logger, publishingAuthorId);
+    }
+    get name() {
+        return 'ucm_artifact_get_versions';
+    }
+    get description() {
+        return 'Get all available versions of a specific UCM artifact';
+    }
+    get inputSchema() {
+        return {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: `Full artifact path without version (e.g., "${this.publishingAuthorId || '01234567890'}/main/commands/user/CreateUserCommand.ts")`,
+                    minLength: 1,
+                    maxLength: 200
+                }
+            },
+            required: ['path']
+        };
+    }
+    async handleExecute(params) {
+        let { path } = params;
+        this.logger.debug('GetArtifactVersionsTool', `Retrieving versions for artifact: ${path}`);
+        try {
+            // Parse the path to extract components
+            if (!path)
+                path = "";
+            const pathComponents = parsePath(path);
+            // Validate that path contains all required components including repository
+            if (!pathComponents.author || !pathComponents.repository || !pathComponents.category ||
+                !pathComponents.subcategory || !pathComponents.filename) {
+                throw new Error(`Invalid artifact path. Expected format: {author}/{repository}/{category}/{subcategory}/{filename}. ` +
+                    `Received: ${path}`);
+            }
+            // Get versions from API
+            const versions = await this.ucmClient.getArtifactVersions(pathComponents.author, pathComponents.repository, pathComponents.category, pathComponents.subcategory, pathComponents.filename);
+            // Return the versions data
+            return {
+                path,
+                author: pathComponents.author,
+                repository: pathComponents.repository,
+                category: pathComponents.category,
+                subcategory: pathComponents.subcategory,
+                filename: pathComponents.filename,
+                versions: versions
+            };
+        }
+        catch (error) {
+            this.logger.error('GetArtifactVersionsTool', 'Failed to retrieve artifact versions', error);
+            if (error.message?.includes('404') || error.message?.includes('not found')) {
+                throw new Error(`Artifact not found: ${path}`);
+            }
+            throw new Error(`Failed to retrieve artifact versions: ${error.message || 'Unknown error'}`);
+        }
+    }
+}
+//# sourceMappingURL=GetArtifactVersionsTool.js.map

package/dist/mcp-server/tools/core/GetChunkTool.d.ts

@@ -0,0 +1,11 @@
+import { BaseToolController } from '../base/BaseToolController.js';
+import { UcmLocalApiClient } from '../../clients/UcmLocalApiClient.js';
+import { ILogger } from '../../interfaces/ILogger.js';
+export declare class GetChunkTool 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=GetChunkTool.d.ts.map

package/dist/mcp-server/tools/core/GetChunkTool.js

@@ -0,0 +1,56 @@
+import { BaseToolController } from '../base/BaseToolController.js';
+import { ResponseChunker } from '../../utils/ResponseChunker.js';
+import { McpError, McpErrorCode } from '../../utils/McpErrorHandler.js';
+export class GetChunkTool extends BaseToolController {
+    constructor(ucmClient, logger, publishingAuthorId) {
+        super(ucmClient, logger, publishingAuthorId);
+    }
+    get name() {
+        return 'ucm_artifact_get_chunk';
+    }
+    get description() {
+        return 'Retrieve the next chunk of a large UCM artifact response';
+    }
+    get inputSchema() {
+        return {
+            type: 'object',
+            properties: {
+                chunkId: {
+                    type: 'string',
+                    description: 'The chunk ID to retrieve',
+                    minLength: 1
+                },
+                sequence: {
+                    type: 'number',
+                    description: 'The sequence number of the chunk to retrieve',
+                    minimum: 0
+                }
+            },
+            required: ['chunkId', 'sequence']
+        };
+    }
+    async handleExecute(params) {
+        const { chunkId, sequence } = params;
+        this.logger.debug('GetChunkTool', `Retrieving chunk: ${chunkId} sequence ${sequence}`);
+        // Get chunk info first
+        const chunkInfo = ResponseChunker.getChunkInfo(chunkId);
+        if (!chunkInfo.exists) {
+            throw new McpError(McpErrorCode.InvalidParams, `Chunk with ID '${chunkId}' not found. It may have expired.`);
+        }
+        // Validate sequence range
+        if (sequence < 0 || (chunkInfo.total && sequence >= chunkInfo.total)) {
+            throw new McpError(McpErrorCode.InvalidParams, `Sequence ${sequence} is out of range. Valid range is 0-${(chunkInfo.total || 1) - 1}`);
+        }
+        // Get the chunk
+        const nextChunk = ResponseChunker.getNextChunk(chunkId, sequence);
+        if (!nextChunk) {
+            throw new McpError(McpErrorCode.InternalError, 'Failed to retrieve chunk');
+        }
+        this.logger.info('GetChunkTool', `Chunk retrieved: ${chunkId} sequence ${sequence}`, '', {
+            hasMore: nextChunk.hasMore,
+            total: nextChunk.chunk.total
+        });
+        return nextChunk;
+    }
+}
+//# sourceMappingURL=GetChunkTool.js.map

package/dist/mcp-server/tools/core/ListArtifactsTool.d.ts

@@ -0,0 +1,11 @@
+import { BaseToolController } from '../base/BaseToolController.js';
+import { UcmLocalApiClient } from '../../clients/UcmLocalApiClient.js';
+import { ILogger } from '../../interfaces/ILogger.js';
+export declare class ListArtifactsTool 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=ListArtifactsTool.d.ts.map

package/dist/mcp-server/tools/core/ListArtifactsTool.js

@@ -0,0 +1,84 @@
+import { BaseToolController } from '../base/BaseToolController.js';
+import { parsePath } from '../../utils/PathUtils.js';
+export class ListArtifactsTool extends BaseToolController {
+    constructor(ucmClient, logger, publishingAuthorId) {
+        super(ucmClient, logger, publishingAuthorId);
+    }
+    get name() {
+        return 'ucm_artifact_list';
+    }
+    get description() {
+        return `List artifacts with exploratory browsing support. Can list authors, repositories, categories, subcategories, or artifacts depending on path depth. ${this.publishingAuthorId ? "Your author value is '" + this.publishingAuthorId + "'" : ''}`;
+    }
+    get inputSchema() {
+        return {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: `Exploratory path: empty string or omit for authors, "{author}" for repositories, "{author}/{repository}" for categories, "{author}/{repository}/{category}" for subcategories, or "{author}/{repository}/{category}/{subcategory}" for artifacts. Eg; ${this.publishingAuthorId}/main/commands/user`,
+                    minLength: 0,
+                    maxLength: 200
+                },
+                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: []
+        };
+    }
+    async handleExecute(params) {
+        let { path, offset, limit } = params;
+        if (!path)
+            path = "";
+        this.logger.debug('ListArtifactsTool', `Exploring path: ${path} (offset: ${offset || 0}, limit: ${limit || 'default'})`);
+        try {
+            // Parse the path to extract components
+            const pathComponents = parsePath(path);
+            const pathSegments = path.split('/').filter(Boolean);
+            // Call API based on path depth for exploratory browsing
+            const response = await this.ucmClient.listArtifacts(pathComponents.author, pathComponents.repository, pathComponents.category, pathComponents.subcategory, offset, limit);
+            // Determine what we're listing based on path depth (4-level structure)
+            let listingType = 'artifacts';
+            if (pathSegments.length == 0) {
+                listingType = 'authors';
+            }
+            else if (pathSegments.length === 1) {
+                listingType = 'repositories';
+            }
+            else if (pathSegments.length === 2) {
+                listingType = 'categories';
+            }
+            else if (pathSegments.length === 3) {
+                listingType = 'subcategories';
+            }
+            // For MVP, validate repository is 'main' if provided
+            // if (pathSegments.length >= 2 && pathComponents.repository && pathComponents.repository !== 'main') {
+            //   throw new Error(`Repository must be 'main' for MVP. Received: "${pathComponents.repository}"`);
+            // }
+            this.logger.info('ListArtifactsTool', `Listed ${response.data.length} ${listingType} in: ${path}`);
+            // Return the full response with pagination metadata and context
+            return {
+                path,
+                listingType,
+                data: response.data,
+                pagination: response.pagination,
+                hasMore: response.pagination.offset + response.pagination.limit < response.pagination.total,
+                _links: response._links
+            };
+        }
+        catch (error) {
+            this.logger.error('ListArtifactsTool', `Failed to explore path: ${path}`, '', error);
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=ListArtifactsTool.js.map

package/dist/mcp-server/tools/core/MoveArtifactTool.d.ts

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

package/dist/mcp-server/tools/core/MoveArtifactTool.js

@@ -0,0 +1,104 @@
+import { BaseToolController } from '../base/BaseToolController.js';
+import { parsePath } from '../../utils/PathUtils.js';
+import { McpError, McpErrorCode } from '../../utils/McpErrorHandler.js';
+export class MoveArtifactTool extends BaseToolController {
+    constructor(ucmClient, logger, publishingAuthorId) {
+        super(ucmClient, logger, publishingAuthorId);
+    }
+    get name() {
+        return 'ucm_artifact_move';
+    }
+    get description() {
+        return 'Move an artifact from one namespace location to another. All versions are moved. Requires read access on source and write access on destination.';
+    }
+    get inputSchema() {
+        return {
+            type: 'object',
+            properties: {
+                sourcePath: {
+                    type: 'string',
+                    description: `Full source artifact path (e.g., "${this.publishingAuthorId || '1234567890'}/main/commands/user/CreateUserCommand.ts")`,
+                    minLength: 1,
+                    maxLength: 250
+                },
+                destinationPath: {
+                    type: 'string',
+                    description: `Full destination artifact path (e.g., "${this.publishingAuthorId || '1234567890'}/main/services/user/UserService.ts")`,
+                    minLength: 1,
+                    maxLength: 250
+                }
+            },
+            required: ['sourcePath', 'destinationPath'],
+            additionalProperties: false
+        };
+    }
+    async handleExecute(params) {
+        const { sourcePath, destinationPath } = params;
+        this.logger.debug('MoveArtifactTool', `Moving artifact: ${sourcePath} → ${destinationPath}`);
+        try {
+            const source = parsePath(sourcePath);
+            const dest = parsePath(destinationPath);
+            // Build destination namespace (author/repository/category/subcategory)
+            const destNamespace = `${dest.author}/${dest.repository}/${dest.category}/${dest.subcategory}`;
+            const result = await this.ucmClient.editArtifactMetadata(source.author, source.repository, source.category, source.subcategory, source.filename, {
+                updateNamespace: destNamespace,
+                updateFilename: dest.filename
+            });
+            const responseData = result.data || result;
+            const response = {
+                success: true,
+                operation: 'move',
+                artifact: {
+                    originalPath: sourcePath,
+                    newPath: destinationPath,
+                    affectedVersions: responseData.affectedVersions || 'all'
+                },
+                details: responseData.details || `Artifact moved from ${sourcePath} to ${destinationPath}`,
+                _links: responseData._links || {}
+            };
+            this.logger.info('MoveArtifactTool', `Artifact moved successfully: ${sourcePath} → ${destinationPath}`);
+            return JSON.stringify(response);
+        }
+        catch (error) {
+            this.logger.error('MoveArtifactTool', `Failed to move artifact: ${sourcePath} → ${destinationPath}`, '', error);
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            if (errorMessage?.includes('not found')) {
+                throw new McpError(McpErrorCode.InvalidParams, `Artifact not found at path: ${sourcePath}. Please verify the path is correct and the artifact exists.`);
+            }
+            if (errorMessage?.includes('permission') || errorMessage?.includes('unauthorized')) {
+                throw new McpError(McpErrorCode.InvalidParams, `Insufficient permissions. You need read access on the source and write access on the destination namespace.`);
+            }
+            if (errorMessage?.includes('destination already exists')) {
+                throw new McpError(McpErrorCode.InvalidParams, `An artifact already exists at: ${destinationPath}. Choose a different destination.`);
+            }
+            if (errorMessage?.includes('Author not found')) {
+                throw new McpError(McpErrorCode.InvalidParams, `Author not found. Ensure both source and destination paths use valid author identifiers.`);
+            }
+            throw error;
+        }
+    }
+    validateParams(params) {
+        super.validateParams(params);
+        const { sourcePath, destinationPath } = params;
+        // Validate source path
+        const sourceParts = sourcePath.split('/');
+        if (sourceParts.length < 5) {
+            throw new McpError(McpErrorCode.InvalidParams, 'sourcePath must contain author/repository/category/subcategory/filename');
+        }
+        // Validate destination path
+        const destParts = destinationPath.split('/');
+        if (destParts.length < 5) {
+            throw new McpError(McpErrorCode.InvalidParams, 'destinationPath must contain author/repository/category/subcategory/filename');
+        }
+        // Validate destination filename
+        const destFilename = destParts[destParts.length - 1];
+        if (!/^[^\/\\:*?"<>|]+\.[a-zA-Z0-9]+$/.test(destFilename)) {
+            throw new McpError(McpErrorCode.InvalidParams, 'destinationPath filename must be valid with an extension (e.g., "UserService.ts")');
+        }
+        // Source and destination must differ
+        if (sourcePath === destinationPath) {
+            throw new McpError(McpErrorCode.InvalidParams, 'sourcePath and destinationPath must be different');
+        }
+    }
+}
+//# sourceMappingURL=MoveArtifactTool.js.map

package/dist/mcp-server/tools/core/PublishArtifactFromFileTool.d.ts

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