Content
<div align="center">
<br />
<h1 align="center">Tup DB Client</h1>
<p align="center">
A modern, cross-platform desktop database client for MySQL and SQLite
<br />
with built-in MCP server support for AI integration
</p>
<p align="center">
<a href="#features"><strong>Features</strong></a> ·
<a href="#quick-start"><strong>Quick Start</strong></a> ·
<a href="#mcp-server"><strong>MCP Server</strong></a> ·
<a href="#architecture"><strong>Architecture</strong></a> ·
<a href="./CONTRIBUTING.md"><strong>Contributing →</strong></a>
</p>
<p align="center">
<img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT" />
<img src="https://img.shields.io/badge/electron-41.x-9b59b6.svg" alt="Electron 41.x" />
<img src="https://img.shields.io/badge/vue-3.x-4fc08d.svg" alt="Vue 3.x" />
<img src="https://img.shields.io/badge/typescript-6.x-3178c6.svg" alt="TypeScript 6.x" />
</p>
</div>
---
## Overview
Tup DB Client is a **cross-platform desktop database client** built with Electron, Vue 3, and TypeScript. It provides a modern, intuitive interface for managing MySQL and SQLite databases, with a unique built-in **Model Context Protocol (MCP) server** that exposes your database as a programmable API — perfect for AI integration and automation.
### Why Tup DB Client?
- **Built for AI workflows** — The integrated MCP server lets AI agents connect and explore your databases programmatically
- **Cross-platform** — Works on Windows, macOS, and Linux
- **Secure** — Passwords encrypted using Electron's safeStorage API
- **Fast** — MySQL connection pooling and efficient local SQLite handling
- **Developer-friendly** — Full TypeScript support, Vue 3 Composition API, and Pinia state management
---
## Features
| Capability | Description |
|---|---|
| **Multi-Database Support** | Connect to MySQL with connection pooling or work with SQLite locally |
| **Secure Connections** | SSL/TLS support for MySQL; passwords encrypted with Electron safeStorage |
| **Connection Profiles** | Save and manage multiple database connections |
| **Query Editor** | Write and execute SQL queries with syntax-friendly editing |
| **Results Viewer** | View query results in a sortable, filterable table |
| **Query History** | Automatic history with one-click recall and export to CSV/JSON |
| **Table Management** | Browse tables, view structure, pin favorites, edit records |
| **MCP Server** | Built-in Model Context Protocol server for AI integration |
| **Dark Theme UI** | Modern, responsive desktop interface |
| **Persistent Storage** | Local SQLite database stores connections and history |
---
## Quick Start
### Prerequisites
- [Node.js](https://nodejs.org/) 18+
- npm
### 1. Clone and install
```bash
git clone https://github.com/teamuplk/tup-db-client.git
cd tup-db-client
npm install
```
### 2. Run in development mode
```bash
npm run dev
```
### 3. Build and package
```bash
# Build for production
npm run build
# Package as desktop app
npm run package
```
---
## MCP Server
The **Model Context Protocol (MCP)** server is built into Tup DB Client and allows programmatic database access via JSON-RPC. This is ideal for AI agents, automation scripts, or custom integrations.
### Starting the MCP Server
1. Open Tup DB Client
2. Connect to a database
3. Click **"MCP"** in the sidebar
4. The server starts on `localhost:3456` by default
### Available Tools
| Tool | Description | Parameters |
|---|---|---|
| `list_connections` | List all saved connections | — |
| `list_databases` | List databases in a connection | `connectionId` |
| `list_tables` | List tables in a database | `connectionId`, `database` |
| `describe_table` | Get table structure (columns, types) | `connectionId`, `database`, `table` |
| `execute_query` | Run arbitrary SQL queries | `connectionId`, `database`, `sql` |
### Example API Calls
#### List connections
```bash
curl -X POST http://localhost:3456/mcp \\
-H "Content-Type: application/json" \\
-H "Authorization: Bearer <your-auth-token>" \\
-d '{"jsonrpc":"2.0","method":"list_connections"}'
```
#### Execute a query
```bash
curl -X POST http://localhost:3456/mcp \\
-H "Content-Type: application/json" \\
-H "Authorization: Bearer <your-auth-token>" \\
-d '{
"jsonrpc":"2.0",
"method":"execute_query",
"params":{
"connectionId":"abc123",
"database":"myapp",
"sql":"SELECT * FROM users LIMIT 10"
}
}'
```
#### Using MCP with AI agents
The MCP server follows the [Model Context Protocol](https://modelcontextprotocol.io) specification. AI agents can discover and call tools dynamically:
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "list_tables",
"arguments": {
"connectionId": "abc123",
"database": "myapp"
}
}
}
```
---
## Architecture
### Project Structure
```text
tup-db-client/
├── src/
│ ├── main/ # Electron main process
│ │ ├── index.ts # App entry point, IPC handlers
│ │ ├── connection-manager.ts # Database connections & pooling
│ │ └── mcp-server.ts # MCP JSON-RPC server
│ ├── preload/ # Preload scripts (context bridge)
│ │ └── index.ts # Exposed API to renderer
│ └── renderer/ # Vue.js frontend
│ └── src/
│ ├── App.vue # Root component
│ ├── main.ts # Vue app entry
│ ├── components/ # UI components
│ ├── stores/ # Pinia state stores
│ └── views/ # Page views
├── resources/ # App resources (icons, etc.)
├── electron.vite.config.ts # Electron + Vite configuration
├── vitest.config.ts # Test configuration
└── tsconfig.json # TypeScript configuration
```
### Technology Stack
| Layer | Technology | Purpose |
|---|---|---|
| **Desktop Framework** | Electron 41.x | Cross-platform desktop app |
| **UI Framework** | Vue 3 + TypeScript | Reactive frontend |
| **State Management** | Pinia | Application state |
| **Build Tool** | Electron-Vite + Vite 7.x | Development & production builds |
| **MySQL Driver** | mysql2 | MySQL connection pooling |
| **SQLite Driver** | sql.js (WASM) | In-browser SQLite |
| **Testing** | Vitest + Vue Test Utils | Unit testing |
| **Security** | Electron safeStorage | Password encryption |
### Data Flow
```
┌─────────────────────────────────────────────────────────────┐
│ Renderer Process │
│ ┌─────────────┐ ┌─────────────┐ ┌──────────────────┐ │
│ │ Vue App │ │ Pinia │ │ Query Editor │ │
│ │ │ │ Stores │ │ Results Table │ │
│ └──────┬──────┘ └──────┬──────┘ └────────┬─────────┘ │
│ │ │ │ │
│ └────────────────┼──────────────────┘ │
│ │ │
│ Preload API │
│ (contextBridge) │
└──────────────────────────┼─────────────────────────────────┘
│ IPC
┌──────────────────────────┼─────────────────────────────────┐
│ Main Process │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ IPC Handlers (connection:, mysql:, mcp:, etc.) │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌──────────────┐ │
│ │ Connection │ │ MySQL │ │ MCP Server │ │
│ │ Manager │ │ Pool │ │ (HTTP/JSON) │ │
│ └─────────────┘ └─────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Connection Manager
The `ConnectionManager` class handles:
- **MySQL connections** with connection pooling (5 connections per pool)
- **SQLite databases** via sql.js (WASM)
- **Secure password storage** using Electron's safeStorage API
- **Query history** persisted in local SQLite database
- **Connection profiles** saved to `connections.db` in user data directory
### MCP Server
The `McpServer` class implements a JSON-RPC server that:
- Runs on `localhost:3456` (configurable)
- Requires authentication via `Authorization: Bearer <token>`
- Exposes database operations as MCP tools
- Follows the [Model Context Protocol](https://modelcontextprotocol.io) specification
---
## Commands
| Command | Description |
|---|---|
| `npm run dev` | Start development server with hot reload |
| `npm run build` | Build for production |
| `npm run preview` | Preview production build |
| `npm run package` | Package as desktop app (build + electron-builder) |
| `npm run test` | Run tests in watch mode |
| `npm run test:run` | Run tests once |
---
## Development Setup
### 1. Clone and install
```bash
git clone https://github.com/teamuplk/tup-db-client.git
cd tup-db-client
npm install
```
### 2. Run development server
```bash
npm run dev
```
This starts Electron with hot reload for both main and renderer processes.
### 3. Run tests
```bash
npm run test:run
```
### 4. Build for production
```bash
npm run build
```
Output is generated in `out/` directory.
### 5. Package as desktop app
```bash
npm run package
```
This builds the app and packages it using electron-builder. Output is generated in `dist/` directory.
---
## Security
### Password Encryption
Tup DB Client uses Electron's `safeStorage` API to encrypt database passwords before storing them in the local SQLite database:
- Passwords are encrypted using the OS's secure credential storage
- Encrypted passwords are stored as `enc:v1:<base64-encoded>`
- Passwords are automatically migrated from plaintext on first run
### MCP Server Authentication
The MCP server requires authentication via:
- `Authorization: Bearer <token>` header, or
- `X-MCP-Token` header
The auth token is randomly generated when the server starts and is valid until the server stops.
---
## License
This project is licensed under the MIT License — see the [LICENSE](./LICENSE) file for details.
---
<div align="center">
<p>
Built with <a href="https://www.electronjs.org/">Electron</a> · <a href="https://vuejs.org/">Vue 3</a> · <a href="https://www.typescriptlang.org/">TypeScript</a>
</p>
<p>
<a href="https://github.com/teamuplk/tup-db-client">GitHub</a>
</p>
</div>
