Content
# 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).
MCP Store