# 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.

## 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

```text
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:

```bash
npm install
```

Build:

```bash
npm run build
```

Start the MCP server:

```bash
npm run serve
```

Local endpoints used by the current development setup:

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

For UI development:

```bash
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:

```text
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:

```text
data/cards.json
```

Current deck sizes:

| Deck | Purpose | Cards |
| --- | --- | ---: |
| Near · 靠近 | daily / memory / deep talk | 20 |
| Closer · 心跳 | relationship / attachment / intimacy | 20 |
| After Dark · 越界 | 18+ preference / fantasy / boundaries | 20 |

## 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:

```text
.tunnel/
.env
.env.*
node_modules/
dist/
```

Before publishing changes, a simple local scan can help:

```bash
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:

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

See [LICENSE](LICENSE) for the authoritative license terms and [NOTICE](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.