Nanostores MCP

Servidor MCP para la librería Nanostores

Documentación

Nano Stores MCP

Servidor de Protocolo de Contexto de Modelo (MCP) para Nanostores — analiza, depura y monitorea tus nanostores en asistentes de IA como Claude Desktop.

  • 📊 Análisis Estático: Escaneo de proyectos basado en AST, gráficos de dependencias, inspección de stores
  • 🔥 Monitoreo en Tiempo Real: Eventos en vivo desde @nanostores/logger, métricas de rendimiento, seguimiento de actividad
  • 📚 Documentación: Busca y navega la documentación de Nanostores por tema o tipo de store
  • 🎯 Cero Configuración: Funciona de inmediato — detecta automáticamente raíces de proyectos y documentación de nanostores
  • 🌐 Agnóstico de Frameworks: Funciona con React, Vue, Svelte, Angular, Solid, Preact, Lit — cualquier framework que use Nanostores
npx nanostores-mcp

Pregunta a tu IA: "Analiza mi arquitectura de stores" o "¿Qué stores se actualizan con más frecuencia?"


Hecho en Evil Martians, consultoría de productos para herramientas de desarrollo.


Tabla de Contenidos

Características

📊 Análisis Estático (basado en AST)

Comprende la arquitectura de tus nanostores sin ejecutar tu aplicación:

  • Escaneo de proyectos — encuentra todos los stores, suscriptores y relaciones de importación/exportación
  • Gráfico de dependencias — visualiza cómo los stores dependen entre sí (diagramas Mermaid)
  • Inspección de stores — tipo (atom/map/computed/batched/persistentAtom/persistentMap/router), ubicación, patrones de uso, archivos relacionados
  • Detección de suscriptores consciente del framework — reconoce llamadas .subscribe() / .listen() y enlaces de componentes en React, Vue, Svelte y Angular
  • Soporte para SFC de Vue — analiza bloques <script> y <script setup> en archivos .vue (requiere @vue/compiler-sfc)
  • Soporte para Svelte — analiza bloques <script context="module"> y de instancia <script>, auto-suscripciones ($storeName en plantillas), y filtra runes de Svelte 5 ($state, $derived, $effect, etc.) para que no se confundan con referencias a stores (requiere svelte)
  • Soporte para DI de Angular — resuelve inyecciones de constructor @nanostores/angular NanostoresService y detecta patrones de llamada this.nanostores.useStore(...) en archivos TypeScript de componentes

🔥 Monitoreo en Tiempo Real (Integración de Logger)

Información en tiempo real sobre tu aplicación en ejecución:

  • Captura de eventos en vivo — montaje/desmontaje, cambios de valor, llamadas de acción desde @nanostores/logger
  • Análisis de rendimiento — encuentra stores ruidosos, altas tasas de error, cuellos de botella de rendimiento
  • Métricas de actividad — frecuencia de cambios, tasas de éxito/fallo de acciones, duración de acciones
  • Análisis combinado — fusiona la estructura estática con el comportamiento en tiempo de ejecución para depuración profunda

📚 Búsqueda de Documentación

Busca y navega la documentación de Nanostores directamente desde tu asistente de IA:

  • Búsqueda de texto completo — encuentra guías, referencias de API y mejores prácticas por consulta
  • Búsqueda por tipo de store — obtén documentación relevante para un tipo específico de store (atom, map, computed, etc.)
  • Detección automática — recoge documentación de nanostores en tu node_modules automáticamente

Requisitos

RequisitoVersión
Node.js^20.0.0 || >=22.0.0

Dependencia par requerida (para análisis estático):

npm install nanostores

Dependencias par opcionales — instala solo si usas el formato de archivo correspondiente:

PaqueteCuándo se necesita
@vue/compiler-sfcEscaneo de archivos Vue SFC (.vue)
svelteEscaneo de archivos Svelte (.svelte)
@nanostores/loggerMonitoreo en tiempo real (attachMcpLogger)

Sin estos paquetes opcionales el servidor sigue funcionando — simplemente omite silenciosamente los tipos de archivo no soportados.

Instalación

npm install -g nanostores-mcp
# or
pnpm add -g nanostores-mcp

O ejecuta directamente sin instalación:

npx nanostores-mcp

Configuración

Claude Desktop

Añade a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
	"mcpServers": {
		"nanostores": {
			"command": "npx",
			"args": ["-y", "nanostores-mcp"],
			"env": {
				"NANOSTORES_MCP_ROOT": "/path/to/your/project"
			}
		}
	}
}

VS Code

Requiere la extensión GitHub Copilot (VS Code 1.99+). Crea .vscode/mcp.json en tu proyecto:

{
	"servers": {
		"nanostores": {
			"type": "stdio",
			"command": "npx",
			"args": ["-y", "nanostores-mcp"]
		}
	}
}

Las herramientas están disponibles en el modo Agente de Copilot (selecciona "Agente" en el menú desplegable de Copilot Chat).

Cursor

Crea .cursor/mcp.json en la raíz de tu proyecto (o ~/.cursor/mcp.json para global):

{
	"mcpServers": {
		"nanostores": {
			"command": "npx",
			"args": ["-y", "nanostores-mcp"]
		}
	}
}

Zed

Añade a tu settings.json de Zed:

{
	"context_servers": {
		"nanostores": {
			"command": "npx",
			"args": ["-y", "nanostores-mcp"],
			"env": {
				"NANOSTORES_MCP_ROOT": "/path/to/your/project"
			}
		}
	}
}

El servidor aparece en la configuración del Panel de Agente de Zed.

Windsurf

Añade a ~/.codeium/windsurf/mcp_config.json:

{
	"mcpServers": {
		"nanostores": {
			"command": "npx",
			"args": ["-y", "nanostores-mcp"],
			"env": {
				"NANOSTORES_MCP_ROOT": "/path/to/your/project"
			}
		}
	}
}

También puedes abrir este archivo desde el icono de MCP en el panel Cascade → "Configurar".

Claude Code

Añade vía CLI:

claude mcp add --transport stdio nanostores -- npx -y nanostores-mcp

O crea .mcp.json en la raíz de tu proyecto (compartido con el equipo):

{
	"mcpServers": {
		"nanostores": {
			"command": "npx",
			"args": ["-y", "nanostores-mcp"],
			"env": {
				"NANOSTORES_MCP_ROOT": "/path/to/your/project"
			}
		}
	}
}

Variables de Entorno

VariablePredeterminadoDescripción
NANOSTORES_MCP_ROOTcwdRuta raíz del proyecto
NANOSTORES_MCP_ROOTS—Raíces delimitadas por plataforma (: en Unix, ; en Windows) para configuración multi-proyecto
WORKSPACE_FOLDER—Alias para NANOSTORES_MCP_ROOT — se establece automáticamente por VS Code y algunos editores
WORKSPACE_FOLDER_PATHS—Alias para NANOSTORES_MCP_ROOTS — se establece automáticamente por algunos editores
NANOSTORES_MCP_LOGGER_ENABLEDtrueEstablece a false o 0 para deshabilitar la recopilación de eventos en tiempo real y el puente de logger
NANOSTORES_MCP_LOGGER_PORT3999Puerto HTTP para el puente de logger
NANOSTORES_MCP_LOGGER_HOST127.0.0.1Host al que vincular. Valores permitidos: 127.0.0.1, localhost, ::1
NANOSTORES_DOCS_ROOTauto-detectRuta al directorio de documentación
NANOSTORES_DOCS_PATTERNS**/*.mdPatrones glob separados por comas para documentación

Cómo se Resuelve la Raíz del Proyecto

El servidor elige las raíces del espacio de trabajo en orden de prioridad:

  1. Variables de entorno (mayor prioridad) — NANOSTORES_MCP_ROOTS / NANOSTORES_MCP_ROOT / WORKSPACE_FOLDER_PATHS / WORKSPACE_FOLDER
  2. Raíces del cliente — raíces reportadas por el cliente MCP a través de la capacidad roots/list (se establecen automáticamente por algunos editores)
  3. Directorio de trabajo actual — process.cwd() se usa como respaldo cuando ni las variables de entorno ni las raíces del cliente están configuradas

Cuando se llama a una herramienta sin un argumento projectRoot explícito, el servidor usa la primera raíz configurada. En una configuración multi-raíz, siempre pasa projectRoot para evitar ambigüedad.

Inicio Rápido

1. Análisis Estático

Funciona de inmediato — solo apunta a tu proyecto y pregunta:

  • "Analiza mi arquitectura de stores"
  • "Explica cómo se usa nanostores en este proyecto"
  • "Dame un resumen del store $cart"
  • "Mis stores cambiaron — vuelve a escanear el proyecto" ← la IA forzará un nuevo escaneo

2. Búsqueda de Documentación

Se detecta automáticamente desde nanostores en tu node_modules:

  • "¿Cómo uso los stores computed?"
  • "Muéstrame la documentación de persistentAtom"

3. Monitoreo en Tiempo Real (Opcional)

Requiere integración de logger en tu aplicación. Consulta Monitoreo en Tiempo Real a continuación.

  • "¿Qué stores se actualizan con más frecuencia?"
  • "Muéstrame la actividad reciente de $user"
  • "Dame un informe general de salud"

Verifica tu Configuración

Ejecuta estas cuatro herramientas en orden para confirmar que todo funciona:

nanostores_ping              → should return server status and logger bridge state
nanostores_scan_project      → should list your stores and subscribers
nanostores_docs_search       → should return documentation results (requires nanostores in node_modules)
nanostores_runtime_overview  → should return overview (or "no runtime data" if logger is disabled — that's fine)

Si nanostores_scan_project devuelve cero stores, verifica que NANOSTORES_MCP_ROOT apunte al directorio correcto del proyecto.

Interfaz MCP

Recursos MCP

RecursoDescripción
nanostores://graphGráfico de dependencias completo (texto + Mermaid)
nanostores://store/{key}Detalles del store por nombre o id
nanostores://docsÍndice de documentación — todas las páginas y etiquetas
nanostores://docs/page/{id}Contenido completo de una página de documentación

Herramientas MCP

Análisis Estático

HerramientaDescripción
nanostores_scan_projectEscanea el proyecto para encontrar todos los stores, suscriptores y dependencias
nanostores_store_summaryResumen detallado de un store específico
nanostores_project_outlineVista general de alto nivel: tipos de stores, directorios principales, stores centrales
nanostores_store_subgraphVecindario de dependencias de un store expandido por BFS
nanostores_store_impactCadena causal descendente — qué se recalcula/re-renderiza si X cambia

Monitoreo en Tiempo Real

HerramientaDescripción
nanostores_runtime_overviewInforme general de salud con estadísticas para todos los stores
nanostores_store_activityLínea de tiempo de actividad para un store específico (filtrable por tipo/acción)
nanostores_find_noisy_storesIdentifica stores con alta frecuencia de cambios o tasas de error
nanostores_runtime_coverageCompara el gráfico estático con eventos en tiempo de ejecución para encontrar brechas de cobertura

Documentación

HerramientaDescripción
nanostores_docs_searchBusca documentación por query (texto completo), storeKind (atom, map, computed, persistentAtom, etc.), o ambos. Opcional: limit (predeterminado 10), tags

Usa el recurso nanostores://docs/page/{id} para leer el contenido completo de las páginas devueltas por la búsqueda.

Utilidades

HerramientaDescripción
nanostores_pingVerificación de salud del servidor y estado del puente de logger
nanostores_clear_cacheLimpia la caché del índice del proyecto para forzar un nuevo escaneo

Prompts MCP

PromptParámetrosDescripción
explain-projectfocus (opcional)Explicación guiada por IA de la arquitectura de stores de tu proyecto. focus limita a una característica/dominio (p. ej. "cart", "auth")
explain-storestore_name (obligatorio)Análisis profundo de la implementación y uso de un store específico
debug-storestore_name (obligatorio)Análisis integral que combina datos estáticos y de tiempo de ejecución
debug-project-activity—Análisis de rendimiento y optimización a nivel de proyecto
docs-how-totask (obligatorio)Guía paso a paso para una tarea de Nanostores, respaldada por documentación (p. ej. "How do I sync a map store to localStorage?")

Argumentos Avanzados de Herramientas

La mayoría de las herramientas aceptan estos argumentos opcionales que cambian significativamente su comportamiento:

ArgumentoTipoUsado enDescripción
storeIdstringstore_summary, store_subgraph, store_impactIdentificador exacto del store — formato: store:src/stores.ts#$counterName. Tiene prioridad sobre name cuando ambos se proporcionan.
namestringstore_summary, store_subgraph, store_impactNombre del store (p. ej. "$user"). Se usa cuando storeId no se proporciona.
radiusnumber (0–10, predeterminado 2)nanostores_store_subgraphSaltos BFS alrededor del store. 1 = solo dependencias directas; 2 = dependencias de dependencias. Advertencia: en stores hub altamente conectados (puntuación hub > 5) radio ≥ 2 puede devolver la mayor parte del proyecto — comienza con 1.
projectRootstringla mayoría de las herramientasQué raíz de proyecto analizar en configuraciones multi-raíz. Omítelo para usar la primera raíz configurada. Especifícalo siempre en proyectos multi-raíz.
windowMsnumberstore_activity, find_noisy_stores, runtime_overviewVentana de retroceso en milisegundos (p. ej. 60000 = últimos 60 s). Filtra eventos a ese rango de tiempo.
kindsstring[]nanostores_store_activityFiltra eventos por tipo. Valores: "mount", "unmount", "change", "action-start", "action-end", "action-error".
actionNamestringnanostores_store_activityFiltra eventos a una acción específica (p. ej. "increment").
compactbooleanscan_project, find_noisy_stores, runtime_overviewDevuelve una tabla comprimida eficiente en tokens en lugar de texto completo. Útil para proyectos grandes para reducir el uso de contexto.

Monitoreo de Tiempo de Ejecución

Para análisis de tiempo de ejecución, integra el cliente MCP Logger en tu aplicación.

1. Instala en tu aplicación y habilita el puente de registro:

npm install nanostores-mcp

El puente de registro se inicia automáticamente — no se necesita configuración adicional. Para deshabilitarlo, establece NANOSTORES_MCP_LOGGER_ENABLED=false en la configuración de tu servidor MCP.

2. Define stores con el logger adjunto (src/stores.ts):

import { atom, map, computed } from "nanostores";
import { initMcpLogger, attachMcpLogger } from "nanostores-mcp/mcpLogger";

// Automatically disabled in production (checks NODE_ENV / import.meta.env.DEV)
initMcpLogger();

// Stores
export const $count = atom(0);
export const $user = map({ name: "", role: "guest" });
export const $greeting = computed($user, user => `Hello, ${user.name}`);

// Attach logger — each call returns a cleanup function
attachMcpLogger($count, "$count");
attachMcpLogger($user, "$user");
attachMcpLogger($greeting, "$greeting");

3. Usa los stores normalmente — los eventos (montaje, desmontaje, cambio, acciones) se capturan automáticamente y se envían por lotes al servidor MCP cada segundo.

4. Pregunta a tu asistente de IA:

  • "¿Qué stores cambian con más frecuencia?" → nanostores_find_noisy_stores
  • "Muéstrame actividad reciente para $user" → nanostores_store_activity
  • "Dame un informe general de salud" → nanostores_runtime_overview

Opciones del Logger

initMcpLogger({
	url: "http://127.0.0.1:3999/nanostores-logger", // default; change if using a custom port
	batchMs: 1000, // default; lower for faster delivery (e.g. 200)
	projectRoot: "/absolute/path/to/project", // link runtime events with static analysis

	// Mask sensitive data — return null to skip event entirely
	maskEvent: event => {
		if (event.storeName === "authToken") return null;
		return event;
	},
});

Vaciar Antes del Apagado

import { getMcpLogger } from "nanostores-mcp/mcpLogger";

window.addEventListener("beforeunload", async () => {
	await getMcpLogger()?.forceFlush();
});

Lectura de Resultados

Resumen de salud nanostores_runtime_overview

La vista general agrupa los stores en tres categorías:

  • Stores más activos — ordenados por recuento total de eventos (cambios + acciones). Un store que aparece aquí con cientos de cambios en segundos puede ser un problema de rendimiento.
  • Stores propensos a errores — stores con eventos action-error. Recuentos altos de errores indican acciones asíncronas fallidas.
  • Stores desmontados — stores vistos en el montaje pero nunca desmontados. Pueden indicar fugas de memoria.

nanostores_runtime_coverage

Compara tu grafo de stores estático con los eventos de tiempo de ejecución observados:

TérminoSignificado
solo-estáticoStore encontrado por escaneo AST pero sin eventos de tiempo de ejecución observados. Posible código muerto, inicialización diferida o llamada a attachMcpLogger faltante.
solo-tiempo-de-ejecuciónEventos recibidos para un store no encontrado por el escáner. Común para stores creados dinámicamente, patrones de fábrica o stores en node_modules.
Cobertura por tipoP. ej. atom: 3/5 (60%) — 3 de 5 stores atom recibieron eventos de tiempo de ejecución. 0% para un tipo generalmente significa que attachMcpLogger no se llamó para esos stores.

nanostores_find_noisy_stores

Devuelve stores clasificados por actividad total (cambios + acciones combinados) dentro del período windowMs. Un store se considera "ruidoso" cuando su frecuencia de cambios es desproporcionadamente alta en relación con las actualizaciones visibles de la interfaz — usa esto para encontrar puntos calientes de re-renderizado o cadenas computadas inestables.

Privacidad y Seguridad

El logger de tiempo de ejecución está diseñado para permanecer en tu máquina local:

  • Vinculación solo de bucle local — el puente HTTP acepta conexiones exclusivamente desde 127.0.0.1, localhost o ::1. La vinculación a 0.0.0.0 está explícitamente bloqueada. Los datos nunca salen de tu máquina.
  • Qué se transmite — desde tu aplicación al servidor MCP a través de localhost: nombre del store, marca de tiempo, tipo de evento y, opcionalmente, instantáneas de valores (truncadas a 200 caracteres). Nada se envía a Anthropic ni a terceros.
  • Nada se persiste — los eventos se mantienen en un búfer circular (máximo 5 000 eventos) en la memoria del proceso y se descartan cuando el servidor se reinicia.
  • Enmascara datos sensibles — usa maskEvent para filtrar o redactar eventos en el lado del cliente antes de que se envíen por lotes:
initMcpLogger({
	maskEvent: event => {
		if (event.storeName === "$authToken") return null; // drop entirely
		if (event.storeName === "$paymentInfo") return { ...event, newValue: undefined }; // strip value
		return event;
	},
});
  • CORS — el puente rechaza solicitudes de origen cruzado desde orígenes que no sean de bucle local.

Consultas de Ejemplo

Haz preguntas en lenguaje natural a tu asistente de IA:

Análisis Estático:

  • "Analiza mi arquitectura de stores en busca de problemas potenciales"
  • "¿Qué sucede cuando $user cambia? Muestra suscriptores y stores derivados"

Depuración de Tiempo de Ejecución:

  • "¿Qué stores se actualizan con más frecuencia?"
  • "¿Hay stores declarados en el código pero nunca usados en tiempo de ejecución?"
  • "Depura el store $user — combina análisis estático con comportamiento de tiempo de ejecución"

Con Playwright MCP:

  • "Abre mi aplicación en el navegador, interactúa con ella y analiza qué stores causan más recálculos"

Documentación:

  • "¿Cómo uso stores computados?"
  • "Muéstrame mejores prácticas para stores persistentes"

Arquitectura

┌──────────────────────┐
│   Your Application   │
│                      │
│  @nanostores/logger  │
│        events        │
└──────────┬───────────┘
           │ HTTP POST (localhost:3999)
           ▼
┌──────────────────────┐
│   nanostores-mcp     │
│                      │
│   ┌──────────────┐   │
│   │ Logger Bridge │   │ ← HTTP server for runtime events
│   └──────┬───────┘   │
│          ▼           │
│   ┌──────────────┐   │
│   │ Event Store  │   │ ← Ring buffer (5000 events) + stats
│   └──────┬───────┘   │
│          │           │
│   ┌──────┴───────┐   │
│   │  AST Scanner │   │ ← ts-morph static analysis
│   └──────┬───────┘   │
│          │           │
│   ┌──────┴───────┐   │
│   │  Docs Index  │   │ ← Auto-detected from node_modules
│   └──────┬───────┘   │
│          │           │
│   ┌──────┴───────┐   │
│   │ MCP Interface│   │ ← Resources, Tools, Prompts
│   └──────────────┘   │
└──────────┬───────────┘
           │ MCP Protocol (stdio)
           ▼
┌──────────────────────┐
│    LLM Client        │
│ (Claude, VS Code, …) │
└──────────────────────┘

Limitaciones y Advertencias

Multi-raíz: mismo nombre de store en múltiples proyectos

En modo multi-raíz, un store llamado $user puede existir en dos proyectos diferentes. El almacén de eventos de tiempo de ejecución usa una clave compuesta (projectRoot + storeName) para mantenerlos separados, pero las vistas de resumen pueden mostrar el mismo nombre dos veces sin etiqueta de proyecto. Siempre especifica projectRoot al consultar herramientas en una configuración multi-raíz para obtener resultados inequívocos.

El análisis estático solo cubre archivos descubiertos

El escáner AST sigue las importaciones de TypeScript/JavaScript desde tu raíz de proyecto. Los stores creados dinámicamente en tiempo de ejecución, generados por fábricas o ubicados en node_modules no aparecerán en los resultados estáticos — pueden mostrarse como "solo-tiempo-de-ejecución" en los informes de cobertura.

El análisis de Vue y Svelte requiere dependencias opcionales

Si @vue/compiler-sfc o svelte no están instalados, los archivos .vue / .svelte se omiten silenciosamente durante el escaneo. Instálalos como dependencias de desarrollo si deseas cobertura completa para esos tipos de archivos.

El búfer circular de eventos está limitado a 5 000 eventos

Los eventos más antiguos se descartan cuando el búfer está lleno. Para stores de alta frecuencia usa windowMs para limitar tus consultas a datos recientes, o reduce batchMs en initMcpLogger para entregar eventos con más frecuencia y reducir la posibilidad de desbordamiento del búfer durante ráfagas.

radius en stores hub puede ser muy grande

Los stores con muchas dependencias (puntuación hub > 5) pueden devolver la mayor parte del grafo del proyecto en radius=2. Comienza con radius=1 y aumenta solo si necesitas un contexto más amplio.

Desarrollo

git clone https://github.com/Valyay/nanostores-mcp.git
cd nanostores-mcp
pnpm install

pnpm dev          # Run dev server
pnpm build        # TypeScript compile
pnpm test         # Run vitest
pnpm lint         # ESLint
pnpm check        # All checks: lint + format + test + build

# Test with MCP Inspector
npx @modelcontextprotocol/inspector pnpm run dev

Solución de Problemas

El logger no recibe eventos:

  1. Usa la herramienta ping para verificar que el puente del logger esté habilitado y en ejecución
  2. Revisa la consola del navegador para ver advertencias de [nanostores-mcp] sobre problemas de conexión
  3. Confirma que el puerto coincida entre el servidor (NANOSTORES_MCP_LOGGER_PORT) y la URL del cliente
  4. Prueba con un store atom simple para verificar que los eventos fluyan

Conflictos de puertos:

# Change server port
NANOSTORES_MCP_LOGGER_PORT=4000 npx nanostores-mcp

# Update client
initMcpLogger({ url: "http://127.0.0.1:4000/nanostores-logger" });

Errores de TypeScript:

// Import from the mcpLogger subpath export
import { initMcpLogger, attachMcpLogger } from "nanostores-mcp/mcpLogger";

Documentación no encontrada:

  • El servidor detecta automáticamente la documentación desde nanostores en tu node_modules
  • Asegúrate de que nanostores esté instalado: npm install nanostores
  • O establece NANOSTORES_DOCS_ROOT para apuntar a un directorio de documentación manualmente

Proyectos Relacionados

Ecosistema Nanostores:

MCP:

Licencia

MIT

Contribuciones

¡Las contribuciones son bienvenidas! Por favor, abre un issue o un PR.