# MarkBox

[English](#english) · [中文](#中文)

本机笔记箱：用 **Tauri 2 + React + TypeScript + SQLite** 做的单机 macOS 学习项目，并支持 **stdio MCP**，让 AI 工具与 GUI 读写同一数据库。

> **定位**：教程 / 示例，不是生产级笔记套件（无同步、无端到端加密、默认未代码签名）。

---

## 中文

### 功能

- 笔记列表 / 编辑 / 设置（三页）
- SQLite 持久化（`~/Library/Application Support/com.markbox.notes/markbox.db`）
- 本机 MCP：`list_notes` / `get_note` / `create_note` / `update_note` / `delete_note`
- 双入口：默认 GUI；`--mcp` 走 MCP stdio

### 环境

- macOS（主目标）
- Node.js + npm
- Rust（rustup stable）
- Xcode Command Line Tools

### 快速开始

```bash
git clone <your-fork-or-url> markbox
cd markbox
npm install
source "$HOME/.cargo/env"   # 若 cargo 不在 PATH
npm run tauri dev
```

### 常用命令

| 命令 | 说明 |
|------|------|
| `npm run tauri dev` | 开发模式 |
| `npm test` | Rust 单测 + 前端小测 |
| `npm run tauri build` | 打出 `.app` / `.dmg` |
| `cargo run --manifest-path src-tauri/Cargo.toml -- --mcp` | 开发期 MCP |

### MCP 配置示例

开发（仓库根为 cwd 时可用相对路径）：

```json
{
  "mcpServers": {
    "markbox": {
      "command": "cargo",
      "args": [
        "run",
        "--manifest-path",
        "src-tauri/Cargo.toml",
        "--",
        "--mcp"
      ]
    }
  }
}
```

打包安装到 Applications 后：

```json
{
  "mcpServers": {
    "markbox": {
      "command": "/Applications/MarkBox.app/Contents/MacOS/markbox",
      "args": ["--mcp"]
    }
  }
}
```

MCP 与 GUI 是**两个进程**，共享 SQLite 文件；改库后请在列表点 **Refresh** 或切回窗口。

### 教程

循序文档在 [`docs/tutorials/`](docs/tutorials/)：

| 课 | 主题 |
|----|------|
| 01–02 | 脚手架、架构 |
| 03–05 | SQLite、CRUD UI、设置与错误 |
| 06 | MCP |
| 07 | 测试 |
| 08 | 打包 |
| 附录 | 签名 / 公证 / CI 概念 |

设计说明：[`docs/plans/`](docs/plans/)。

### 标识与数据目录

- Bundle identifier：`com.markbox.notes`
- 数据库：`~/Library/Application Support/com.markbox.notes/markbox.db`

若你本地曾用过旧版 `com.markbox.app`，可手动迁移：

```bash
OLD="$HOME/Library/Application Support/com.markbox.app"
NEW="$HOME/Library/Application Support/com.markbox.notes"
mkdir -p "$NEW"
# 仅在 NEW 尚无库文件时拷贝
cp -n "$OLD/markbox.db" "$NEW/markbox.db" 2>/dev/null || true
```

### 分发说明

- `tauri build` 产物默认**未签名**；本机可用，公开给陌生人建议 Apple Developer ID + 公证。
- 详见 `docs/tutorials/08-packaging.md` 与 `docs/tutorials/appendix-signing-ci.md`。

### License

[MIT](LICENSE)

---

## English

### What is this?

**MarkBox** is a **learning-oriented** local notes app:

- **Tauri 2** desktop shell + **React / TypeScript** UI
- **SQLite** via Rust (`NotesService`)
- **stdio MCP** (`--mcp`) sharing the same database as the GUI

It is intentionally small (no cloud sync, no full markdown editor, unsigned builds by default).

### Requirements

- macOS (primary)
- Node.js + npm, Rust (stable), Xcode CLT

### Quick start

```bash
npm install
npm run tauri dev
```

### Scripts

| Command | Purpose |
|---------|---------|
| `npm run tauri dev` | Dev app |
| `npm test` | Unit tests |
| `npm run tauri build` | macOS `.app` + `.dmg` |
| `cargo run --manifest-path src-tauri/Cargo.toml -- --mcp` | MCP stdio |

Data path: `~/Library/Application Support/com.markbox.notes/markbox.db`  
Tutorials (Chinese): [`docs/tutorials/`](docs/tutorials/)

### License

[MIT](LICENSE)