@utaba/ucm-mcp-server 6.5.0 → 6.6.0

package/dist/mcp-server/tools/connections/AccessConnectionTool.js

@@ -0,0 +1,107 @@
+/**
+ * AccessConnectionTool
+ * Access a specific external connection, check auth status, and return available tool schemas.
+ *
+ * Phase 2 of Unified Connection Gateway Implementation
+ */
+import { BaseToolController } from '../base/BaseToolController.js';
+import { McpError, McpErrorCode } from '../../utils/McpErrorHandler.js';
+export class AccessConnectionTool extends BaseToolController {
+    constructor(ucmClient, logger, publishingAuthorId) {
+        super(ucmClient, logger, publishingAuthorId);
+    }
+    get name() {
+        return 'ucm_connection_access';
+    }
+    get description() {
+        return 'Access a specific external connection, check auth status, and return available tool schemas. Call without toolNames to get a summary index of all available tools. Pass toolNames to retrieve full parameter schemas.';
+    }
+    get inputSchema() {
+        return {
+            type: 'object',
+            properties: {
+                connectionId: {
+                    type: 'string',
+                    description: 'Connection ID (SharePoint connection or Remote MCP Server) from ucm_connection_list',
+                    minLength: 36,
+                    maxLength: 36
+                },
+                toolNames: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Optional list of tool names to get full parameter schemas for. If omitted, returns a summary index of all available tools. Pass in all tool names that could likely be relevant.'
+                }
+            },
+            required: ['connectionId']
+        };
+    }
+    validateParams(params) {
+        super.validateParams(params);
+        // Validate connectionId
+        if (!params.connectionId || typeof params.connectionId !== 'string') {
+            throw new McpError(McpErrorCode.InvalidParams, 'connectionId is required and must be a string');
+        }
+        if (params.connectionId.length !== 36) {
+            throw new McpError(McpErrorCode.InvalidParams, 'connectionId must be a valid UUID (36 characters)');
+        }
+    }
+    async handleExecute(params) {
+        this.logger.info('AccessConnectionTool', `Accessing connection: ${params.connectionId}`);
+        try {
+            const result = await this.ucmClient.accessConnection(params.connectionId, params.toolNames);
+            this.logger.info('AccessConnectionTool', 'Connection accessed successfully', '', {
+                connectionId: params.connectionId,
+                connectionType: result.connectionType,
+                isAuthenticated: result.isAuthenticated,
+                toolCount: result.tools?.length || 0
+            });
+            // Auth required — return login message
+            if (!result.isAuthenticated) {
+                if (result.authRequired && result.loginUrl) {
+                    return `Authentication required for "${result.connectionName}". Login URL: ${result.loginUrl}`;
+                }
+                return `Connection "${result.connectionName}" is not accessible: ${result.loginMessage || 'Authentication failed'}`;
+            }
+            // If markdown index returned (no toolNames requested), return markdown
+            if (result.markdown) {
+                return result.markdown;
+            }
+            // Tools mode — return compact JSON with schemas
+            const json = {
+                connectionId: result.connectionId,
+                connectionName: result.connectionName,
+                instructions: result.instructions,
+                policies: result.policies,
+                ...(result.error && { error: result.error }),
+                tools: result.tools
+            };
+            return JSON.stringify(json);
+        }
+        catch (error) {
+            // Sanitize error for logging
+            const sanitizedError = {
+                message: error?.message,
+                status: error?.response?.status,
+                data: error?.response?.data
+            };
+            this.logger.error('AccessConnectionTool', 'Failed to access connection', '', sanitizedError);
+            if (error instanceof McpError) {
+                throw error;
+            }
+            // Handle API errors
+            if (error.response) {
+                const status = error.response.status;
+                const errorData = error.response.data;
+                if (status === 401 || status === 403) {
+                    throw new McpError(McpErrorCode.InvalidRequest, `Access denied: ${errorData?.message || 'Not authorized to access this connection'}`);
+                }
+                if (status === 404) {
+                    throw new McpError(McpErrorCode.InvalidParams, `Connection not found: ${params.connectionId}`);
+                }
+                throw new McpError(McpErrorCode.InternalError, `API error: ${errorData?.message || error.message}`);
+            }
+            throw new McpError(McpErrorCode.InternalError, `Failed to access connection: ${error.message}`);
+        }
+    }
+}
+//# sourceMappingURL=AccessConnectionTool.js.map

package/dist/mcp-server/tools/connections/CallRemoteToolTool.d.ts

@@ -0,0 +1,22 @@
+/**
+ * CallRemoteToolTool
+ * Execute a tool on an external connection (SharePoint or Remote MCP Server).
+ *
+ * Phase 3 of Unified Connection Gateway Implementation
+ */
+import { BaseToolController } from '../base/BaseToolController.js';
+import { UcmLocalApiClient } from '../../clients/UcmLocalApiClient.js';
+import { ILogger } from '../../interfaces/ILogger.js';
+export declare class CallRemoteToolTool extends BaseToolController {
+    constructor(ucmClient: UcmLocalApiClient, logger: ILogger, publishingAuthorId?: string);
+    get name(): string;
+    get description(): string;
+    get inputSchema(): any;
+    protected validateParams(params: any): void;
+    protected handleExecute(params: {
+        connectionId: string;
+        toolName: string;
+        args?: any;
+    }): Promise<any>;
+}
+//# sourceMappingURL=CallRemoteToolTool.d.ts.map

package/dist/mcp-server/tools/connections/CallRemoteToolTool.js

@@ -0,0 +1,124 @@
+/**
+ * CallRemoteToolTool
+ * Execute a tool on an external connection (SharePoint or Remote MCP Server).
+ *
+ * Phase 3 of Unified Connection Gateway Implementation
+ */
+import { BaseToolController } from '../base/BaseToolController.js';
+import { McpError, McpErrorCode } from '../../utils/McpErrorHandler.js';
+export class CallRemoteToolTool extends BaseToolController {
+    constructor(ucmClient, logger, publishingAuthorId) {
+        super(ucmClient, logger, publishingAuthorId);
+    }
+    get name() {
+        return 'ucm_connection_call_tool';
+    }
+    get description() {
+        return 'Call a tool on an external connection.';
+    }
+    get inputSchema() {
+        return {
+            type: 'object',
+            properties: {
+                connectionId: {
+                    type: 'string',
+                    description: 'Connection ID (SharePoint connection or Remote MCP Server) from ucm_connection_list',
+                    minLength: 36,
+                    maxLength: 36
+                },
+                toolName: {
+                    type: 'string',
+                    description: 'Name of the tool to call (see ucm_connection_access for available tools)',
+                    minLength: 1
+                },
+                args: {
+                    type: 'object',
+                    description: 'Tool arguments — passed through to the remote tool as-is',
+                    additionalProperties: true
+                }
+            },
+            required: ['connectionId', 'toolName']
+        };
+    }
+    validateParams(params) {
+        super.validateParams(params);
+        // Validate connectionId
+        if (!params.connectionId || typeof params.connectionId !== 'string') {
+            throw new McpError(McpErrorCode.InvalidParams, 'connectionId is required and must be a string');
+        }
+        if (params.connectionId.length !== 36) {
+            throw new McpError(McpErrorCode.InvalidParams, 'connectionId must be a valid UUID (36 characters)');
+        }
+        // Validate toolName
+        if (!params.toolName || typeof params.toolName !== 'string') {
+            throw new McpError(McpErrorCode.InvalidParams, 'toolName is required and must be a string');
+        }
+    }
+    async handleExecute(params) {
+        // MCP transport may serialize nested objects as strings — parse if needed
+        const args = typeof params.args === 'string'
+            ? JSON.parse(params.args)
+            : params.args;
+        this.logger.info('CallRemoteToolTool', `Calling tool ${params.toolName} on connection: ${params.connectionId}`);
+        try {
+            const result = await this.ucmClient.callRemoteTool(params.connectionId, params.toolName, args);
+            this.logger.info('CallRemoteToolTool', 'Tool executed successfully', '', {
+                connectionId: params.connectionId,
+                toolName: params.toolName,
+                success: result.success,
+                authRequired: result.authRequired || false
+            });
+            // Clean proxy: pass through content blocks directly
+            // Return structured JSON for errors so the AI can self-correct and retry
+            if (!result.success) {
+                if (result.errorCode === 'TOOL_NOT_FOUND' && result.tools) {
+                    return JSON.stringify({
+                        error: 'TOOL_NOT_FOUND',
+                        message: result.error,
+                        available_tools: result.tools
+                    });
+                }
+                if (result.errorCode === 'VALIDATION_ERROR' && result.tools) {
+                    return JSON.stringify({
+                        error: 'VALIDATION_ERROR',
+                        message: result.error,
+                        tool_schema: result.tools[0]
+                    });
+                }
+                // For other errors (auth), return text
+                return result.markdown || result.error || 'Tool execution failed';
+            }
+            // Return as pre-formatted MCP response — McpHandler will pass through
+            return { content: result.content };
+        }
+        catch (error) {
+            // Sanitize error for logging
+            const sanitizedError = {
+                message: error?.message,
+                status: error?.response?.status,
+                data: error?.response?.data
+            };
+            this.logger.error('CallRemoteToolTool', 'Failed to execute tool', '', sanitizedError);
+            if (error instanceof McpError) {
+                throw error;
+            }
+            // Handle API errors
+            if (error.response) {
+                const status = error.response.status;
+                const errorData = error.response.data;
+                if (status === 401 || status === 403) {
+                    throw new McpError(McpErrorCode.InvalidRequest, `Access denied: ${errorData?.message || 'Not authorized to access this connection'}`);
+                }
+                if (status === 404) {
+                    throw new McpError(McpErrorCode.InvalidParams, `Connection not found: ${params.connectionId}`);
+                }
+                if (status === 400) {
+                    throw new McpError(McpErrorCode.InvalidParams, `Invalid request: ${errorData?.message || errorData?.error || 'Invalid parameters'}`);
+                }
+                throw new McpError(McpErrorCode.InternalError, `API error: ${errorData?.message || error.message}`);
+            }
+            throw new McpError(McpErrorCode.InternalError, `Failed to execute tool: ${error.message}`);
+        }
+    }
+}
+//# sourceMappingURL=CallRemoteToolTool.js.map

package/dist/mcp-server/tools/core/DeleteArtifactTool.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 DeleteArtifactTool 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=DeleteArtifactTool.d.ts.map

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

@@ -0,0 +1,83 @@
+import { BaseToolController } from '../base/BaseToolController.js';
+export class DeleteArtifactTool extends BaseToolController {
+    constructor(ucmClient, logger, publishingAuthorId) {
+        super(ucmClient, logger, publishingAuthorId);
+    }
+    get name() {
+        return 'ucm_artifact_delete';
+    }
+    get description() {
+        return 'Delete a UCM artifact by path and version. This action cannot be undone. Only the latest or specified version is deleted.';
+    }
+    get inputSchema() {
+        return {
+            type: 'object',
+            properties: {
+                workspace: {
+                    type: 'string',
+                    description: `Author name (e.g., ${this.publishingAuthorId || '01234567890'})`,
+                    minLength: 1,
+                    maxLength: 50
+                },
+                repository: {
+                    type: 'string',
+                    description: 'Repository name (e.g., "main")',
+                    minLength: 1,
+                    maxLength: 50
+                },
+                category: {
+                    type: 'string',
+                    description: 'Category name (e.g., "commands")',
+                    minLength: 1,
+                    maxLength: 50
+                },
+                subcategory: {
+                    type: 'string',
+                    description: 'Subcategory name (e.g., "user")',
+                    minLength: 1,
+                    maxLength: 50
+                },
+                filename: {
+                    type: 'string',
+                    description: 'Filename with optional version suffix (e.g., "CreateUserCommand.ts" or "CreateUserCommand.ts@1.0.0")',
+                    minLength: 1,
+                    maxLength: 150
+                }
+            },
+            required: ['workspace', 'repository', 'category', 'subcategory', 'filename']
+        };
+    }
+    async handleExecute(params) {
+        const { workspace, repository, category, subcategory, filename } = params;
+        const author = workspace;
+        this.logger.debug('DeleteArtifactTool', `Deleting artifact: ${author}/${repository}/${category}/${subcategory}/${filename}`);
+        try {
+            // Parse filename to extract version if present
+            const parts = filename.split('@');
+            const actualFilename = parts[0];
+            const version = parts.length > 1 ? parts[1] : undefined;
+            // Delete artifact from API and capture the response
+            const deleteResponse = await this.ucmClient.deleteArtifact(author, repository, category, subcategory, actualFilename, version);
+            const path = `${author}/${repository}/${category}/${subcategory}/${filename}`;
+            this.logger.info('DeleteArtifactTool', `Artifact deleted successfully: ${path}`);
+            // Use actual response data from the server instead of hardcoded values
+            return {
+                success: deleteResponse.success || true,
+                message: `Artifact deleted successfully`,
+                author,
+                repository,
+                category,
+                subcategory,
+                filename: deleteResponse.filename || actualFilename,
+                version: deleteResponse.version, // Use actual version that was deleted from server
+                path,
+                deletedAt: deleteResponse.deletedAt || new Date().toISOString()
+            };
+        }
+        catch (error) {
+            this.logger.error('DeleteArtifactTool', `Failed to delete artifact: ${author}/${repository}/${category}/${subcategory}/${filename}`, '', error);
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=DeleteArtifactTool.js.map

package/dist/mcp-server/tools/core/EditArtifactMetadataTool.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 EditArtifactMetadataTool 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;
+}
+//# sourceMappingURL=EditArtifactMetadataTool.d.ts.map

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

@@ -0,0 +1,173 @@
+import { BaseToolController } from '../base/BaseToolController.js';
+import { parsePath } from '../../utils/PathUtils.js';
+import { McpError, McpErrorCode } from '../../utils/McpErrorHandler.js';
+export class EditArtifactMetadataTool extends BaseToolController {
+    constructor(ucmClient, logger, publishingAuthorId) {
+        super(ucmClient, logger, publishingAuthorId);
+    }
+    get name() {
+        return 'ucm_artifact_edit_metadata';
+    }
+    get description() {
+        return 'Edit artifact metadata and move artifacts. Supports updating description, namespace, filename, MIME type, technology, and tags. Move operations affect all versions while metadata-only updates apply to latest version only.';
+    }
+    get inputSchema() {
+        return {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: `Full artifact path (e.g., "${this.publishingAuthorId || '1234567890'}/main/commands/user/CreateUserCommand.ts")`,
+                    minLength: 1,
+                    maxLength: 250
+                },
+                updateDescription: {
+                    type: 'string',
+                    description: 'New description for the artifact (up to 1000 characters)',
+                    maxLength: 1000
+                },
+                updateNamespace: {
+                    type: 'string',
+                    description: 'New namespace path to move artifact to (e.g., "utaba/main/services/user")',
+                    maxLength: 200
+                },
+                updateFilename: {
+                    type: 'string',
+                    description: 'New filename for the artifact (e.g., "UserService.ts")',
+                    maxLength: 100
+                },
+                updateMimeType: {
+                    type: 'string',
+                    description: 'New MIME type for the artifact (e.g., "application/typescript")',
+                    maxLength: 100
+                },
+                updateTechnology: {
+                    type: 'string',
+                    description: 'New technology stack (e.g., "typescript", "python", "nextjs")',
+                    maxLength: 50
+                },
+                updateTags: {
+                    type: 'string',
+                    description: 'New comma-separated tags for categorization',
+                    maxLength: 500
+                }
+            },
+            required: ['path'],
+            additionalProperties: false
+        };
+    }
+    async handleExecute(params) {
+        const { path, updateDescription, updateNamespace, updateFilename, updateMimeType, updateTechnology, updateTags } = params;
+        this.logger.debug('EditArtifactMetadataTool', `Editing artifact metadata: ${path}`, '', {
+            hasDescriptionUpdate: !!updateDescription,
+            hasNamespaceUpdate: !!updateNamespace,
+            hasFilenameUpdate: !!updateFilename
+        });
+        try {
+            // Parse the current path to extract components
+            const pathComponents = parsePath(path);
+            // Validate path components exist including repository
+            if (!pathComponents.author || !pathComponents.repository || !pathComponents.category || !pathComponents.subcategory || !pathComponents.filename) {
+                throw new McpError(McpErrorCode.InvalidParams, 'Path must contain author, repository, category, subcategory, and filename (e.g., "utaba/main/commands/user/CreateUserCommand.ts")');
+            }
+            // Validate that at least one update field is provided
+            const hasUpdates = !!(updateDescription || updateNamespace || updateFilename || updateMimeType || updateTechnology || updateTags);
+            if (!hasUpdates) {
+                throw new McpError(McpErrorCode.InvalidParams, 'At least one update field must be provided (updateDescription, updateNamespace, updateFilename, updateMimeType, updateTechnology, or updateTags)');
+            }
+            // Prepare the edit data
+            const editData = {};
+            if (updateDescription !== undefined)
+                editData.updateDescription = updateDescription;
+            if (updateNamespace !== undefined)
+                editData.updateNamespace = updateNamespace;
+            if (updateFilename !== undefined)
+                editData.updateFilename = updateFilename;
+            if (updateMimeType !== undefined)
+                editData.updateMimeType = updateMimeType;
+            if (updateTechnology !== undefined)
+                editData.updateTechnology = updateTechnology;
+            if (updateTags !== undefined)
+                editData.updateTags = updateTags;
+            // Call the API to edit the artifact metadata
+            const result = await this.ucmClient.editArtifactMetadata(pathComponents.author, pathComponents.repository, pathComponents.category, pathComponents.subcategory, pathComponents.filename, editData);
+            // Handle response structure - API might return wrapped in 'data' or direct
+            const responseData = result.data || result;
+            // Build successful response with operation details
+            const isMove = !!(updateNamespace || updateFilename);
+            const operation = isMove ? 'move' : 'metadata_update';
+            const response = {
+                success: true,
+                operation,
+                artifact: {
+                    originalPath: path,
+                    newPath: isMove ?
+                        `${updateNamespace || `${pathComponents.author}/${pathComponents.repository}/${pathComponents.category}/${pathComponents.subcategory}`}/${updateFilename || pathComponents.filename}` :
+                        path,
+                    updatedFields: Object.keys(editData),
+                    affectedVersions: responseData.affectedVersions || (isMove ? 'all' : 'latest'),
+                },
+                details: responseData.details || 'Artifact metadata updated successfully',
+                _links: responseData._links || {}
+            };
+            this.logger.info('EditArtifactMetadataTool', `Artifact edited successfully: ${path}`, '', {
+                operation,
+                updatedFields: Object.keys(editData),
+                affectedVersions: response.artifact.affectedVersions
+            });
+            return response;
+        }
+        catch (error) {
+            this.logger.error('EditArtifactMetadataTool', `Failed to edit artifact: ${path}`, '', error);
+            // Enhanced error handling for edit operations
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            if (errorMessage?.includes('not found')) {
+                throw new McpError(McpErrorCode.InvalidParams, `Artifact not found at path: ${path}. Please verify the path is correct and the artifact exists.`);
+            }
+            if (errorMessage?.includes('permission') || errorMessage?.includes('unauthorized')) {
+                throw new McpError(McpErrorCode.InvalidParams, `Insufficient permissions to edit artifact at: ${path}. You must have write access to both source and destination namespaces for move operations.`);
+            }
+            if (errorMessage?.includes('destination already exists')) {
+                throw new McpError(McpErrorCode.InvalidParams, 'Destination artifact already exists. Choose a different filename or namespace for move operations.');
+            }
+            if (errorMessage?.includes('Invalid namespace format')) {
+                throw new McpError(McpErrorCode.InvalidParams, `Invalid namespace format in updateNamespace. Must follow pattern "author/repository/category/subcategory". Example: "${this.publishingAuthorId || '0000000000'}/main/services/user"`);
+            }
+            if (errorMessage?.includes('Author not found')) {
+                throw new McpError(McpErrorCode.InvalidParams, `Author not found. Ensure the path uses a valid author identifier.`);
+            }
+            throw error;
+        }
+    }
+    validateParams(params) {
+        super.validateParams(params);
+        const { path, updateNamespace, updateFilename, updateDescription } = params;
+        // Validate path format
+        if (!path || typeof path !== 'string') {
+            throw new McpError(McpErrorCode.InvalidParams, 'path is required and must be a string');
+        }
+        // Basic path validation - should contain at least author/repository/category/subcategory/filename
+        const pathParts = path.split('/');
+        if (pathParts.length < 5) {
+            throw new McpError(McpErrorCode.InvalidParams, 'path must contain at least author/repository/category/subcategory/filename');
+        }
+        // Validate updateNamespace format if provided
+        if (updateNamespace && updateNamespace.length > 0) {
+            const namespaceParts = updateNamespace.split('/');
+            if (namespaceParts.length !== 4) {
+                throw new McpError(McpErrorCode.InvalidParams, 'updateNamespace must follow format "author/repository/category/subcategory"');
+            }
+        }
+        // Validate updateFilename if provided
+        if (updateFilename && updateFilename.length > 0) {
+            if (!/^[^\/\\:*?"<>|]+\.[a-zA-Z0-9]+$/.test(updateFilename)) {
+                throw new McpError(McpErrorCode.InvalidParams, 'updateFilename must be a valid filename with extension (e.g., "UserService.ts")');
+            }
+        }
+        // Validate description length
+        if (updateDescription && updateDescription.length > 1000) {
+            throw new McpError(McpErrorCode.InvalidParams, 'updateDescription cannot exceed 1000 characters');
+        }
+    }
+}
+//# sourceMappingURL=EditArtifactMetadataTool.js.map

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

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