@utaba/ucm-mcp-server 4.2.2 → 4.3.0

package/dist/tools/sharepoint/SharePointSearchTool.js

@@ -0,0 +1,134 @@
+/**
+ * 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?.map((file) => ({
+                                id: file.id,
+                                name: file.name,
+                                webUrl: file.webUrl,
+                                size: file.size,
+                                mimeType: file.mimeType,
+                                createdDateTime: file.createdDateTime,
+                                lastModifiedDateTime: file.lastModifiedDateTime,
+                                folder: file.folder
+                            })) || []
+                        }, null, 2)
+                    }
+                ]
+            };
+        }
+        catch (error) {
+            return SharePointErrorHandler.handle(error, this.logger, 'SharePointSearchTool');
+        }
+    }
+}
+//# sourceMappingURL=SharePointSearchTool.js.map

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

@@ -0,0 +1,22 @@
+/**
+ * SharePointSignOutTool
+ * Revoke user's OnBehalfOf authorization for a SharePoint connection
+ */
+import { BaseToolController } from '../base/BaseToolController.js';
+import { UcmLocalApiClient } from '../../clients/UcmLocalApiClient.js';
+import { ILogger } from '../../interfaces/ILogger.js';
+export declare class SharePointSignOutTool 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;
+    }): Promise<any>;
+    /**
+     * Format sign out response as markdown
+     */
+    private formatSignOutResponse;
+}
+//# sourceMappingURL=SharePointSignOutTool.d.ts.map

package/dist/tools/sharepoint/SharePointSignOutTool.js

@@ -0,0 +1,108 @@
+/**
+ * SharePointSignOutTool
+ * Revoke user's OnBehalfOf authorization for a SharePoint connection
+ */
+import { BaseToolController } from '../base/BaseToolController.js';
+import { McpError, McpErrorCode } from '../../utils/McpErrorHandler.js';
+export class SharePointSignOutTool extends BaseToolController {
+    constructor(ucmClient, logger, publishingAuthorId) {
+        super(ucmClient, logger, publishingAuthorId);
+    }
+    get name() {
+        return 'ucm_sharepoint_signout';
+    }
+    get description() {
+        return 'This signs the user out only for connections with user-delegated permissions.';
+    }
+    get inputSchema() {
+        return {
+            type: 'object',
+            properties: {
+                connectionId: {
+                    type: 'string',
+                    description: 'SharePoint connection ID to revoke authorization for (get this from list_connections)',
+                    minLength: 36,
+                    maxLength: 36
+                }
+            },
+            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('SharePointSignOutTool', `Revoking SharePoint authorization for connection ${params.connectionId}`);
+        try {
+            // Call API to revoke authorization
+            const result = await this.ucmClient.sharePointSignOut(params.connectionId);
+            this.logger.info('SharePointSignOutTool', 'Authorization revoked successfully', '', {
+                connectionId: params.connectionId,
+                success: result.success
+            });
+            // Return structured markdown response
+            const markdown = this.formatSignOutResponse(result);
+            return markdown;
+        }
+        catch (error) {
+            this.logger.error('SharePointSignOutTool: Failed to revoke authorization', 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 revoke SharePoint authorization'}`);
+                }
+                if (status === 404) {
+                    throw new McpError(McpErrorCode.InvalidRequest, `Connection not found: ${errorData?.message || 'SharePoint connection does not exist'}`);
+                }
+                if (status === 400 && errorData?.error === 'INVALID_AUTH_TYPE') {
+                    throw new McpError(McpErrorCode.InvalidRequest, `Invalid operation: Only OnBehalfOf (user-delegated) connections support user authorization. This connection uses ServicePrincipal authentication.`);
+                }
+                throw new McpError(McpErrorCode.InternalError, `API error: ${errorData?.message || error.message}`);
+            }
+            throw new McpError(McpErrorCode.InternalError, `Failed to revoke SharePoint authorization: ${error.message}`);
+        }
+    }
+    /**
+     * Format sign out response as markdown
+     */
+    formatSignOutResponse(result) {
+        const lines = [];
+        lines.push('# SharePoint Authorization Revoked\n');
+        if (result.success) {
+            lines.push('✅ **Status**: Authorization successfully revoked\n');
+            lines.push(`**Connection ID**: ${result.connectionId}\n`);
+            if (result.revokedAt) {
+                lines.push(`**Revoked At**: ${new Date(result.revokedAt).toLocaleString()}\n`);
+            }
+            lines.push('\n## What This Means\n');
+            lines.push('- Your access tokens have been deleted from the system');
+            lines.push('- You are now signed out of this SharePoint connection');
+            lines.push('- To access SharePoint files again, you must re-authorize\n');
+            if (result._links?.authorize) {
+                lines.push('\n## Re-authorize Access\n');
+                lines.push(`To grant access again, visit: ${result._links.authorize.href}\n`);
+            }
+        }
+        else {
+            lines.push('⚠️ **Status**: Revocation failed or not needed\n');
+            lines.push(`**Message**: ${result.message}\n`);
+            if (result.details?.reason) {
+                lines.push(`**Reason**: ${result.details.reason}\n`);
+            }
+        }
+        return lines.join('\n');
+    }
+}
+//# sourceMappingURL=SharePointSignOutTool.js.map

package/dist/utils/SharePointErrorHandler.d.ts

@@ -0,0 +1,28 @@
+/**
+ * SharePointErrorHandler
+ * Centralized error handling for SharePoint MCP tools
+ */
+import { ILogger } from '../interfaces/ILogger.js';
+/**
+ * Standard MCP tool result with content array
+ */
+interface ToolResult {
+    content: Array<{
+        type: string;
+        text?: string;
+        uri?: string;
+        mimeType?: string;
+    }>;
+}
+export declare class SharePointErrorHandler {
+    /**
+     * Handle SharePoint API errors and return appropriate MCP responses
+     * @param error - The error from axios/API call
+     * @param logger - Logger instance for error tracking
+     * @param toolName - Name of the tool for logging context
+     * @returns ToolResult for authentication errors, throws McpError for others
+     */
+    static handle(error: any, logger: ILogger, toolName: string): ToolResult | never;
+}
+export {};
+//# sourceMappingURL=SharePointErrorHandler.d.ts.map

package/dist/utils/SharePointErrorHandler.js

@@ -0,0 +1,47 @@
+/**
+ * SharePointErrorHandler
+ * Centralized error handling for SharePoint MCP tools
+ */
+import { McpError, McpErrorCode } from './McpErrorHandler.js';
+export class SharePointErrorHandler {
+    /**
+     * Handle SharePoint API errors and return appropriate MCP responses
+     * @param error - The error from axios/API call
+     * @param logger - Logger instance for error tracking
+     * @param toolName - Name of the tool for logging context
+     * @returns ToolResult for authentication errors, throws McpError for others
+     */
+    static handle(error, logger, toolName) {
+        logger.error(toolName, 'SharePoint operation failed', '', error);
+        const serverError = error?.response?.data;
+        // Handle SharePoint authentication required (OnBehalfOf flow)
+        if (error?.response?.status === 401 && serverError?.error === 'SHAREPOINT_LOGIN_REQUIRED') {
+            const userMessage = serverError.message || 'To access SharePoint, please login then continue your conversation.';
+            const loginUrl = serverError.details?.loginUrl;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: userMessage
+                    },
+                    {
+                        type: 'resource',
+                        uri: loginUrl,
+                        mimeType: 'text/html'
+                    }
+                ]
+            };
+        }
+        // Handle not found errors
+        if (error?.response?.status === 404) {
+            throw new McpError(McpErrorCode.InvalidParams, 'SharePoint resource not found');
+        }
+        // Handle authorization errors (403 or other 401s)
+        if (error?.response?.status === 401 || error?.response?.status === 403) {
+            throw new McpError(McpErrorCode.InvalidParams, 'Not authorized to access this SharePoint resource');
+        }
+        // Handle all other errors
+        throw new McpError(McpErrorCode.InternalError, `SharePoint operation failed: ${error?.message || 'Unknown error'}`, { originalError: error?.message });
+    }
+}
+//# sourceMappingURL=SharePointErrorHandler.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@utaba/ucm-mcp-server",
-  "version": "4.2.2",
+  "version": "4.3.0",
   "description": "Universal Context Manager MCP Server - AI-native artifact management",
   "main": "dist/index.js",
   "type": "module",

package/package.json.backup

@@ -1,6 +1,6 @@
 {
   "name": "ucm-mcp-server",
-  "version": "4.2.2",
+  "version": "4.3.0",
   "description": "Universal Context Manager MCP Server - AI-native artifact management",
   "main": "dist/index.js",
   "type": "module",