mcp-app-message-bridge

# MCP App Message Bridge A reference architecture for bridging external messages into an AI chat conversation through an MCP App UI. This repository is intentionally **not** a one-click deployment. It documents the small protocol core that is reusable across projects, then leaves memory, wake policy, scheduling, queues, prompts, notification channels, and product-specific behavior to the implementer. The intended workflow is: 1. A human decides what they want their AI to be able to receive or wake for. 2. Their AI/agent reads this repository. 3. The AI adapts the reference bridge to the owner's backend, MCP server, frontend/channel, and continuity system. ## Core idea ```text External channel (PWA / web / app / Telegram / Discord / ...) ↕ Gateway / adapter ↕ Your backend ↕ MCP server ↕ MCP App UI running inside the chat host ↕ Official conversation turn ``` The MCP App UI is the door between an external backend and the conversation. For an automatic event, the reference pattern is: ```text Backend event ↓ Listener App reserves one event ↓ ui/update-model-context (model-visible, chat-invisible context) ↓ ui/message (visible user-role message; starts the next turn) ↓ AI handles the turn using your MCP / continuity tools ↓ Optional outbound tool / backend route ↓ External channel ``` ## Start here If you are an AI implementing this repository for someone, read in this order: 1. [`AGENTS.md`](./AGENTS.md) 2. [`AI_IMPLEMENTATION_GUIDE.md`](./AI_IMPLEMENTATION_GUIDE.md) 3. [`ARCHITECTURE.md`](./ARCHITECTURE.md) 4. [`docs/context-channels.md`](./docs/context-channels.md) 5. [`docs/event-lifecycle.md`](./docs/event-lifecycle.md) 6. [`docs/pitfalls.md`](./docs/pitfalls.md) 7. [`docs/upstream.md`](./docs/upstream.md) 8. [`reference/`](./reference/) If you are a human, the only required concept is: **your external channel must be able to write events into a backend you control, and your MCP App UI must be able to read those events and send a message into the conversation.** ## What is reusable vs personal Reusable: - MCP App resource/tool wiring - `ui/update-model-context` → `ui/message` dispatch order - event identity and reserve/release lifecycle - single in-flight dispatch - explicit MCP/plugin routing hint in the visible trigger - stale/duplicate recovery patterns - separation of model context, UI-only metadata, and visible messages Personal/project-specific: - when the AI wakes - what a wake means - memory/state/continuity design - wake or care prompts - queue priorities - external frontend/channel - database and deployment platform - outbound notifications / Push - whether the AI must reply externally ## Standards-first The reference implementation prefers the open **MCP Apps** bridge (`ui/*`, `_meta.ui.resourceUri`) and treats ChatGPT-specific `window.openai` helpers as optional compatibility/extension surfaces. Current upstream references: - OpenAI Plugins UI guide: https://developers.openai.com/plugins/build/chatgpt-ui - OpenAI Plugins reference: https://developers.openai.com/plugins/reference - MCP Apps specification/API: https://apps.extensions.modelcontextprotocol.io/ ## Repository status Reference architecture distilled from a working production bridge. Private application logic, private prompts, personal memory data, deployment secrets, and product-specific state machines are deliberately excluded. ## License See [`LICENSE`](./LICENSE).