@utaba/ucm-mcp-server 6.5.1 → 6.6.0

package/dist/mcp-server/tools/sharepoint/SharePointSearchTool.js

@@ -0,0 +1,125 @@
+/**
+ * SharePointSearchTool
+ * Search SharePoint documents with text query
+ */
+import { BaseToolController } from '../base/BaseToolController.js';
+import { McpError, McpErrorCode } from '../../utils/McpErrorHandler.js';
+import { SharePointErrorHandler } from '../../utils/SharePointErrorHandler.js';
+export class SharePointSearchTool extends BaseToolController {
+    constructor(ucmClient, logger, publishingAuthorId) {
+        super(ucmClient, logger, publishingAuthorId);
+    }
+    get name() {
+        return 'ucm_sharepoint_search_documents';
+    }
+    get description() {
+        return 'Search SharePoint documents with text query using Microsoft Search API. Returns document metadata with snippets. Supports pagination and file type filtering via KQL.';
+    }
+    get inputSchema() {
+        return {
+            type: 'object',
+            properties: {
+                connectionId: {
+                    type: 'string',
+                    description: 'SharePoint connection ID to use for searching (get this from list_connections)',
+                    minLength: 36,
+                    maxLength: 36
+                },
+                query: {
+                    type: 'string',
+                    description: 'Search query text (optional, defaults to * for all documents)',
+                    maxLength: 500
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Maximum number of results to return (default: 20, max: 100)',
+                    minimum: 1,
+                    maximum: 100
+                },
+                offset: {
+                    type: 'number',
+                    description: 'Number of results to skip for pagination (default: 0)',
+                    minimum: 0
+                },
+                fileType: {
+                    type: 'string',
+                    description: 'Filter by file extension (e.g., "docx", "pdf", "xlsx") - uses Microsoft Search KQL filtering',
+                    maxLength: 10
+                }
+            },
+            required: ['connectionId'],
+            additionalProperties: false
+        };
+    }
+    validateParams(params) {
+        super.validateParams(params);
+        // Validate connectionId is UUID format
+        const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+        if (!uuidPattern.test(params.connectionId)) {
+            throw new McpError(McpErrorCode.InvalidParams, 'Connection ID must be a valid UUID');
+        }
+        // Validate query
+        if (!params.query || typeof params.query !== 'string' || params.query.trim() === '') {
+            params.query = '*';
+        }
+        // Validate and set default limit
+        if (params.limit !== undefined) {
+            if (typeof params.limit !== 'number' || params.limit < 1 || params.limit > 100) {
+                throw new McpError(McpErrorCode.InvalidParams, 'Limit must be between 1 and 100');
+            }
+        }
+        else {
+            params.limit = 20;
+        }
+        // Validate and set default offset
+        if (params.offset !== undefined) {
+            if (typeof params.offset !== 'number' || params.offset < 0) {
+                throw new McpError(McpErrorCode.InvalidParams, 'Offset must be 0 or greater');
+            }
+        }
+        else {
+            params.offset = 0;
+        }
+        // Validate file type if provided (now supported via Microsoft Search API KQL)
+        if (params.fileType && !/^[a-zA-Z0-9]{1,10}$/.test(params.fileType)) {
+            throw new McpError(McpErrorCode.InvalidParams, 'File type must be alphanumeric and no more than 10 characters');
+        }
+    }
+    async handleExecute(params) {
+        this.logger.info('SharePointSearchTool', `Searching SharePoint with query: "${params.query}"`);
+        try {
+            // Call the API to search SharePoint documents
+            const searchParams = {
+                query: params.query,
+                limit: params.limit,
+                offset: params.offset,
+                fileType: params.fileType
+            };
+            // Make API call via UCM client
+            const result = await this.ucmClient.sharePointSearch(params.connectionId, searchParams);
+            this.logger.info('SharePointSearchTool', `Search completed, found ${result.totalCount} results`);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            query: params.query,
+                            totalCount: result.totalCount,
+                            returnedCount: result.files?.length || 0,
+                            hasMore: result.hasMore,
+                            limit: params.limit,
+                            offset: params.offset,
+                            fileType: params.fileType,
+                            files: result.files || []
+                        }, null, 2)
+                    }
+                ]
+            };
+        }
+        catch (error) {
+            return SharePointErrorHandler.handle(error, this.logger, 'SharePointSearchTool');
+        }
+    }
+}
+//# sourceMappingURL=SharePointSearchTool.js.map

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

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

@@ -0,0 +1,49 @@
+import { BaseToolController } from '../base/BaseToolController.js';
+export class AuthorIndexTool extends BaseToolController {
+    constructor(ucmClient, logger, publishingAuthorId) {
+        super(ucmClient, logger, publishingAuthorId);
+    }
+    get name() {
+        return 'ucm_workspace_get_index';
+    }
+    get description() {
+        return 'Discover a dynamic markdown index guide for AI assistants working with a workspace\'s content.';
+    }
+    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('AuthorIndexTool', `Retrieving author index for: ${author}`);
+        try {
+            // Get author index content from API (author-level index, not repository-specific)
+            const authorIndexContent = await this.ucmClient.getAuthorIndex(author);
+            this.logger.info('AuthorIndexTool', 'Author index retrieved successfully', '', {
+                author,
+                contentLength: authorIndexContent.length,
+                source: `UCM API /api/v1/authors/${author}/index`
+            });
+            return authorIndexContent;
+        }
+        catch (error) {
+            let errorMessage = `Failed to retrieve author index 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('AuthorIndexTool', `${errorMessage}`, '', error);
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=AuthorIndexTool.js.map

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

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

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

@@ -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 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

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

@@ -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 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

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

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

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

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

@@ -0,0 +1,67 @@
+// MCP-specific error handling following MCP standards
+export var McpErrorCode;
+(function (McpErrorCode) {
+    McpErrorCode[McpErrorCode["ParseError"] = -32700] = "ParseError";
+    McpErrorCode[McpErrorCode["InvalidRequest"] = -32600] = "InvalidRequest";
+    McpErrorCode[McpErrorCode["MethodNotFound"] = -32601] = "MethodNotFound";
+    McpErrorCode[McpErrorCode["InvalidParams"] = -32602] = "InvalidParams";
+    McpErrorCode[McpErrorCode["InternalError"] = -32603] = "InternalError";
+    McpErrorCode[McpErrorCode["ExternalServiceUnavailable"] = -32001] = "ExternalServiceUnavailable"; // External resource offline/unavailable
+})(McpErrorCode || (McpErrorCode = {}));
+export class McpError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+        this.name = 'McpError';
+    }
+    toResponse() {
+        return {
+            error: {
+                code: this.code,
+                message: this.message,
+                data: this.data
+            }
+        };
+    }
+}
+export class McpErrorHandler {
+    static formatError(error) {
+        if (error instanceof McpError) {
+            return error;
+        }
+        if (error.error) {
+            error = error.error;
+        }
+        if (error instanceof McpError) {
+            return error;
+        }
+        // Extract error message from various sources
+        let message = error.message || error.toString();
+        if (!message) {
+            message = JSON.stringify(error);
+        }
+        // Map common errors to MCP error codes
+        if (message?.includes('not found')) {
+            return new McpError(McpErrorCode.InvalidParams, message, { originalError: error });
+        }
+        if (message?.includes('validation')) {
+            return new McpError(McpErrorCode.InvalidParams, 'Parameter validation failed', { originalError: error });
+        }
+        if (message?.includes('ECONNREFUSED')) {
+            return new McpError(McpErrorCode.ExternalServiceUnavailable, 'External API is unavailable, try 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

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