MarkBox

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

快速开始

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 时可用相对路径）：

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

打包安装到 Applications 后：

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

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

教程

循序文档在 docs/tutorials/：

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

设计说明：docs/plans/。

标识与数据目录

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

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

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

---

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

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/

License

MIT