Between Us

A relationship card game for two kinds of heart.

Between Us is a small MCP App for people who want to play relationship cards with the AI companion already present in their current chat.

It does not ship a separate chatbot. The app provides the cards, state, UI, and interaction flow; the connected chat model answers using the conversation it already has.

What it includes

• Near · 靠近 — daily conversation, memories, small habits, and gentle questions.

• Closer · 心跳 — attachment, dependence, intimacy, and relationship-focused prompts.

• After Dark · 越界 — 18+ preference, fantasy, and boundary cards. Explicit adult confirmation is required before this deck can be drawn.

• 20 cards per deck.

• Card flipping, reshuffling, history count, and a built-in favorites library.

• “Let them answer” flow that sends the current card back into the active chat.

• Responsive desktop/mobile UI.

• Local preview mode for UI work without connecting a live MCP host.

• OpenAI Secure MCP Tunnel helper scripts for local development.

Related MCP server: mcp-server-anki

How the interaction works

1. Open Between Us from the current chat.

2. Choose a deck.

3. Draw and flip a card.

4. Either answer it yourself, or press 让 TA 回答 / Let them answer.

5. The card is passed back to the current conversation so the AI companion can answer in context.

The app intentionally avoids creating a second chat or separate character system.

Tech stack

• TypeScript

• Node.js

• Model Context Protocol (MCP)

• @modelcontextprotocol/ext-apps

• @modelcontextprotocol/sdk

• Vite

• JSON card data

Project structure

between-us-mcp-app/
├─ data/
│  └─ cards.json
├─ src/
│  ├─ mcp-app.css
│  └─ mcp-app.ts
├─ scripts/
├─ standalone/
├─ server.ts
├─ main.ts
├─ mcp-app.html
├─ preview.html
├─ package.json
├─ TUNNEL_SETUP.md
└─ README.md

Quick start

Requirements:

• Node.js

• npm

Install dependencies:

npm install

Build:

npm run build

Start the MCP server:

npm run serve

Local endpoints used by the current development setup:

Health: http://127.0.0.1:8798/health
MCP:    http://127.0.0.1:8798/mcp

For UI development:

npm run dev

Then open the Vite preview page shown in the terminal. The project supports a local preview mode via ?preview=1.

Connecting to ChatGPT

For local development, expose the MCP endpoint through a supported secure tunnel or another HTTPS endpoint.

This repository includes helper scripts for OpenAI Secure MCP Tunnel. See:

TUNNEL_SETUP.md

Important:

• Create your own Tunnel ID and Runtime API key.

• Never commit Runtime API keys, .env files, or .tunnel/.

• The included .gitignore excludes local tunnel state, dependencies, build output, and environment files.

• After changing MCP App UI resources, rebuild/restart the server and reload/reconnect the tool in ChatGPT so the host refreshes the template.

Card data

Cards live in:

data/cards.json

Current deck sizes:

Current limitations

• Session state is currently kept in memory and resets when the server restarts.

• Favorites are session-scoped on the MCP server.

• The project is optimized for ChatGPT MCP App hosting; other MCP hosts may render UI resources differently.

• After Dark requires explicit adult confirmation.

Development notes

Older visual and fix notes are useful during development but are not required for runtime. Keeping them under docs/dev-notes/ is recommended so the repository root stays readable.

Security

Do not commit:

.tunnel/
.env
.env.*
node_modules/
dist/

Before publishing changes, a simple local scan can help:

git grep -n -I -E "sk-|API_KEY|apiKey|CONTROL_PLANE_API_KEY|Bearer|runtime.*key"

Variable names and setup instructions are expected; actual secret values are not.

License

Between Us is source-available, not OSI open source.

Current releases are licensed under the PolyForm Noncommercial License 1.0.0.

In practical terms:

• Personal/noncommercial use is allowed.

• Personal/noncommercial modification is allowed.

• Noncommercial redistribution of modified versions is allowed only if the original attribution notice is preserved.

• Commercial use is not allowed without separate written permission from IlyraVale.

Required attribution:

Required Notice: Between Us © 2026 IlyraVale. Original project by IlyraVale.

See LICENSE for the authoritative license terms and NOTICE for the project attribution notice.

Previous versions that were already distributed under the MIT License remain subject to the license terms under which those copies were released. Starting with v1.2.10, current and future releases use PolyForm Noncommercial 1.0.0 unless explicitly stated otherwise.

Status

v1.2.10 — noncommercial licensing release

Core draw / flip / answer flow works on desktop and mobile ChatGPT. Drawing a card is intentionally neutral; the AI answers only when the user asks or uses the app's “Let them answer” action.