MCP 服务器

MailBridge MCP

Enables MCP-compatible AI assistants to securely search multiple mailboxes, reconstruct email threads, and inspect attachments through read-only tools without altering mailbox state.

README

MailBridge MCP

Security-first, read-only email intelligence for MCP-compatible AI assistants.

MailBridge demonstrates how an AI assistant can search multiple mailboxes, reconstruct threads, inspect attachments, and preserve mailbox state. The public distribution runs entirely on synthetic data, so it is safe to explore without credentials or access to a real inbox.

This repository is a controlled public reference distribution by Gexiro Global Enterprises Ltd. It is not a mirror of any private deployment and contains no production configuration, infrastructure, mailbox data, or credentials.

Why MailBridge

Eleven deliberately read-only MCP tools.
Standard search and fetch contracts for knowledge-source compatibility.
Explicit output schemas for every structured tool result.
MCP Apps widget with a versioned ui:// resource.
Standards-first ui/initialize and ui/notifications/initialized handshake.
Multi-mailbox and all-folder search behavior.
Thread reconstruction using Message-ID, In-Reply-To, and References.
Bounded attachment retrieval with SHA-256 checksums.
Explicit warning that email and attachment content is untrusted.
Fail-closed public binding: loopback-only unless an operator explicitly opts in.
Zero SMTP, send, move, delete, flag, append, copy, or expunge operations.

Tool surface

Tool	Purpose
`list_mailboxes`	Discover synthetic mailboxes and safe metadata.
`mailbox_health`	Report redacted TLS/auth/folder/read-only health.
`list_folders`	Enumerate selectable folders and counters.
`list_recent_messages`	Return bounded recent message metadata.
`search_messages`	Structured multi-mailbox, all-folder search.
`fetch_message`	Fetch one bounded message without changing unread state.
`fetch_thread`	Reconstruct a thread from message identifiers.
`list_attachments`	Return attachment metadata only.
`fetch_attachment`	Return bounded synthetic bytes, base64, and SHA-256.
`search`	Standard read-only knowledge search.
`fetch`	Standard read-only knowledge document fetch.

Every descriptor sets readOnlyHint: true, destructiveHint: false, idempotentHint: true, and openWorldHint: false.

Quick start

Requirements: Node.js 24 or newer.

npm ci
npm run check
npm run dev

The server starts on loopback by default:

Health: http://127.0.0.1:3100/health
Widget: http://127.0.0.1:3100/widget
MCP:    http://127.0.0.1:3100/mcp

To connect from an MCP client, use the streamable HTTP endpoint /mcp. For ChatGPT developer testing, expose the loopback service through a reviewed HTTPS tunnel and refresh the app after tool or resource metadata changes.

Docker

The container remains synthetic-only and runs as the unprivileged node user.

docker build -t mailbridge-mcp .
docker run --rm -p 127.0.0.1:3100:3100 \
  -e MAILBRIDGE_HOST=0.0.0.0 \
  -e MAILBRIDGE_ALLOW_PUBLIC_DEMO=I_UNDERSTAND_SYNTHETIC_ONLY \
  mailbridge-mcp

Architecture

flowchart LR
    Host[ChatGPT or MCP host] -->|Streamable HTTP| MCP[MailBridge MCP server]
    MCP --> Tools[Read-only tool contracts]
    MCP --> Widget[MCP Apps dashboard]
    Tools --> Demo[Synthetic mailbox provider]
    Demo --> Guard[Untrusted-content and size guards]

The provider boundary is intentionally small. This public edition ships only the synthetic provider; production adapters, operator identities, credential storage, and deployment topology are outside this repository.

Security properties

No credential input exists in any MCP tool schema.
No real mailbox connection is implemented in this public distribution.
Message fetches do not mutate synthetic unread state.
Attachment bytes are bounded and labeled as untrusted.
The HTTP runtime refuses non-loopback binding unless the explicit synthetic demo acknowledgement is set.
CI runs compilation, tests, repository secret scanning, dependency audit, dependency review, CodeQL, a real container smoke test, and SBOM validation.
The container gate fails closed on detected High or Critical CVEs and strips package managers from the runtime image after dependency installation.
Tagged releases contain SHA-256 checksums, a CycloneDX SBOM, and GitHub artifact provenance attestations.

See SECURITY.md, THREAT_MODEL.md, PRIVACY.md, and ARCHITECTURE.md.

OpenAI Apps SDK alignment

The implementation follows the current MCP Apps-first guidance:

the UI resource uses text/html;profile=mcp-app;
tools remain useful without the widget;
list_mailboxes points to a versioned _meta.ui.resourceUri;
the widget consumes ui/notifications/tool-result and uses window.openai.toolOutput only as a compatibility path;
CSP metadata declares no external connect or resource domains.

Official references:

Release integrity

Each tagged release is built from locked dependencies in GitHub Actions. Verify the downloaded archive and SBOM with the included SHA256SUMS, then verify the GitHub artifact attestation against this repository before use.