Mailplug Jandi

Mailplug 메일 워크플로우와 JANDI 알림을 연결하기 위한 TypeScript MCP scaffold입니다. 현재 구현은 stdio MCP server와 Streamable HTTP backend를 함께 제공합니다. 실제 Mailplug POP3/SMTP 연동과 JANDI 인증 정보는 나중에 로컬 또는 서버 .env에서 설정하도록 의도적으로 비워 두었습니다.

현재 범위

• @modelcontextprotocol/[email protected] 기반 MCP stdio server.
• Apache reverse proxy 뒤에서 사용할 Streamable HTTP backend (/mcp, /health).
• MVP에서 사용할 tool 이름:
  • mailplug_list_recent
  • jandi_build_message
  • jandi_send_message
• JANDI Incoming Webhook payload builder와 sender.
• Mailplug 인증 정보와 POP3 동작 방식이 확정되기 전까지 빈 목록을 반환하는 placeholder recent-message tool.
• mcp.nimbustech.co.kr용 Apache vhost 예시. 원격 적용은 별도 승인 후 진행합니다.

설정

npm install
cp .env.example .env
npm run check
npm run build

.env, 실제 webhook URL, Mailplug app password, token, certificate path, secret은 commit하지 마세요.

환경 변수

Variable	Purpose
MAILPLUG_EMAIL	향후 POP3/SMTP 연동에 사용할 Mailplug mailbox address.
MAILPLUG_APP_PASSWORD	향후 POP3/SMTP 연동에 사용할 Mailplug app password.
MAILPLUG_POP3_HOST	기본값은 pop3.mailplug.co.kr.
MAILPLUG_POP3_PORT	기본값은 995.
MAILPLUG_SMTP_HOST	기본값은 smtp.mailplug.co.kr.
MAILPLUG_SMTP_PORT	기본값은 465.
JANDI_WEBHOOK_URL	JANDI Incoming Webhook URL. 로컬 .env에만 입력합니다.
MCP_PUBLIC_URL	Public URL, https://mcp.nimbustech.co.kr/mcp.
MCP_HTTP_PORT	Streamable HTTP backend port, 현재 8710.

개발 명령어

npm run dev       # 로컬 stdio MCP server 실행
npm run dev:http  # 로컬 Streamable HTTP backend 실행
npm test          # unit test 실행
npm run typecheck # TypeScript 검사만 실행
npm run build     # dist/ 출력
npm run check     # typecheck + tests

배포 문서

이 repo가 재현 가능한 배포 절차와 운영 문서의 source of truth입니다. 서버에는 live runtime file, secret, 그리고 배포 commit, enabled service, certificate 상태, 승인된 host-specific deviation 같은 non-secret live-state note만 둡니다.

• docs/deployment.md는 target server shape, 필요한 operator input, preflight check, HTTP/vhost 절차를 문서화합니다.
• docs/runbook.md는 운영 점검, troubleshooting command, DNS check, secret handling, rollback을 문서화합니다.
• docs/auth-credential-plan.md는 public /mcp HTTPS 노출 전 필요한 multi-user auth, per-user credential routing, secret storage 요구사항을 문서화합니다.
• docs/mcp-tooling-notes.md는 MCP SDK, registerTool, Zod schema, agent-facing tool metadata 작성 원칙을 문서화합니다.
• deploy/apache/에는 Apache 예시가 있습니다.
• deploy/systemd/에는 systemd 예시가 있습니다.

mcp.nimbustech.co.kr의 DNS target은 49.247.207.165입니다. 변경 직후 resolver별 propagation/cache 지연이 있을 수 있습니다. DNS, certificate 발급, systemd 설치, Apache reload, 배포 타이밍이 명시적으로 승인되기 전까지 live server config를 적용하지 마세요. Public /mcp HTTPS 노출은 docs/auth-credential-plan.md의 auth와 per-user credential routing 요구사항이 구현될 때까지 차단합니다. nimbus에 live-state note가 필요하면 /opt/mailplug-jandi-mcp/DEPLOYMENT_STATE.md에 server-local로 두고 모든 secret은 제외합니다.