@utaba/ucm-mcp-server 4.2.2 → 4.3.0

package/dist/tools/sharepoint/SharePointListConnectionsTool.d.ts

@@ -0,0 +1,19 @@
+/**
+ * SharePointListConnectionsTool
+ * List all SharePoint connections available to the user
+ */
+import { BaseToolController } from '../base/BaseToolController.js';
+import { UcmLocalApiClient } from '../../clients/UcmLocalApiClient.js';
+import { ILogger } from '../../interfaces/ILogger.js';
+export declare class SharePointListConnectionsTool 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: {
+        limit?: number;
+        offset?: number;
+    }): Promise<any>;
+}
+//# sourceMappingURL=SharePointListConnectionsTool.d.ts.map

package/dist/tools/sharepoint/SharePointListConnectionsTool.js

@@ -0,0 +1,84 @@
+/**
+ * SharePointListConnectionsTool
+ * List all SharePoint connections available to the user
+ */
+import { BaseToolController } from '../base/BaseToolController.js';
+import { McpError, McpErrorCode } from '../../utils/McpErrorHandler.js';
+export class SharePointListConnectionsTool extends BaseToolController {
+    constructor(ucmClient, logger, publishingAuthorId) {
+        super(ucmClient, logger, publishingAuthorId);
+    }
+    get name() {
+        return 'ucm_list_connections';
+    }
+    get description() {
+        return 'List all External connections including SharePoint available to the user. Returns connection details, use this to discover available connections before searching or browsing.';
+    }
+    get inputSchema() {
+        return {
+            type: 'object',
+            properties: {
+                limit: {
+                    type: 'number',
+                    description: 'Maximum number of connections to return (default: 20, max: 100)',
+                    minimum: 1,
+                    maximum: 100
+                },
+                offset: {
+                    type: 'number',
+                    description: 'Number of connections to skip for pagination (default: 0)',
+                    minimum: 0
+                }
+            },
+            required: []
+        };
+    }
+    validateParams(params) {
+        super.validateParams(params);
+        // Validate limit if provided
+        if (params.limit !== undefined) {
+            if (typeof params.limit !== 'number' || params.limit < 1 || params.limit > 100) {
+                throw new McpError(McpErrorCode.InvalidParams, 'Limit must be a number between 1 and 100');
+            }
+        }
+        // Validate offset if provided
+        if (params.offset !== undefined) {
+            if (typeof params.offset !== 'number' || params.offset < 0) {
+                throw new McpError(McpErrorCode.InvalidParams, 'Offset must be a number greater than or equal to 0');
+            }
+        }
+    }
+    async handleExecute(params) {
+        this.logger.info('SharePointListConnectionsTool', `Listing SharePoint connections (limit: ${params.limit || 20}, offset: ${params.offset || 0})`);
+        try {
+            // Get organizationId from auth ticket (via UcmApiClient)
+            // Call API to list connections with pagination params
+            const result = await this.ucmClient.listExternalConnections({
+                limit: params.limit,
+                offset: params.offset
+            });
+            this.logger.info('listConnections', 'Connections retrieved successfully', '', {
+                contentLength: result.length,
+                source: 'UCM API /api/v1/connections'
+            });
+            return result;
+        }
+        catch (error) {
+            this.logger.error('SharePointListConnectionsTool: Failed to list connections', error);
+            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 list SharePoint connections'}`);
+                }
+                throw new McpError(McpErrorCode.InternalError, `API error: ${errorData?.message || error.message}`);
+            }
+            throw new McpError(McpErrorCode.InternalError, `Failed to list external connections: ${error.message}`);
+        }
+    }
+}
+//# sourceMappingURL=SharePointListConnectionsTool.js.map

package/dist/tools/sharepoint/SharePointListFoldersTool.d.ts

@@ -0,0 +1,21 @@
+/**
+ * SharePointListFoldersTool
+ * List folders in SharePoint document library
+ */
+import { BaseToolController } from '../base/BaseToolController.js';
+import { UcmLocalApiClient } from '../../clients/UcmLocalApiClient.js';
+import { ILogger } from '../../interfaces/ILogger.js';
+export declare class SharePointListFoldersTool 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;
+        folderPath?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<any>;
+}
+//# sourceMappingURL=SharePointListFoldersTool.d.ts.map

package/dist/tools/sharepoint/SharePointListFoldersTool.js

@@ -0,0 +1,140 @@
+/**
+ * SharePointListFoldersTool
+ * List folders in SharePoint document library
+ */
+import { BaseToolController } from '../base/BaseToolController.js';
+import { McpError, McpErrorCode } from '../../utils/McpErrorHandler.js';
+import { SharePointErrorHandler } from '../../utils/SharePointErrorHandler.js';
+export class SharePointListFoldersTool extends BaseToolController {
+    constructor(ucmClient, logger, publishingAuthorId) {
+        super(ucmClient, logger, publishingAuthorId);
+    }
+    get name() {
+        return 'ucm_sharepoint_list_folders';
+    }
+    get description() {
+        return 'Browse SharePoint hierarchically: "/" lists document libraries, "/LibraryName" lists library root, "/LibraryName/Folder" lists subfolder. Supports pagination. Use ucm_list_connections first to get connection ID.';
+    }
+    get inputSchema() {
+        return {
+            type: 'object',
+            properties: {
+                connectionId: {
+                    type: 'string',
+                    description: 'SharePoint connection ID to use for listing folders (get this from list_connections)',
+                    minLength: 36,
+                    maxLength: 36
+                },
+                folderPath: {
+                    type: 'string',
+                    description: 'Path: "/" = list libraries (e.g., Documents, Sales), "/Documents" = list library root, "/Documents/Projects" = list subfolder. Default: "/"',
+                    maxLength: 1000
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Maximum number of items to return (default: 50, max: 200)',
+                    minimum: 1,
+                    maximum: 200
+                },
+                offset: {
+                    type: 'number',
+                    description: 'Number of items to skip for pagination (default: 0)',
+                    minimum: 0
+                }
+            },
+            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');
+        }
+        // Set default folder path if not provided
+        if (!params.folderPath) {
+            params.folderPath = '/';
+        }
+        // Validate folder path format
+        if (params.folderPath && typeof params.folderPath !== 'string') {
+            throw new McpError(McpErrorCode.InvalidParams, 'Folder path must be a string');
+        }
+        // Ensure folder path starts with /
+        if (params.folderPath && !params.folderPath.startsWith('/')) {
+            params.folderPath = '/' + params.folderPath;
+        }
+        // Validate and set default limit
+        if (params.limit !== undefined) {
+            if (typeof params.limit !== 'number' || params.limit < 1 || params.limit > 200) {
+                throw new McpError(McpErrorCode.InvalidParams, 'Limit must be between 1 and 200');
+            }
+        }
+        else {
+            params.limit = 50;
+        }
+        // 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;
+        }
+    }
+    async handleExecute(params) {
+        this.logger.info('SharePointListFoldersTool', `Listing folders at path: ${params.folderPath}`);
+        try {
+            // Call the API to list SharePoint folders
+            // organizationId is auto-detected from auth token in V1 API
+            const listParams = {
+                folderPath: params.folderPath,
+                limit: params.limit,
+                offset: params.offset
+            };
+            // Make API call via UCM client (V1 API)
+            const result = await this.ucmClient.sharePointListFolders(params.connectionId, listParams);
+            this.logger.info('SharePointListFoldersTool', `Listed ${result.folders?.length || 0} folders and ${result.files?.length || 0} files`);
+            // Format response from V1 API
+            const response = {
+                success: true,
+                path: result.path || params.folderPath,
+                totalFolders: result.totalFolders || 0,
+                totalFiles: result.totalFiles || 0,
+                total: result.total || 0,
+                hasMore: result.hasMore || false,
+                limit: params.limit,
+                offset: params.offset,
+                folders: result.folders?.map((folder) => ({
+                    name: folder.name,
+                    webUrl: folder.webUrl,
+                    size: folder.size,
+                    createdDateTime: folder.createdDateTime,
+                    lastModifiedDateTime: folder.lastModifiedDateTime
+                })) || [],
+                files: result.files?.map((file) => ({
+                    name: file.name,
+                    webUrl: file.webUrl,
+                    size: file.size,
+                    mimeType: file.mimeType,
+                    createdDateTime: file.createdDateTime,
+                    lastModifiedDateTime: file.lastModifiedDateTime
+                })) || []
+            };
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(response, null, 2)
+                    }
+                ]
+            };
+        }
+        catch (error) {
+            return SharePointErrorHandler.handle(error, this.logger, 'SharePointListFoldersTool');
+        }
+    }
+}
+//# sourceMappingURL=SharePointListFoldersTool.js.map

package/dist/tools/sharepoint/SharePointReadFileTool.d.ts

@@ -0,0 +1,22 @@
+/**
+ * SharePointReadFileTool
+ * Read and convert SharePoint files to text
+ */
+import { BaseToolController } from '../base/BaseToolController.js';
+import { UcmLocalApiClient } from '../../clients/UcmLocalApiClient.js';
+import { ILogger } from '../../interfaces/ILogger.js';
+export declare class SharePointReadFileTool 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;
+        webUrl: string;
+        extractMetadata?: boolean;
+        offset?: number;
+        limit?: number;
+    }): Promise<any>;
+}
+//# sourceMappingURL=SharePointReadFileTool.d.ts.map

package/dist/tools/sharepoint/SharePointReadFileTool.js

@@ -0,0 +1,145 @@
+/**
+ * SharePointReadFileTool
+ * Read and convert SharePoint files to text
+ */
+import { BaseToolController } from '../base/BaseToolController.js';
+import { McpError, McpErrorCode } from '../../utils/McpErrorHandler.js';
+import { SharePointErrorHandler } from '../../utils/SharePointErrorHandler.js';
+export class SharePointReadFileTool extends BaseToolController {
+    constructor(ucmClient, logger, publishingAuthorId) {
+        super(ucmClient, logger, publishingAuthorId);
+    }
+    get name() {
+        return 'ucm_sharepoint_read_file';
+    }
+    get description() {
+        return 'Read a file from SharePoint and convert it to text. Supports Office documents (Word, Excel, PowerPoint), PDFs, and text files. Maximum file size is 20MB. Provide either a full SharePoint URL or relative path. Supports pagination with offset/limit for TEXT CONTENT ONLY. Pagination parameters are ignored for binary files (images, PDFs with embedded images).';
+    }
+    get inputSchema() {
+        return {
+            type: 'object',
+            properties: {
+                connectionId: {
+                    type: 'string',
+                    description: 'SharePoint connection ID to use for reading file (get this from list_connections)',
+                    minLength: 36,
+                    maxLength: 36
+                },
+                webUrl: {
+                    type: 'string',
+                    description: 'SharePoint file URL (e.g., "https://contoso.sharepoint.com/sites/Sales/Shared Documents/report.docx") OR relative path ("/Shared Documents/report.docx")',
+                    minLength: 1,
+                    maxLength: 2000
+                },
+                extractMetadata: {
+                    type: 'boolean',
+                    description: 'Include file metadata in response (default: true)'
+                },
+                offset: {
+                    type: 'number',
+                    description: 'Number of characters to skip from the start of the content (default: 0). Pagination for text content only - ignored for binary/image files.',
+                    minimum: 0
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Maximum number of characters to return (default: unlimited). Pagination for text content only - ignored for binary/image files.',
+                    minimum: 1
+                }
+            },
+            required: ['connectionId', 'webUrl'],
+            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 that webUrl is provided
+        if (!params.webUrl || typeof params.webUrl !== 'string' || params.webUrl.trim() === '') {
+            throw new McpError(McpErrorCode.InvalidParams, 'File URL is required and must be a non-empty string');
+        }
+        // Set boolean defaults
+        if (params.extractMetadata === undefined) {
+            params.extractMetadata = true;
+        }
+        // Validate and set offset/limit defaults
+        if (params.offset !== undefined) {
+            if (typeof params.offset !== 'number' || params.offset < 0) {
+                throw new McpError(McpErrorCode.InvalidParams, 'Offset must be a non-negative number');
+            }
+        }
+        else {
+            params.offset = 0;
+        }
+        if (params.limit !== undefined) {
+            if (typeof params.limit !== 'number' || params.limit < 1) {
+                throw new McpError(McpErrorCode.InvalidParams, 'Limit must be a positive number');
+            }
+        }
+    }
+    async handleExecute(params) {
+        this.logger.info('SharePointReadFileTool', `Reading file: ${params.webUrl} (offset: ${params.offset || 0}, limit: ${params.limit || 'unlimited'})`);
+        try {
+            // Call the API to read and convert SharePoint file
+            // organizationId is auto-detected from auth token in V1 API
+            const readParams = {
+                fileUrl: params.webUrl, // Map webUrl parameter to fileUrl for internal command
+                extractMetadata: params.extractMetadata
+            };
+            // Add pagination parameters if provided
+            if (params.offset !== undefined) {
+                readParams.offset = params.offset;
+            }
+            if (params.limit !== undefined) {
+                readParams.limit = params.limit;
+            }
+            // Make API call via UCM client (V1 API)
+            const result = await this.ucmClient.sharePointReadFile(params.connectionId, readParams);
+            this.logger.info('SharePointReadFileTool', `File read successfully: ${result.fileName}`);
+            // Format response
+            const response = {
+                success: true,
+                fileName: result.fileName,
+                fileType: result.fileType,
+                contentLength: result.contentLength,
+                returnedLength: result.returnedLength,
+                offset: result.offset,
+                hasMore: result.hasMore,
+                content: result.content,
+                conversionNotes: result.conversionNotes,
+                convertedAt: result.convertedAt
+            };
+            // Add nextOffset if there's more content
+            if (result.hasMore && result.nextOffset !== undefined) {
+                response.nextOffset = result.nextOffset;
+            }
+            // Include metadata if requested
+            if (params.extractMetadata && result.metadata) {
+                response.metadata = result.metadata;
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(response, null, 2)
+                    }
+                ]
+            };
+        }
+        catch (error) {
+            // Handle ReadFile-specific errors first
+            if (error?.response?.status === 400 && error?.response?.data?.error === 'TENANT_MISMATCH') {
+                throw new McpError(McpErrorCode.InvalidParams, 'File URL does not match the connection tenant');
+            }
+            if (error?.response?.status === 413 || error?.message?.includes('size')) {
+                throw new McpError(McpErrorCode.InvalidParams, 'File exceeds maximum size limit of 20MB');
+            }
+            // Delegate to common SharePoint error handler for generic errors
+            return SharePointErrorHandler.handle(error, this.logger, 'SharePointReadFileTool');
+        }
+    }
+}
+//# sourceMappingURL=SharePointReadFileTool.js.map

package/dist/tools/sharepoint/SharePointReadRelatedFileTool.d.ts

@@ -0,0 +1,18 @@
+/**
+ * SharePointReadRelatedFileTool
+ * Retrieve related file (image/embedded file) extracted from a SharePoint document
+ */
+import { BaseToolController } from '../base/BaseToolController.js';
+import { UcmLocalApiClient } from '../../clients/UcmLocalApiClient.js';
+import { ILogger } from '../../interfaces/ILogger.js';
+export declare class SharePointReadRelatedFileTool 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: {
+        uri: string;
+    }): Promise<any>;
+}
+//# sourceMappingURL=SharePointReadRelatedFileTool.d.ts.map

package/dist/tools/sharepoint/SharePointReadRelatedFileTool.js

@@ -0,0 +1,102 @@
+/**
+ * SharePointReadRelatedFileTool
+ * Retrieve related file (image/embedded file) extracted from a SharePoint document
+ */
+import { BaseToolController } from '../base/BaseToolController.js';
+import { McpError, McpErrorCode } from '../../utils/McpErrorHandler.js';
+export class SharePointReadRelatedFileTool extends BaseToolController {
+    constructor(ucmClient, logger, publishingAuthorId) {
+        super(ucmClient, logger, publishingAuthorId);
+    }
+    get name() {
+        return 'ucm_sharepoint_read_relatedfile';
+    }
+    get description() {
+        return 'Retrieve a related file (image or embedded file) that was extracted from a SharePoint document. Pass the full URI from markdown. Returns complete file. Large images (>500KB original size) may fail with size limit error.';
+    }
+    get inputSchema() {
+        return {
+            type: 'object',
+            properties: {
+                uri: {
+                    type: 'string',
+                    description: 'Full URI from markdown (e.g., "file1.jpg?connectionId=...&fileId=...&eTag=..." or without protocol prefix)',
+                    minLength: 1,
+                    maxLength: 2000
+                }
+            },
+            required: ['uri'],
+            additionalProperties: false
+        };
+    }
+    validateParams(params) {
+        super.validateParams(params);
+        // Validate URI is provided and is a non-empty string
+        if (!params.uri || typeof params.uri !== 'string' || params.uri.trim() === '') {
+            throw new McpError(McpErrorCode.InvalidParams, 'URI is required and must be a non-empty string');
+        }
+        // Don't validate format - let server handle parsing and auto-correction
+    }
+    async handleExecute(params) {
+        this.logger.info('SharePointReadRelatedFileTool', `Reading related file from URI: ${params.uri}`);
+        try {
+            // Call the API to read the related file (no pagination - always complete file)
+            const result = await this.ucmClient.sharePointReadRelatedFile(params.uri);
+            this.logger.info('SharePointReadRelatedFileTool', `Related file retrieved: ${result.fileName}, size: ${result.size} bytes, content length: ${result.content.length} chars`);
+            // Check if base64 content exceeds safe MCP token limit (~15,000 characters)
+            // This prevents MCP response errors for large images
+            if (result.content.length > 15000) {
+                throw new McpError(McpErrorCode.InternalError, 'Image file too large for MCP response. Please resize the image in SharePoint or use the web UI to download.');
+            }
+            // Check if this is an image file - return as image resource for visual analysis
+            if (result.mimeType && result.mimeType.startsWith('image/')) {
+                return {
+                    content: [
+                        {
+                            type: 'image',
+                            data: result.content, // base64 encoded image data
+                            mimeType: result.mimeType
+                        },
+                        {
+                            type: 'text',
+                            text: `Image: ${result.fileName}\nSize: ${result.size} bytes\nType: ${result.mimeType}`
+                        }
+                    ]
+                };
+            }
+            // For non-image files, return file information as JSON
+            const response = {
+                success: true,
+                fileName: result.fileName,
+                mimeType: result.mimeType,
+                size: result.size,
+                contentLength: result.content.length,
+                content: result.content, // base64 encoded binary data
+                encoding: 'base64'
+            };
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(response, null, 2)
+                    }
+                ]
+            };
+        }
+        catch (error) {
+            this.logger.error('SharePointReadRelatedFileTool', 'Read related file operation failed', '', error);
+            // Format error response
+            if (error?.response?.status === 404) {
+                throw new McpError(McpErrorCode.InvalidParams, 'Related file not found. File may no longer be available. Re-read the parent document to access related files.');
+            }
+            if (error?.response?.status === 401 || error?.response?.status === 403) {
+                throw new McpError(McpErrorCode.InvalidParams, 'Not authorized to access this SharePoint connection or file');
+            }
+            if (error?.response?.status === 400) {
+                throw new McpError(McpErrorCode.InvalidParams, error?.response?.data?.message || 'Invalid request parameters');
+            }
+            throw new McpError(McpErrorCode.InternalError, `SharePoint read related file failed: ${error?.message || 'Unknown error'}`, { originalError: error?.message });
+        }
+    }
+}
+//# sourceMappingURL=SharePointReadRelatedFileTool.js.map

package/dist/tools/sharepoint/SharePointSearchTool.d.ts

@@ -0,0 +1,22 @@
+/**
+ * SharePointSearchTool
+ * Search SharePoint documents with text query
+ */
+import { BaseToolController } from '../base/BaseToolController.js';
+import { UcmLocalApiClient } from '../../clients/UcmLocalApiClient.js';
+import { ILogger } from '../../interfaces/ILogger.js';
+export declare class SharePointSearchTool 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;
+        query: string;
+        limit?: number;
+        offset?: number;
+        fileType?: string;
+    }): Promise<any>;
+}
+//# sourceMappingURL=SharePointSearchTool.d.ts.map