outlook-bridge

Claude가 Outlook 클래식(Windows, COM 경유)에서 메일을 검색하고 읽을 수 있게 해주는 MCP 서버 — list_folders, search_mail, read_mail, get_thread, read_attachment. 전체 설계는 docs/superpowers/specs/2026-08-24-outlook-bridge-design.md에서, 구현 계획은 docs/superpowers/plans/2026-08-24-outlook-bridge-a.md에서 확인할 수 있습니다.

읽기 전용 — 쓰기 도구 없음

이 서버에는 send_mail, delete_mail, move_mail, mark_as_read 또는 메일을 수정/삭제/전송하는 어떤 도구도 없습니다. Win32MailStore의 어떤 메서드도 .Send(), .Save(), .Delete(), .Move(), .MarkAsRead()를 호출하거나 Outlook 속성에 값을 할당하지 않습니다. 유일한 예외: read_attachment는 텍스트를 추출하기 위해 서버가 직접 생성한 임시 디렉터리(tempfile.TemporaryDirectory)에 첨부 파일을 기록한 후, 해당 디렉터리를 즉시 삭제합니다 — SaveAsFile은 읽기 API이며 Outlook 내부의 어떤 것도 수정하지 않습니다.

Related MCP server: outlook-mcp

Linux(개발 머신)에서 실행 — FakeMailStore

Outlook도 Windows도 필요 없습니다. FakeMailStore는 YAML 픽스처(합성 메일 약 50통: 여러 폴더, 여러 스토어, 대화 스레드, 다양한 유형의 첨부 파일, 베트남어 메일, 긴 본문 메일, 빈 메일, 메일이 아닌 항목)를 로드하고 Win32MailStore가 구현하는 것과 동일한 MailStore 인터페이스를 구현합니다.

python -m venv .venv
.venv/bin/pip install -e ".[dev]"

# Chạy server với store giả (không cần Outlook)
OUTLOOK_BRIDGE_FAKE=1 OUTLOOK_BRIDGE_FIXTURE=tests/fixtures/mailbox.yaml \
  .venv/bin/python server.py

테스트 실행

Linux(대부분의 로직 — 순수 Python + FakeMailStore):

.venv/bin/pytest

Windows(두 스토어에 공통으로 사용되는 계약 테스트 세트 — 이것이 Win32MailStore가 실제로 FakeMailStore와 동작이 일치함을 증명하는 유일한 방법이며, 단지 "실행된다"는 것만 증명하는 것이 아닙니다):

set OUTLOOK_BRIDGE_CONTRACT_WIN32=1
.venv\Scripts\pytest tests/contract -v

이 세트의 일부 케이스는 실제 사서함에서 의도적으로 SKIP됩니다(데이터가 FakeMailStore의 픽스처에만 존재함) — SKIP을 문제의 신호로 간주하기 전에 docs/WINDOWS-RUNBOOK.md의 "의도적 SKIP 테스트" 섹션을 참조하세요.

Windows에서 MCP 서버를 설치하고 등록하려면 docs/INSTALL-windows.md를, 실제 Windows 머신 앞에 처음 앉았을 때 수행할 작업 순서는 docs/WINDOWS-RUNBOOK.md를 참조하세요.

환경 진단 — doctor.py

python doctor.py            # trên Linux: báo "không phải Windows", degrade an toàn
python doctor.py --verbose  # trên Windows: thêm chi tiết root.Name, cây folder, giá trị raw

아직 아무도 해결하지 못한 두 가지 위험(spec §13)

R2 — New Outlook이 점차 Outlook 클래식을 대체하고 COM도 함께 사라집니다. Microsoft는 사용자를 COM 서버를 등록하지 않는 New Outlook으로 강제 마이그레이션하고 있습니다(doctor.py가 이 경우 com_ok: False를 보고합니다). 이것은 수명이 제한된 것이지, 패치할 수 있는 버그가 아닙니다. 발생 시 유일한 탈출구는 Microsoft Graph API 기반으로 Win32MailStore를 다시 작성하는 것입니다 — 프로젝트의 아키텍처(모든 COM 세부 사항이 정확히 두 파일, win32_store.py와 doctor.py에만 있음)는 피해를 정확히 그 두 파일의 재작성으로 제한하며, 전체 시스템을 다시 작성할 필요는 없습니다.

R3 — 회사 내부 메일 내용이 Anthropic의 API를 통과합니다. COM은 완전히 로컬에서 실행되지만(메일을 읽기 위해 어떤 것도 머신을 떠나지 않음), Claude가 메일 내용을 기반으로 답변하려면 해당 내용을 API로 보내야 합니다. 이것은 AI 어시스턴트를 사용하여 메일을 읽는 것의 본질적인 트레이드오프입니다 — 어떤 서버도 이를 대신 해결해 주지 않습니다.

유일한 통제 수단: config.toml의 folder_allowlist. 이를 특정 폴더 목록(store-qualified, 예: "Mailbox - Nguyen Van A/Inbox")으로 설정하면 이 서버가 볼 수 있는 메일 범위가 제한됩니다 — allowlist 밖의 메일은 어떤 도구로도, 어떤 호출 경로로도(검색, ID로 읽기, 스레드 읽기, 첨부 파일 다운로드) 읽을 수 없으며, 대화 스레드가 allowlist 경계를 넘는 경우에도 마찬가지입니다.

일치는 정확히 일치(PREFIX 아님)입니다. "Inbox"를 허용해도 "Inbox/Bao cao"는 허용되지 않습니다 — 허용하려는 각 폴더는 개별적으로 나열해야 합니다. 이것은 제한이 아니라 의도적인 설계 선택입니다: 접두사 기반 allowlist는 구성자가 생각하지 못한 민감한 하위 폴더를 실수로 통과시키기 쉽습니다. folder_allowlist를 구성하지 않으면(기본값, 빈 목록) 사서함의 모든 폴더를 읽을 수 있습니다 — 이 서버를 실제 회사 사서함에 연결하기 전에 구성하세요. list_folders에서 정확한 store-qualified 폴더 이름을 얻는 방법은 docs/WINDOWS-RUNBOOK.md 2단계를 참조하세요.

더 강하게 제한해야 한다면: folder_allowlist를 몇 개의 특정 폴더로 좁히거나, 그래도 부족하다면 전체 메일 내용 대신 메타데이터 + 스니펫만 반환하는 방안을 고려하세요(현재 이 작업을 수행하는 도구는 없으며, 새 도구가 필요합니다).