peek

本 README 中的每张截图均由一次 set_layout MCP 调用生成——参见 apps/desktop/scripts/screenshot.mjs。

peek 是一款桌面数据库 GUI，同时也是一个 MCP 服务器。让 Claude 打开一张表、运行一条查询，或排列面板以便对比——这一切都发生在你眼前的窗口中，因为 AI 工具调用和你自己的点击共享同一条命令通道。内置的聊天面板在应用内运行 Claude Code，因此你对话的智能体驱动着它所在的窗口。

功能特性

• 🤝 人类与 AI 共用一套界面 —— 每一次点击和每一次 MCP 工具调用都是同一总线上的 Command；没有隐藏状态，没有同步步骤

• 💬 内置 Claude Code —— 聊天面板通过 ACP 承载它，并回连到 peek 自己的 MCP 服务器

• 🛠️ 16 个 MCP 工具 —— 连接、探查模式、运行查询、打开视图、控制布局、通知、询问用户

• 🔒 只读，由服务器强制 —— 只读事务和标志，任何地方都不做关键字过滤

• 📎 只有你主动附加，数据才会到达 AI —— 否则一条查询最多只返回 20 行给模型

• 📦 数据库是插件 —— 六个驱动从 ~/.peek/packages/<id>/ 加载；新增一个就是安装一个目录

• ⚡ 百万行流畅滚动 —— 0 掉帧，启动约 0.5 秒，打包体积 6.3 MB（性能）

• 🔑 密码存放在操作系统钥匙串中 —— 磁盘上绝不出现明文

支持的数据库： PostgreSQL · MySQL · SQLite · Redis · Qdrant · Neo4j

Related MCP server: mcp-knowledgebase

安装

从 Releases 下载 peek-v0.0.1-macos-arm64.zip，解压后将 peek.app 拖入 Applications 文件夹。目前仅支持 Apple Silicon。

此构建为临时签名（尚无 Developer ID），因此 macOS 首次启动时会拒绝下载的应用并提示"已损坏"。清除一次隔离标志即可正常打开：

xattr -d com.apple.quarantine /Applications/peek.app

或者：系统设置 → 隐私与安全性 → "仍要打开"。签名并公证的构建已在计划中。

快速开始

要求：Node ≥ 22、pnpm 10.32.1（通过 packageManager 固定版本），以及一个要连接的数据库。目前仅在 macOS / Apple Silicon 上开发和测试。

pnpm install
pnpm dev              # opens the window; MCP server on port 7332
pnpm build            # production bundles into apps/desktop/out

在应用中：在侧边栏选择驱动，粘贴连接字符串，然后浏览。完成握手的连接会自动保存（密码存入操作系统钥匙串）。表以虚拟化网格打开，SQL 在 CodeMirror 编辑器中运行（⌘⏎），面板用 ⌘\ / ⌘⇧\ 拆分，每个结果视图都有由真实截止时间支撑的取消按钮。

测试

pnpm -r typecheck     # strict TS across every package
pnpm -r test          # 2567 tests; driver suites need real servers (see below)

桌面端测试套件是纯逻辑，无需任何外部依赖。每个驱动套件都是集成测试，从环境中读取目标，当服务器不可达时自动跳过：

PEEK_TEST_PG_URL="postgresql://user@localhost:5432/your_db" \
PEEK_TEST_REDIS_URL="redis://localhost:6379" \
PEEK_TEST_QDRANT_URL="http://localhost:6333" \
PEEK_TEST_MYSQL_URL="mysql://root:pw@localhost:3306/peek_test" \
PEEK_TEST_NEO4J_URL="bolt://localhost:7687" PEEK_TEST_NEO4J_PASSWORD="…" \
pnpm -r test

注意事项：Redis / Qdrant / MySQL / SQLite 套件会自行创建并清理测试数据；PostgreSQL 套件目前针对特定的开发数据库进行断言（自助配置是待办事项）；Neo4j 始终需要显式密码。此外还有一个针对构建后应用端到端冒烟测试（smoke-drivers.mjs），通过 MCP 驱动所有已配置的驱动。

从 Claude Code 中使用

peek 在启动时启动其 MCP 服务器（仅回环地址，bearer 令牌认证），并将端点写入 ~/.peek/mcp.json（权限 0600）。注册一次：

claude mcp add peek --transport http http://127.0.0.1:7332/mcp \
  --header "Authorization: Bearer <token from ~/.peek/mcp.json>"

确切的命令（已填入令牌）在 设置 → MCP 端点 中一键可得，那里也是更改端口或轮换令牌的地方。

工具

刻意没有提供将完整结果集交给模型的工具。

聊天面板

一次 ask 调用，挂起直到人类回答——智能体不能回答自己的问题。

你不必自带客户端：peek 本身就以标签页形式承载 Claude Code。内嵌智能体启动时没有文件工具、没有 shell，也没有除 peek 自身以外的任何 MCP 服务器——它不会继承你的 settings.json、CLAUDE.md 或已配置的 MCP 服务器，verify-chat-security.mjs 会针对真实智能体验证这一点。两个设置（默认均关闭）让你可以选择重新开启：文件/命令工具，以及你自己的 MCP 服务器。每个开关旁边都说明了其代价——参见安全模型。

安全模型

• MCP 服务器： 仅回环地址，需要 Authorization: Bearer，Host/Origin 针对 DNS 重绑定进行检查，令牌以恒定时间比较且绝不记录日志。

• 只读： 在数据库服务器支持的地方强制执行（事务、标志）；Redis 和 Qdrant 驱动根本不发出写命令。一个缺口：预先存在的存储过程如果自行开启读写事务——对你关心的任何数据，请使用只读数据库账户。

• 进程隔离： 每个连接一个子进程运行驱动；卡死的查询或崩溃不会拖垮窗口，杀死进程就是无条件的取消。包代码绝不在主进程中运行。

• 包是受信任的，而非沙箱化的。 你安装什么就信任什么——与 VS Code 扩展或 MCP 服务器同理。peek 会验证包的清单格式、隔离其进程、并从其环境中剥离凭据，但没有签名检查，也没有沙箱。详见设计文档。

• 启用智能体的文件工具有真实代价： 能读取 ~/.peek/mcp.json 的智能体就持有 bearer 令牌，权限提示也不再是屏障。设置面板在开关打开时会明确说明这一点。

性能

在 Apple M2 Max（macOS，120 Hz Retina）上，针对生成的 1,000,000 行 SQLite 测试数据测量，由两个可复现的基准脚本完成（bench-startup.mjs、bench-scroll.mjs）：

结果以列式块流式传输，带背压和 LRU 缓存；虚拟滚动是手写的，因为 Chromium 在 Retina 分辨率下会静默地将约 699,000 行处的元素高度截断——peek 中没有任何 DOM 尺寸是从行数推导出来的。

状态与限制

早期但真实可用：全部六个数据库都能连接、探查并流式传输行；上述布局、聊天、MCP 接口和包系统均已实现并通过测试。pnpm build 生成构建产物，package-mac.mjs 生成 macOS .app；目前还没有签名安装包。在只读路径完全稳定之前，写入功能刻意不在范围内。

已知限制，简述如下（详见 docs/PLAN.md 和 docs/design/）：

• 大型查询在约 20 万行处会暂停（这是设计使然），直到你继续滚动；从约 200 MB 缓存中逐出的行无法原地重新获取——请重新运行查询。

• 固定 24 px 行高；大值在模态框中打开。

• 可访问性在布局层面做得扎实（ARIA tablist、roving tabindex、焦点管理），但面板主体内部很少，且未针对真实屏幕阅读器验证。

• 恢复的工作区会重新打开布局、标签页和编辑器文本，但绝不会重新运行查询。

• Qdrant：不支持查询取消（API 本身不提供——按钮上会说明），表头排序也尚未实现。

• 存储的凭据与你的操作系统用户账户同等私密；二进制签名随首个发布构建一起落地。

仓库结构

peek/
├─ packages/
│  ├─ core/           # command schemas, workspace types, capability + chunk protocol, driver-host runtime
│  ├─ db-postgres/    # PostgreSQL driver
│  ├─ db-sql/         # MySQL + SQLite behind one dialect layer
│  ├─ db-redis/       # Redis driver
│  ├─ db-qdrant/      # Qdrant driver
│  └─ db-neo4j/       # Neo4j driver, plus the `graph` view kind
├─ apps/desktop/      # Electron app: main / preload / renderer, plus scripts/ (benchmarks, smoke tests)
└─ docs/              # PLAN.md (design record) and docs/design/ (per-change design docs)

docs/PLAN.md 是权威的设计记录——架构决策、 性能预算和里程碑定义（PLAN.zh-CN.md 是中文 原版）。每次变更的设计文档位于 docs/design/ 中。

许可证

MIT。参见 LICENSE。