Hiworks Mail MCP

Instructions

Implementation Reference

• src/index.ts:245-304 (handler)

  The handler function for the 'read_email' tool. It connects to the POP3 server using the provided credentials, iterates through emails to find the one matching the messageId, parses the email content with mailparser, converts date to KST, and returns the structured email data or error.

  async ({ username, password, messageId }) => {
    try {
      const client = await connectPOP3(username, password);
      const stat = await client.STAT();
      const totalMessages = stat[0];
      let email: Email | undefined;
  
      for (let i = totalMessages; i >= 1; i--) {
        try {
          const rawEmail = await client.RETR(i);
          const parsed = await simpleParser(rawEmail);
          
          if (parsed.messageId === messageId || String(i) === messageId) {
            // KST로 변환된 날짜 사용
            const date = parsed.date ? formatDate(parsed.date) : formatDate(new Date());
            
            email = {
              id: parsed.messageId || String(i),
              subject: parsed.subject || '(제목 없음)',
              from: Array.isArray(parsed.from) ? parsed.from[0]?.text || '' : parsed.from?.text || '',
              to: Array.isArray(parsed.to) ? parsed.to[0]?.text || '' : parsed.to?.text || '',
              date,
              content: parsed.text || '',
              html: parsed.html || undefined
            };
            break;
          }
        } catch (err) {
          log(`Error processing email ${i}:`, err);
          continue;
        }
      }
  
      await client.QUIT();
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              success: true,
              email
            } as ReadEmailResponse)
          }
        ]
      };
    } catch (error: any) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              success: false,
              error: error.message
            } as ReadEmailResponse)
          }
        ]
      };
    }
  }

• src/index.ts:241-305 (registration)

  The server.tool call that registers the 'read_email' tool with its description, input schema (readEmailSchema), and handler function.

  server.tool(
    'read_email',
    '하이웍스 이메일을 읽어옵니다.',
    readEmailSchema,
    async ({ username, password, messageId }) => {
      try {
        const client = await connectPOP3(username, password);
        const stat = await client.STAT();
        const totalMessages = stat[0];
        let email: Email | undefined;
  
        for (let i = totalMessages; i >= 1; i--) {
          try {
            const rawEmail = await client.RETR(i);
            const parsed = await simpleParser(rawEmail);
            
            if (parsed.messageId === messageId || String(i) === messageId) {
              // KST로 변환된 날짜 사용
              const date = parsed.date ? formatDate(parsed.date) : formatDate(new Date());
              
              email = {
                id: parsed.messageId || String(i),
                subject: parsed.subject || '(제목 없음)',
                from: Array.isArray(parsed.from) ? parsed.from[0]?.text || '' : parsed.from?.text || '',
                to: Array.isArray(parsed.to) ? parsed.to[0]?.text || '' : parsed.to?.text || '',
                date,
                content: parsed.text || '',
                html: parsed.html || undefined
              };
              break;
            }
          } catch (err) {
            log(`Error processing email ${i}:`, err);
            continue;
          }
        }
  
        await client.QUIT();
  
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify({
                success: true,
                email
              } as ReadEmailResponse)
            }
          ]
        };
      } catch (error: any) {
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify({
                success: false,
                error: error.message
              } as ReadEmailResponse)
            }
          ]
        };
      }
    }
  );

• src/index.ts:130-133 (schema)

  Zod validation schema for read_email input parameters, extending emailSchema (username, password) with required messageId.

  const readEmailSchema = {
    ...emailSchema,
    messageId: z.string()
  };

• src/types/mail.ts:1-5 (schema)

  TypeScript interface defining the input parameters for the read_email tool.

  export interface ReadEmailParams {
    username?: string;
    password?: string;
    messageId: string;
  }

• src/types/mail.ts:33-37 (schema)

  TypeScript interface defining the output response structure for the read_email tool.

  export interface ReadEmailResponse {
    success: boolean;
    email?: Email;
    error?: string;
  }