peek

Cada captura de pantalla de este README fue producida por una única llamada MCP set_layout — ver apps/desktop/scripts/screenshot.mjs.

peek es una GUI de bases de datos de escritorio que además funciona como servidor MCP. Pídele a Claude que abra una tabla, ejecute una consulta u organice los paneles para comparar: todo sucede en la ventana que tienes delante, porque las llamadas a herramientas de la IA y tus propios clics comparten un único canal de comandos. Un panel de chat integrado ejecuta Claude Code dentro de la aplicación, así que el agente con el que hablas controla la ventana en la que vive.

Características

• 🤝 Una interfaz para humanos e IA — cada clic y cada llamada a herramienta MCP es un Comando en el mismo bus; sin estado fantasma, sin paso de sincronización

• 💬 Claude Code integrado — el panel de chat lo aloja mediante ACP, conectado de vuelta al propio servidor MCP de peek

• 🛠️ 16 herramientas MCP — conectar, inspeccionar esquemas, ejecutar consultas, abrir vistas, controlar el diseño, notificar, preguntar al usuario

• 🔒 Solo lectura, impuesto por el servidor — transacciones y banderas de solo lectura, sin filtrado de palabras clave en ningún sitio

• 📎 Los datos llegan a la IA solo cuando los adjuntas — de lo contrario, una consulta devuelve al modelo como máximo 20 filas

• 📦 Las bases de datos son plugins — seis controladores se cargan desde ~/.peek/packages/<id>/; añadir uno significa instalar un directorio

• ⚡ Un millón de filas se desplazan — 0 fotogramas perdidos, ~0,5 s de arranque, paquetes de 6,3 MB (Rendimiento)

• 🔑 Las contraseñas viven en el llavero del sistema — nunca en texto plano en el disco

Bases de datos: PostgreSQL · MySQL · SQLite · Redis · Qdrant · Neo4j

Related MCP server: MCP Server for Database

Instalación

Descarga peek-v0.0.1-macos-arm64.zip desde Releases, descomprímelo y arrastra peek.app a Aplicaciones. Solo Apple Silicon por ahora.

Esta compilación está firmada ad hoc (sin Developer ID todavía), así que macOS rechazará la aplicación descargada como «dañada» en el primer lanzamiento. Elimina la marca de cuarentena una vez y se abrirá con normalidad:

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

Alternativa: Ajustes del Sistema → Privacidad y Seguridad → «Abrir de todos modos». Una compilación firmada y notarizada está prevista.

Inicio rápido

Requisitos: Node ≥ 22, pnpm 10.32.1 (fijado mediante packageManager) y una base de datos a la que apuntar. Desarrollado y probado solo en macOS / Apple Silicon hasta ahora.

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

En la aplicación: elige un controlador en la barra lateral, pega una cadena de conexión y navega. Las conexiones que completan un handshake se guardan automáticamente (las contraseñas van al llavero del sistema). Las tablas se abren como cuadrículas virtualizadas, el SQL se ejecuta en un editor CodeMirror con ⌘⏎, los paneles se dividen con ⌘\ / ⌘⇧\, y cada vista de resultados tiene un botón de cancelar respaldado por un plazo real.

Pruebas

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

La suite de escritorio es lógica pura y no necesita nada. Cada suite de controladores es una suite de integración que lee su objetivo del entorno y se omite cuando el servidor no es accesible:

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

Advertencias: las suites de Redis / Qdrant / MySQL / SQLite crean y limpian sus propios fixtures; la suite de PostgreSQL actualmente verifica contra una base de datos de desarrollo específica (el autoaprovisionamiento es un TODO); Neo4j siempre necesita una contraseña explícita. También hay una prueba de humo de extremo a extremo de la aplicación compilada (smoke-drivers.mjs) que maneja cada controlador configurado sobre MCP.

Usarlo desde Claude Code

peek inicia su servidor MCP al arrancar (solo loopback, autenticado con token de portador) y escribe el endpoint en ~/.peek/mcp.json (modo 0600). Regístralo una vez:

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

El comando exacto, con el token ya rellenado, está a un clic en Configuración → Endpoint MCP, que es también donde puedes cambiar el puerto o rotar el token.

Las herramientas

Deliberadamente no hay ninguna herramienta que entregue un conjunto de resultados completo al modelo.

El panel de chat

Una llamada ask, suspendida hasta que el humano responda — los agentes no pueden responder a sus propias preguntas.

No tienes que traer tu propio cliente: peek aloja el propio Claude Code, como una pestaña. El agente integrado arranca sin herramientas de archivos, sin shell y sin servidores MCP aparte de los de peek — no hereda tu settings.json, CLAUDE.md ni los servidores MCP configurados, y verify-chat-security.mjs lo comprueba contra el agente real. Dos ajustes (ambos desactivados por defecto) te permiten volver a activarlos: herramientas de archivos/comandos y servidores MCP propios. Cada uno explica su coste junto al interruptor — ver Modelo de seguridad.

Modelo de seguridad

• Servidor MCP: solo loopback, se requiere Authorization: Bearer, Host/Origin comprobados contra el DNS rebinding, token comparado en tiempo constante y nunca registrado.

• Solo lectura: impuesto por el servidor de base de datos siempre que se puede (transacciones, banderas); los controladores de Redis y Qdrant simplemente no emiten ningún comando de escritura. Una laguna: un procedimiento almacenado preexistente que abra su propia transacción de lectura-escritura — usa una cuenta de base de datos de solo lectura para cualquier cosa que te importe.

• Aislamiento de procesos: los controladores se ejecutan en un proceso hijo por conexión; una consulta atascada o un fallo no pueden tumbar la ventana, y matar el proceso es una cancelación incondicional. El código de los paquetes nunca se ejecuta en el proceso principal.

• Los paquetes son de confianza, no están en sandbox. Lo que instalas es aquello en lo que confías — el mismo trato que una extensión de VS Code o un servidor MCP. peek valida la forma del manifiesto de un paquete, aísla sus procesos y elimina las credenciales de su entorno, pero no hay comprobación de firma ni sandbox. Detalles en los documentos de diseño.

• Activar las herramientas de archivos del agente tiene un coste real: un agente que pueda leer ~/.peek/mcp.json tiene el token de portador, y las indicaciones de permiso dejan de ser una barrera. El panel de ajustes dice exactamente esto cuando el interruptor está activado.

Rendimiento

Medido en un Apple M2 Max (macOS, Retina 120 Hz) contra un fixture SQLite generado de 1.000.000 de filas, mediante dos scripts de benchmark reproducibles (bench-startup.mjs, bench-scroll.mjs):

Los resultados se transmiten en bloques por columnas con contrapresión y una caché LRU, y el desplazamiento virtual está escrito a mano porque Chromium limita silenciosamente las alturas de los elementos alrededor de 699.000 filas en resolución Retina — ninguna dimensión del DOM en peek se deriva del número de filas.

Estado y limitaciones

En fase temprana pero real: las seis bases de datos se conectan, inspeccionan y transmiten filas; el diseño, el chat, la superficie MCP y el sistema de paquetes descritos arriba están implementados y probados. pnpm build genera los paquetes, y package-mac.mjs genera un .app de macOS; todavía no hay instalador firmado. Las escrituras quedan deliberadamente fuera del alcance hasta que la vía de solo lectura se haya estabilizado por completo.

Limitaciones conocidas, brevemente (detalles en docs/PLAN.md y docs/design/):

• Una consulta grande se pausa (por diseño) en ~200k filas hasta que te desplazas más; las filas desalojadas de la caché de ~200 MB no se pueden volver a recuperar en su sitio — vuelve a ejecutar la consulta.

• Altura de fila fija de 24 px; los valores grandes se abren en un modal.

• La accesibilidad es sólida a nivel de diseño (listas de pestañas ARIA, tabindex móvil, gestión del foco), pero mínima dentro de los cuerpos de los paneles, y sin verificar con un lector de pantalla real.

• Un espacio de trabajo restaurado reabre el diseño, las pestañas y el texto del editor, pero nunca vuelve a ejecutar las consultas.

• Qdrant: no hay cancelación de consultas (la API no ofrece ninguna — así lo dice el botón), y los encabezados de tabla aún no pueden ordenarse.

• Las credenciales almacenadas son tan privadas como tu cuenta de usuario del sistema operativo; la firma binaria llegará con la primera compilación publicada.

Estructura del repositorio

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 es el registro de diseño de referencia — decisiones de arquitectura, el presupuesto de rendimiento y las definiciones de hitos (PLAN.zh-CN.md es el original en chino). Los documentos de diseño por cambio se encuentran en docs/design/.

Licencia

MIT. Ver LICENSE.