outlook-mcp

Instructions

Implementation Reference

• advanced/index.js:48-191 (handler)

  Main handler function for the 'access-shared-mailbox' tool. Validates input, authenticates, calls Microsoft Graph API to fetch emails from a shared mailbox, and formats the response. Handles errors for authentication, access denied (403), and not found (404) scenarios.

  async function handleAccessSharedMailbox(args) {
    const { sharedMailbox, folder, count, outputVerbosity } = args;
  
    if (!sharedMailbox) {
      return {
        content: [
          {
            type: 'text',
            text: "Shared mailbox email address is required (e.g., 'shared@company.com').",
          },
        ],
      };
    }
  
    const mailFolder = folder || 'inbox';
    const pageSize = Math.min(count || 25, 50);
    const verbosity = outputVerbosity || 'standard';
  
    try {
      const accessToken = await ensureAuthenticated();
  
      // Build endpoint for shared mailbox
      const endpoint = `users/${sharedMailbox}/mailFolders/${mailFolder}/messages`;
      const fieldSet = verbosity === 'full' ? 'read' : 'list';
      const queryParams = {
        $top: pageSize.toString(),
        $orderby: 'receivedDateTime desc',
        $select: FIELD_PRESETS[fieldSet].join(','),
      };
  
      const response = await callGraphAPI(
        accessToken,
        'GET',
        endpoint,
        null,
        queryParams
      );
  
      const messages = response.value || [];
  
      if (messages.length === 0) {
        return {
          content: [
            {
              type: 'text',
              text: `No emails found in ${sharedMailbox}/${mailFolder}.\n\nNote: Make sure you have access to this shared mailbox and the Mail.Read.Shared permission is granted.`,
            },
          ],
        };
      }
  
      let output = [];
      output.push(`# Shared Mailbox: ${sharedMailbox}`);
      output.push(`**Folder**: ${mailFolder} | **Count**: ${messages.length}\n`);
  
      if (verbosity === 'minimal') {
        messages.forEach((msg, i) => {
          output.push(`${i + 1}. ${msg.subject}`);
          output.push(`   From: ${msg.from?.emailAddress?.address || 'Unknown'}`);
        });
      } else {
        output.push('| # | Subject | From | Date | Read |');
        output.push('|---|---------|------|------|------|');
        messages.forEach((msg, i) => {
          const date = new Date(msg.receivedDateTime).toLocaleDateString();
          const from =
            msg.from?.emailAddress?.name ||
            msg.from?.emailAddress?.address ||
            'Unknown';
          const read = msg.isRead ? 'Y' : 'N';
          output.push(
            `| ${i + 1} | ${msg.subject?.substring(0, 40)}${msg.subject?.length > 40 ? '...' : ''} | ${from.substring(0, 20)} | ${date} | ${read} |`
          );
        });
      }
  
      if (verbosity === 'full') {
        output.push('\n## Message IDs');
        messages.forEach((msg, i) => {
          output.push(`${i + 1}. \`${msg.id}\``);
        });
      }
  
      return {
        content: [
          {
            type: 'text',
            text: output.join('\n'),
          },
        ],
        _meta: {
          sharedMailbox,
          folder: mailFolder,
          count: messages.length,
          messages: messages.map((m) => formatEmail(m, verbosity)),
        },
      };
    } catch (error) {
      if (error.message === 'Authentication required') {
        return {
          content: [
            {
              type: 'text',
              text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
            },
          ],
        };
      }
  
      if (
        error.message.includes('Access is denied') ||
        error.message.includes('403')
      ) {
        return {
          content: [
            {
              type: 'text',
              text: `Access denied to shared mailbox "${sharedMailbox}".\n\n**Possible causes:**\n- You don't have access to this shared mailbox\n- The Mail.Read.Shared permission is not granted\n- The shared mailbox address is incorrect`,
            },
          ],
        };
      }
  
      if (error.message.includes('not found') || error.message.includes('404')) {
        return {
          content: [
            {
              type: 'text',
              text: `Shared mailbox "${sharedMailbox}" not found. Please verify the email address.`,
            },
          ],
        };
      }
  
      return {
        content: [
          {
            type: 'text',
            text: `Error accessing shared mailbox: ${error.message}`,
          },
        ],
      };
    }
  }

• advanced/index.js:590-623 (registration)

  Tool registration defining the 'access-shared-mailbox' tool with name, description, annotations (readOnlyHint, openWorldHint), inputSchema with parameters (sharedMailbox, folder, count, outputVerbosity), and handler reference.

  const advancedTools = [
    {
      name: 'access-shared-mailbox',
      description: 'Read emails from a shared mailbox you have access to',
      annotations: {
        title: 'Shared Mailbox',
        readOnlyHint: true,
        openWorldHint: false,
      },
      inputSchema: {
        type: 'object',
        properties: {
          sharedMailbox: {
            type: 'string',
            description: 'Email address of the shared mailbox (required)',
          },
          folder: {
            type: 'string',
            description: 'Folder to read from (default: inbox)',
          },
          count: {
            type: 'number',
            description: 'Number of emails to retrieve (default: 25, max: 50)',
          },
          outputVerbosity: {
            type: 'string',
            enum: ['minimal', 'standard', 'full'],
            description: 'Output detail level (default: standard)',
          },
        },
        required: ['sharedMailbox'],
      },
      handler: handleAccessSharedMailbox,
    },

• advanced/index.js:19-42 (helper)

  Helper function 'formatEmail' that formats email objects for output based on verbosity level (minimal or standard). Used within the handler to structure email data in the response.

  function formatEmail(email, verbosity = 'standard') {
    if (verbosity === 'minimal') {
      return {
        id: email.id,
        subject: email.subject,
        from: email.from?.emailAddress?.address,
      };
    }
  
    return {
      id: email.id,
      subject: email.subject,
      from: email.from?.emailAddress
        ? {
            name: email.from.emailAddress.name,
            address: email.from.emailAddress.address,
          }
        : null,
      receivedDateTime: email.receivedDateTime,
      isRead: email.isRead,
      hasAttachments: email.hasAttachments,
      flag: email.flag,
    };
  }