Microsoft 365 Core MCP Server

Instructions

Implementation Reference

• src/handlers.ts:84-135 (handler)

  The core handler function that implements the 'manage_offboarding' tool logic. It handles three actions: 'start' (disables account, revokes sessions, optional backup), 'check' (retrieves user status), and 'complete' (converts to shared mailbox or deletes user). Uses Microsoft Graph API calls.

  // Offboarding Handler
  export async function handleOffboarding(
    graphClient: Client,
    args: OffboardingArgs
  ): Promise<{ content: { type: string; text: string }[] }> {
    switch (args.action) {
      case 'start': {
        // Block sign-ins
        await graphClient
          .api(`/users/${args.userId}`)
          .patch({ accountEnabled: false });
  
        if (args.options?.revokeAccess) {
          // Revoke all refresh tokens
          await graphClient
            .api(`/users/${args.userId}/revokeSignInSessions`)
            .post({});
        }
  
        if (args.options?.backupData) {
          // Trigger backup
          await graphClient
            .api(`/users/${args.userId}/drive/content`)
            .get();
        }
  
        return { content: [{ type: 'text', text: 'Offboarding process started successfully' }] };
      }
      case 'check': {
        const status = await graphClient
          .api(`/users/${args.userId}`)
          .get();
        return { content: [{ type: 'text', text: JSON.stringify(status, null, 2) }] };
      }
      case 'complete': {
        if (args.options?.convertToShared) {
          // Convert to shared mailbox
          await graphClient
            .api(`/users/${args.userId}/mailbox/convert`)
            .post({});
        } else if (!args.options?.retainMailbox) {
          // Delete user if not retaining mailbox
          await graphClient
            .api(`/users/${args.userId}`)
            .delete();
        }
        return { content: [{ type: 'text', text: 'Offboarding process completed successfully' }] };
      }
      default:
        throw new McpError(ErrorCode.InvalidParams, `Invalid action: ${args.action}`);
    }
  }

• src/server.ts:457-477 (registration)

  Registers the 'manage_offboarding' tool with the MCP server, linking to the handleOffboarding handler, offboardingSchema for input validation, and metadata annotations.

  this.server.tool(
    "manage_offboarding",
    "Automate user offboarding processes including account disablement, license removal, data backup, and access revocation.",
    offboardingSchema.shape,
    {"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false},
    wrapToolHandler(async (args: OffboardingArgs) => {
      // Validate credentials only when tool is executed (lazy loading)
      this.validateCredentials();
      try {
        return await handleOffboarding(this.getGraphClient(), args);
      } catch (error) {
        if (error instanceof McpError) {
          throw error;
        }
        throw new McpError(
          ErrorCode.InternalError,
          `Error executing tool: ${error instanceof Error ? error.message : 'Unknown error'}`
        );
      }
    })
  );    // SharePoint Sites - Lazy loading enabled for tool discovery

• src/tool-definitions.ts:116-125 (schema)

  Zod schema defining the input parameters for the 'manage_offboarding' tool, including required action and userId, and optional offboarding options.

  export const offboardingSchema = z.object({
    action: z.enum(['start', 'check', 'complete']).describe('Offboarding process action'),
    userId: z.string().describe('User ID or UPN to offboard'),
    options: z.object({
      revokeAccess: z.boolean().optional().describe('Revoke all access immediately'),
      retainMailbox: z.boolean().optional().describe('Retain user mailbox'),
      convertToShared: z.boolean().optional().describe('Convert mailbox to shared'),
      backupData: z.boolean().optional().describe('Backup user data'),
    }).optional().describe('Offboarding options'),
  });

• src/tool-metadata.ts:55-58 (schema)

  Tool metadata providing description, title, and annotations (readOnlyHint, destructiveHint, etc.) for the 'manage_offboarding' tool used in MCP server capabilities and discovery.

  manage_offboarding: {
    description: "Automate user offboarding processes including account disablement, license removal, data backup, and access revocation.",
    title: "User Offboarding Manager",
    annotations: { title: "User Offboarding Manager", readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true }

• src/types.ts:11-20 (helper)

  TypeScript interface defining the OffboardingArgs type used by the handler and schema for type safety.

  export interface OffboardingArgs {
    action: 'start' | 'check' | 'complete';
    userId: string;
    options?: {
      revokeAccess?: boolean;
      retainMailbox?: boolean;
      convertToShared?: boolean;
      backupData?: boolean;
    };
  }