Manual de Firescope

Instalación

1. Desde la página de descarga obtén el .dmg para Mac (puedes elegir entre Apple Silicon e Intel).
2. Abre el .dmg descargado y arrastra el icono de Firescope a la carpeta «Aplicaciones».
3. Inicia Firescope desde la carpeta de Aplicaciones.

Windows

1. Desde la página de descarga obtén y ejecuta Firescope-Setup.exe.
2. Si aparece un aviso de SmartScreen la primera vez, continúa con «Más información» → «Ejecutar de todas formas».

Configuración inicial (idioma y tema)

Al iniciar por primera vez se abre un asistente de configuración de 4 pasos. Primero eliges el idioma de la interfaz (incluye 9 idiomas: 日本語, English, 简体中文, 繁體中文, 한국어, Español, Português, Français y Deutsch). El cambio se aplica al instante al hacer clic, así que si tienes dudas, pruébalo y compruébalo.

A continuación eliges el tema visual: Light y Dark, entre 10 opciones en total. También se previsualiza al instante con un clic.

Conectar con Firestore

Hay dos formas de conectar. La más sencilla es iniciar sesión con tu cuenta de Google, que no requiere preparar ningún archivo de clave. También puedes seguir usando, como siempre, una clave privada de cuenta de servicio (JSON).

Método 1: iniciar sesión con tu cuenta de Google

Autoriza Firescope con tu cuenta de Google habitual y conéctate eligiendo sin más de la lista de proyectos de Firebase a los que tienes acceso. No hace falta descargar ni guardar ningún archivo de clave.

1. En la pestaña «Google» del diálogo de añadir conexión, pulsa «Iniciar sesión con Google» y se abrirá la pantalla de consentimiento en el navegador.
2. Al volver a la app se listan los proyectos de Firebase a los que tienes acceso. Puedes acotarlos con la búsqueda y seleccionarlos en bloque con «Seleccionar los N proyectos visibles». Los proyectos ya conectados no se pueden seleccionar (aparecen como «Conectado» para evitar registros duplicados).
3. Para cada proyecto elegido indica su etiqueta de entorno y si es de solo lectura. La etiqueta de entorno se deduce automáticamente del ID del proyecto, así que basta con corregir las que no coincidan.
4. Confirma con «Añadir N conexiones».

Método 2: usar una clave privada de cuenta de servicio (JSON)

Esta es la opción si quieres usar una cuenta de servicio de CI o conectarte sin una cuenta de Google. Aunque no la tengas todavía, siguiendo las indicaciones en pantalla puedes obtenerla en aproximadamente un minuto.

1. Al pulsar «Abrir la página de configuración de cuenta de servicio» se abre en el navegador la página correspondiente de la consola de Firebase (ruta: Configuración del proyecto → Cuentas de servicio).
2. Haz clic en «Generar nueva clave privada» para descargar el JSON.
3. Vuelve a Firescope y, desde «Seleccionar archivo JSON para conectar», elige el JSON descargado. También puedes seleccionar los JSON de varios proyectos a la vez para conectarlos simultáneamente.
4. Elige el entorno de destino (desarrollo / pruebas / staging / producción). Se muestra en la barra lateral como una etiqueta de color, y esta etiqueta también determina la intensidad de la protección de seguridad.

Organizar las conexiones (grupos y ocultar)

Cuando se acumulan conexiones, cuesta distinguir en la barra lateral qué proyecto es cada una. Firescope añade encabezados y las ordena automáticamente, sin que tengas que reordenar nada.

Separación automática

Las conexiones se separan primero según con qué credencial se conectan.

• Cuenta de Google — se separan por cada cuenta con la que iniciaste sesión. Aunque uses varias cuentas, ves de un vistazo de cuál procede cada conexión
• Clave del Admin SDK — por cada clave privada de cuenta de servicio
• Emulador — conexiones al emulador de Firestore local

Dentro de cada bloque, además, las conexiones se agrupan por la parte común del nombre de destino. Como al comparar se descartan los sufijos que indican el entorno, como dev / staging / production / test / env, las conexiones OCEAN-dev, ocean-pro, OCEAN-staging y OCEAN-test quedan bajo un único encabezado: OCEAN (no se distinguen mayúsculas y minúsculas).

Ocultar las conexiones que no usas

Puedes ocultar una conexión de la lista sin desconectarla. La configuración y las claves se conservan, así que puedes revertirlo cuando quieras.

1. Clic derecho en la conexión → «Ocultar esta conexión». Desde el encabezado de un grupo tienes «Ocultar este grupo» y, con una selección múltiple (⌘ / Shift y clic), «Ocultar las conexiones seleccionadas».
2. Cuando hay conexiones ocultas, en la parte superior de la barra lateral aparece un icono de ojo (con una insignia de cantidad).
3. Al pulsar ese icono, las conexiones ocultas se muestran atenuadas. Con clic derecho → «Volver a mostrar» las restauras. También puedes restaurarlas en bloque, por grupo o mediante una selección múltiple.

Ver los datos

Abre una conexión en la barra lateral y haz clic en una colección para ver los documentos en una tabla. Cada encabezado de columna incluye una insignia de tipo (string / int / time, etc.), así que la forma de los datos se entiende de un vistazo.

• Al hacer clic en una fila, el panel derecho muestra todos los campos del documento.
• El orden, la cantidad mostrada y la búsqueda por grupo (collection group) se cambian desde la barra de herramientas.
• El número de lecturas se muestra siempre en la barra de estado (como referencia para la facturación).

Paleta de comandos (⌘K)

Con ⌘K abres una búsqueda global desde cualquier pantalla. Busca a la vez colecciones, conexiones, pantallas, «vistos recientemente» y marcadores; al escribir 6 caracteres o más también aparecen resultados de búsqueda de documentos por ID.

• Usa ↑↓ para moverte entre resultados y Enter para ejecutar. Cambia de pantalla sin soltar el teclado.
• También puedes lanzar desde aquí acciones frecuentes: cambiar el tema, activar/desactivar el enmascarado de valores, abrir la configuración o la lista de atajos.

Búsqueda en la tabla (⌘F)

Con una tabla abierta, pulsa ⌘F (Ctrl+F en Windows) para lanzar una búsqueda por subcadena en todas las celdas, sin distinguir mayúsculas y minúsculas. Las coincidencias se resaltan en ámbar y cada pulsación de Enter desplaza el cursor a la siguiente coincidencia con un scroll suave.

• Busca en todas las columnas visibles, incluida la columna de ID.
• Enter va a la siguiente coincidencia y Shift+Enter a la anterior; al llegar al final, vuelve al principio.
• La celda encontrada queda seleccionada, así que puedes continuar con las flechas, ⌘C o F2 para editar.
• Antes de que se carguen todos los documentos, solo se busca en el rango ya cargado (aparece un * junto al número de coincidencias).
• La búsqueda de colecciones de la barra lateral pasó a ⌘⇧F (en pantallas sin tabla, ⌘F sigue enfocándola).

Potencia de consultas

Puedes guardar las condiciones de consulta que armes como consulta guardada con un nombre y recuperarla en cualquier momento desde la lista (restaura de una vez condiciones, orden y cantidad).

Al elegir un campo numérico (int / double), la barra de herramientas muestra la suma y el promedio tras aplicar los filtros actuales.

En «Gráfico» se dibuja al instante, a partir de los documentos ya cargados, un histograma para los campos numéricos y la frecuencia de aparición (top 10) para los campos de texto o enum. No genera lecturas adicionales.

En «Generar código» puedes copiar las condiciones que armaste como código de firebase-admin (Node.js), o, si la condición requiere un índice compuesto, copiarla como definición en formato firestore.indexes.json.

Nombres lógicos (traducción de campos)

Puedes mostrar nombres de campo en inglés como carryingOutCoffinMasterId con un nombre lógico, por ejemplo en español. El interruptor «Nombre lógico» de la barra de herramientas alterna en cualquier momento entre el nombre físico y el lógico.

• El diccionario se edita desde el icono 📖 de la barra de herramientas. Tiene dos niveles de alcance: «común a toda la conexión» y «solo esta colección (sobrescribe)».
• «Traducción automática» completa los campos vacíos de una vez, usando el diccionario incorporado y una API de traducción gratuita.
• Al pulsar «Abrir Google Translate» se abre la página de traducción con los nombres de campo convertidos a texto en inglés; solo copia la traducción y vuelve a la app para aplicarla en bloque.
• Haz clic derecho en el encabezado de una columna → «Definir nombre lógico…» para editar solo esa columna al instante.
• La insignia de tipo del encabezado (string / int, etc.) se puede mostrar u ocultar con el interruptor «Mostrar tipo».

Pestañas y grupos

Haz clic derecho en una colección → «Abrir en una pestaña nueva» para añadir pestañas, como en un navegador. Las pestañas se pueden organizar en grupos, al estilo Chrome.

• Haz clic derecho en una pestaña → «Añadir a un grupo nuevo» para crear un grupo. Puedes asignarle nombre y color.
• Al hacer clic en el chip del grupo, se contrae o se expande.
• Doble clic en una pestaña para cambiar su nombre y color de fondo.
• Arrastra y suelta para reordenar y mover pestañas dentro o fuera de un grupo.
• El estado de las pestañas se restaura tras reiniciar (puedes desactivarlo en la configuración).

Vista dividida

Haz clic derecho en una colección → «Mostrar dividido a la derecha» para ver dos colecciones una junto a otra. Muy útil para cotejar datos maestros con transacciones.

• También puedes dividir arrastrando una colección desde la barra lateral hasta el borde izquierdo o derecho de la pantalla.
• Arrastrando el chip de un panel puedes intercambiar izquierda/derecha o extraerlo a una pestaña nueva.
• El estado de la división se conserva por pestaña.

Monitoreo en tiempo real

Al pulsar «Monitorear» en la barra de herramientas, los cambios de la colección que estás viendo se reflejan en vivo en la tabla. El contenido escrito por otra app o por tu servidor llega directamente, sin necesidad de recargar.

• En el diálogo previo al inicio puedes acotar por condiciones (campo/valor), orden y cantidad.
• En el feed de cambios de la derecha aparecen en orden cronológico las altas, actualizaciones y bajas, incluyendo qué campos cambiaron.
• El monitoreo es de solo lectura. Las operaciones de escritura mientras monitoreas siguen pasando normalmente por el pipeline de seguridad.
• Puedes monitorear hasta 5 colecciones a la vez.
• Se detiene automáticamente tras un tiempo determinado (configurable), para evitar un uso excesivo de lecturas.

Editar los datos

Haz doble clic en una celda para editarla ahí mismo. Enter confirma, Esc cancela. Los tipos como int o timestamp se conservan al escribir.

Toda escritura pasa por el pipeline de seguridad:

1. Confirmación — aparece un diálogo cuya intensidad depende de la etiqueta de entorno × el riesgo de la operación. Las operaciones destructivas en producción requieren escribir el ID del proyecto.
2. Copia de seguridad automática — los documentos afectados se guardan como snapshot antes de ejecutar.
3. Ejecución — se realiza la escritura.
4. Registro de auditoría — se registra el resultado, con éxito o error (consúltalo desde «Registro de auditoría» en la barra inferior).

Copia de seguridad y restauración

Los snapshots tomados justo antes de una operación destructiva se acumulan en «Copias de seguridad», en la barra inferior. Al seleccionar uno se abre la vista previa de restauración, donde puedes revisar las diferencias (recrear / sobrescribir / sin cambios) antes de restaurar.

• Con ⌘Z (o el icono ↩︎ de la barra lateral) puedes restaurar al instante tu última escritura.
• Los snapshots más antiguos se eliminan al superar el límite de generaciones. Fija con 📌 los que quieras conservar.

Consola

En «Consola», en la barra lateral, puedes escribir consultas en JavaScript al estilo firebase-admin. Al ejecutar con ⌘Enter, el resultado se muestra en una tabla con tipos anotados.

const snap = await db.collection('orders')
  .where('status', '==', 'paid')
  .orderBy('amount', 'desc')
  .limit(20)
  .get();
return snap.docs.map((d) => ({ id: d.id, ...d.data() }));

• Para quienes prefieren el mouse, también hay un generador visual (obtener / actualizar / crear / eliminar). Las condiciones armadas se pueden convertir a JS con «Reflejar en código».
• El código que incluye escrituras se ejecuta en el orden ensayo (dry-run) → vista previa de escritura → aplicar, así que los datos nunca cambian de repente.
• También admite vista de join (combinación) entre colecciones.

Importación/exportación CSV

Exportación

Al pulsar «Exportar CSV» en la barra de herramientas de una colección, puedes guardar en CSV el resultado de la consulta que estás viendo (con filtros y orden aplicados). El encabezado incluye anotaciones de tipo, así que al reimportarlo más tarde los tipos no se pierden.

Importación

1. En la barra de herramientas, «Importar» → selecciona el archivo CSV (Shift_JIS se detecta automáticamente).
2. Revisa el tipo de cada columna y el modo (upsert / solo nuevos / solo actualizar).
3. «Verificar cantidad» muestra una vista previa de cuántos registros son nuevos y cuántos se sobrescribirán.
4. «Ejecutar importación» → tras un diálogo de confirmación se realiza la carga. Los registros sobrescritos se respaldan automáticamente antes de ejecutar.

Revisión de esquema (detección de inconsistencias)

Haz clic derecho en una colección → «Revisión de esquema…» para leer toda la colección y detectar automáticamente campos con tipos mixtos, campos ausentes solo en algunos documentos y campos poco frecuentes que podrían ser errores de tipeo (límite de 20.000 documentos).

• Los campos faltantes que se repiten en el mismo grupo de documentos se agrupan en una sola tarjeta. «Abrir todo» marca automáticamente todas las filas afectadas, listas para, por ejemplo, eliminarlas en bloque.
• Al hacer clic en el ID de un documento afectado, la tabla hace scroll automático hasta esa fila y la resalta.
• Los resultados se conservan aunque cierres el asistente, así que puedes ir y volver revisando documentos las veces que necesites.
• En la pestaña «Validación con esquema Zod» puedes pegar un esquema Zod (TypeScript) y validar todos los documentos.

Proteger las escrituras con un esquema

En la pestaña «Validación con esquema Zod» de la revisión de esquema no solo puedes validar, también puedes configurar la aplicación en las escrituras. Elige entre tres niveles: ninguno / advertencia / bloqueo. Con «bloqueo», el proceso principal rechaza cualquier escritura que infrinja el esquema (no se puede saltar aunque se evite la interfaz). La aplicación solo afecta a los documentos cuya ruta de colección coincide exactamente.

Con un esquema Zod registrado, al crear un documento nuevo puedes usar el modo «Entrada por formulario». El formulario se genera automáticamente a partir de los tipos del esquema, así que puedes crear documentos rellenando los campos obligatorios sin escribir JSON a mano (en colecciones sin esquema registrado, el formulario también puede construirse a partir de la estimación de tipos de la revisión de esquema).

Exportar diagrama ER

Clic derecho en una conexión de la barra lateral → "Exportar diagrama ER…": se muestrea cada colección (hasta 100 documentos) para generar automáticamente un diagrama ER. Además de los campos reference y las subcolecciones, las referencias por ID de texto como customerId se infieren del nombre del campo y se dibujan como relaciones punteadas.

• Alterna al instante "Mostrar campos", "Solo claves", "Mostrar tipos" e "Incluir nombres lógicos" — todas las variantes están prerenderizadas.
• Zoom con pellizco o Ctrl+rueda, arrastra para desplazarte y un clic para ajustar el diagrama completo.
• Copia el texto Mermaid o guarda como .mmd / .svg — pégalo tal cual en GitHub o Notion.
• Las líneas hacia padres con muchas subcolecciones se omiten del diagrama para facilitar la lectura (permanecen en el texto Mermaid).

Migración de datos

En «Actualización en lote», además de establecer campos en masa, también puedes renombrar campos y convertir tipos. Antes de ejecutar, revisa siempre la vista previa en modo dry-run con las diferencias de todos los registros.

Al hacer clic derecho en una colección → «Eliminar colección…» se eliminan también las subcolecciones, de forma recursiva. El recuento del diálogo de confirmación incluye las subcolecciones, y los documentos afectados se respaldan automáticamente antes de ejecutar.

«Generar datos de prueba» estima la estructura de campos a partir de la distribución de tipos de los documentos existentes (revisión de esquema) y crea de una vez la cantidad indicada de documentos de ejemplo. Es una función pensada para verificar el funcionamiento en desarrollo o con el emulador.

Comparar y copiar entornos

Comparar con otro entorno

Haz clic derecho en una colección → «Comparar con otro entorno…» para cotejar la misma colección entre dos entornos (por ejemplo, desarrollo y producción). Las diferencias (altas / bajas / cambios) se listan por documento y por campo.

• Puedes indicar campos a excluir de la comparación, como updatedAt.
• El contenido de las diferencias se puede exportar como CSV.

Copiar a otro entorno

«Copiar a otro entorno…» te permite duplicar una colección hacia otra conexión (entorno). Antes de ejecutar se previsualiza la cantidad y si habrá sobrescrituras, y la escritura en producción pasa por la misma protección estricta de siempre.

Comparaciones y diferencias

En la comparación de entornos también puedes seleccionar las diferencias (documentos con contenido distinto o presentes en un solo lado) y aplicarlas directamente al destino de escritura mediante la sincronización de diferencias. El sentido de la sincronización se sugiere a partir de las etiquetas de entorno de las conexiones, y la aplicación pasa, como de costumbre, por el pipeline de seguridad (confirmación y copia de seguridad automática).

El botón «Comparar» del panel derecho del documento permite comparar campo por campo el documento abierto con cualquier otro documento (también de otra colección u otra conexión).

El «Historial de cambios» de un documento ordena las copias de seguridad automáticas como versiones cronológicas, y puedes elegir dos versiones cualesquiera (incluida la actual) para comparar sus diferencias.

Usuarios de Authentication

Desde «Authentication», en la barra lateral, puedes ver y administrar los usuarios de Firebase Authentication.

• Lista de correo, nombre visible, proveedor, fecha de creación y último inicio de sesión. El interruptor de nombre lógico también traduce los nombres de los campos.
• Permite deshabilitar / habilitar y eliminar usuarios, y enviar correos de restablecimiento de contraseña.
• Puedes copiar el UID de un usuario para cotejarlo con los documentos de Firestore.
• Las operaciones destructivas (como eliminar) pasan por el mismo pipeline de seguridad que Firestore (confirmación → registro de auditoría).

Registro compartido (quién / cuándo / qué)

Registra los metadatos de las escrituras en el Firestore del proyecto, para que todos los que se conecten al mismo proyecto vean quién hizo qué y cuándo.

• Actívelo por conexión: clic derecho en la conexión → «Registrar registro compartido». El diálogo de confirmación explica todo y permite configurar su nombre de operador en el momento.
• Solo se registran metadatos (nombre del operador, tipo de operación, ruta, resultado, duración). Nunca se incluyen los valores de los documentos ni se envía nada a servidores externos: los eventos viven en la colección _firescope_audit del proyecto.
• Consúltelo en Registro de operaciones → pestaña «Registro compartido»: línea de tiempo agrupada por fecha con filtros de operador/tipo/período. Haga clic en una fila para ver los detalles y abrir el documento en la cuadrícula.
• Los registros se eliminan automáticamente a los 30 días.

Buscar y compartir

«Búsqueda de valores» localiza un valor cuando no sabes en qué campo está, buscando en todos los documentos y todos los campos de la colección. Antes de ejecutar se muestra una estimación de las lecturas necesarias, para que puedas usarlo con confianza incluso en colecciones grandes.

Puedes marcar un documento con ★ marcador para recuperarlo en cualquier momento desde el icono ★ de la barra lateral, incluso entre distintas conexiones. La pestaña «Vistos recientemente» guarda automáticamente el historial de los documentos que abriste.

• Desde «Enlace», en el panel derecho del documento, puedes copiar un enlace directo (firescope://); al compartirlo, por ejemplo en Slack, la otra persona puede abrir ese mismo documento directamente en su Firescope.
• El icono de enlace externo de las migas de pan lleva directamente a la ruta correspondiente en la consola de Firebase (web); no se muestra en conexiones al emulador.

Operación

El monitoreo en tiempo real admite alertas por condición. Registra «cuando se añada», «cuando se elimine» o «cuando cambie un campo indicado» para recibir una notificación de escritorio cuando ocurra un cambio que coincida.

Al hacer clic en el número de lecturas del pie de página, un popover muestra el recuento aproximado de lecturas de la sesión, el coste estimado y su evolución.

En la pestaña «Compartir y migrar» de la configuración puedes exportar/importar en un solo archivo JSON parte de los ajustes de la interfaz, como los nombres lógicos de campo, las consultas guardadas y los marcadores. Nunca incluye la clave privada de las conexiones, la información de licencia ni las etiquetas de entorno, por lo que es útil para compartir en equipo o al cambiar de equipo.

Al activar «Ocultar valores» en la barra de herramientas, se muestran los datos reales enmascarados (••••) manteniendo intactos los nombres de campo, los tipos y la estructura. Útil al compartir pantalla o hacer capturas (es solo una función de visualización; los datos reales no cambian).

Servidor MCP (integración con agentes de IA)

Firescope incluye un servidor MCP (Model Context Protocol) integrado. Al conectarlo desde un agente de IA como Claude Code, puedes listar colecciones de Firestore, obtener documentos y ejecutar consultas directamente desde la conversación.

Inicio (desde la raíz del repositorio):

# Para conectar con el emulador
FIRESCOPE_MCP_PROJECT_ID=your-project \
FIRESCOPE_MCP_EMULATOR_HOST=127.0.0.1:8080 \
npm run mcp

# Para conectar con un proyecto real mediante JSON de cuenta de servicio
FIRESCOPE_MCP_SERVICE_ACCOUNT_PATH=/path/to/service-account.json \
npm run mcp

Ejemplo de configuración en el cliente MCP (.mcp.json):

{
  "mcpServers": {
    "firescope": {
      "command": "npm",
      "args": ["run", "mcp"],
      "cwd": "/path/to/firescope",
      "env": {
        "FIRESCOPE_MCP_SERVICE_ACCOUNT_PATH": "/path/to/service-account.json"
      }
    }
  }
}

• Se ofrecen tres herramientas: listar colecciones (firestore_list_collections), obtener un documento (firestore_get_document) y ejecutar una consulta (firestore_query_collection, con filtros, orden y límite de cantidad).
• Reutiliza la misma lógica interna que el generador de consultas de la interfaz gráfica, así que el formato del resultado coincide con lo que muestra la app.

Actualización

• Las actualizaciones se comprueban automáticamente cada 6 horas y al iniciar (también puedes comprobarlo manualmente desde Configuración → Información → «Buscar actualizaciones»).
• Si se publica una actualización obligatoria, desde la pantalla de actualización al iniciar se realiza automáticamente la descarga → el reinicio → la aplicación, sin necesidad de pulsar ningún botón.
• Solo si falla (por ejemplo, sin conexión) se indica la descarga manual desde el navegador.

Precios y licencia

• Desde el primer inicio tienes 14 días de prueba con todas las funciones disponibles. No se requiere registro ni datos de pago.
• Aunque venza el plazo, la visualización de datos sigue siendo gratuita.
• La compra se hace desde dentro de la app: en ⚙ Configuración → Licencia, abajo a la derecha, elige un plan (Pro / TEAM, mensual / anual) y se abrirá en el navegador la página de pago segura de Stripe. Al completar el pago, la app activa la licencia automáticamente.
• Si cambias a otro Mac, primero «Desactiva la licencia» en el equipo anterior y luego actívala en el nuevo.

Para más detalles sobre los planes, consulta la página de precios.

Preguntas frecuentes

No puedo conectar / aparece «Error de autenticación»

Comprueba que el JSON sea la clave de cuenta de servicio del proyecto correcto. Si regeneraste la clave, lo más seguro es desconectar la conexión antigua y volver a conectar con el nuevo JSON.

¿Se envían mis datos a algún lado?

No. Firescope accede directamente a Firestore desde tu Mac. Ni las claves ni los datos se envían a servidores externos.

¿Qué hace exactamente la «protección de producción»?

Es un mecanismo que ajusta automáticamente la intensidad de la confirmación según la etiqueta de entorno de la conexión y el riesgo de la operación. Por ejemplo, eliminar una colección en producción no se puede ejecutar sin escribir a mano el ID del proyecto. Como la validación ocurre en el núcleo de la app (el proceso principal) y no es solo un aviso de la interfaz, no se puede saltar por descuido.

¿Hay versión para Windows?

Sí. Descarga Firescope-Setup.exe desde la página de descargas (si aparece un aviso de SmartScreen, continúa con «Más información» → «Ejecutar de todas formas»).

¿Puedo añadir otro idioma?

Sí. Desde Configuración → Idioma puedes exportar un paquete de idioma (JSON), traducirlo e importarlo para añadir el idioma que quieras.