Hiworks Mail MCP

Instructions

Implementation Reference

• src/index.ts:155-239 (handler)

  Full handler implementation for the 'search_email' tool. Connects to POP3 server, fetches headers of the most recent emails (ignores query, uses limit), parses with mailparser, formats dates to KST, sorts by date, returns JSON response.

  server.tool(
    'search_email',
    '하이웍스 이메일을 검색합니다.',
    searchEmailSchema,
    async ({ username, password, query, limit = 100 }) => {
      try {
        const client = await connectPOP3(username, password);
        
        // STAT으로 메일박스 상태 확인
        const stat = await client.STAT();
        
        // LIST로 각 메일의 크기 확인 (메시지 번호는 1부터 시작)
        const messageList = await client.LIST();
        const totalMessages = messageList.length;  // LIST 결과로 전체 메시지 수 계산
  
        // UIDL로 메일의 고유 ID 확인
        const uidList = await client.UIDL();
  
        const emails = [];
        const messagesToFetch = [];
  
        // 최신 메일 선택 (가장 높은 번호부터)
        const startIndex = Math.min(totalMessages, messageList[messageList.length - 1][0]);
        for (let i = startIndex; i > Math.max(1, startIndex - limit); i--) {
          if (messageList.some(([num]) => Number(num) === i)) {
            messagesToFetch.push(i);
          }
        }
  
        // 선택된 메일들의 정보 가져오기
        for (const msgNum of messagesToFetch) {
          try {
            // 먼저 TOP으로 헤더만 가져오기
            const messageTop = await client.TOP(msgNum, 0);
            const parsed = await simpleParser(messageTop);
            
            // KST로 변환된 날짜 사용
            const date = parsed.date ? formatDate(parsed.date) : formatDate(new Date());
            
            emails.push({
              id: parsed.messageId || String(msgNum),
              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
            });
          } catch (err) {
            if (process.env.NODE_ENV === 'development') {
              log(`Error processing message ${msgNum}:`, err);
            }
          }
        }
  
        // KST 기준으로 정렬
        emails.sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime());
  
        await client.QUIT();
  
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify({
                success: true,
                emails
              } as SearchEmailResponse)
            }
          ]
        };
      } catch (error: any) {
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify({
                success: false,
                emails: [],
                error: error.message
              } as SearchEmailResponse)
            }
          ]
        };
      }
    }
  );

• src/index.ts:89-101 (registration)

  Registration of 'search_email' tool in the MCP server's capabilities section for tool discovery by clients.

  search_email: {
    description: '하이웍스 이메일을 검색합니다.',
    parameters: {
      type: 'object',
      properties: {
        username: { type: 'string' },
        password: { type: 'string' },
        query: { type: 'string' },
        limit: { type: 'number' }
      },
      required: ['username', 'password']
    }
  },

• src/index.ts:124-128 (schema)

  Zod schema used for input validation in the search_email tool handler.

  const searchEmailSchema = {
    ...emailSchema,
    query: z.string().optional(),
    limit: z.number().optional()
  };

• src/types/mail.ts:7-12 (schema)

  TypeScript interface defining the input parameters for search_email.

  export interface SearchEmailParams {
    username?: string;
    password?: string;
    query?: string;
    limit?: number;
  }

• src/types/mail.ts:27-31 (schema)

  TypeScript interface defining the output response for search_email.

  export interface SearchEmailResponse {
    success: boolean;
    emails: Email[];
    error?: string;
  }

• src/index.ts:44-56 (helper)

  Helper function to establish POP3 connection, used by search_email handler.

  async function connectPOP3(username: string, password: string): Promise<Pop3Command> {
    const pop3Config = {
      user: username,
      password: password,
      host: config.pop3.host,
      port: config.pop3.port,
      tls: config.pop3.ssl,
      timeout: 60000
    };
    
    const client = new Pop3Command(pop3Config);
    return client;
  }