Nanostores MCP

Servidor MCP para a biblioteca Nanostores

Documentação

Nano Stores MCP

Servidor de Model Context Protocol para Nanostores — analise, depure e monitore seus nanostores em assistentes de IA como o Claude Desktop.

📊 Análise Estática: Varredura de projetos baseada em AST, gráficos de dependência, inspeção de stores
🔥 Monitoramento em Tempo Real: Eventos ao vivo do @nanostores/logger, métricas de desempenho, rastreamento de atividade
📚 Documentação: Pesquise e navegue pela documentação do Nanostores por tópico ou tipo de store
🎯 Zero Configuração: Funciona imediatamente — detecta automaticamente raízes de projetos e documentação do nanostores
🌐 Agnóstico de Framework: Funciona com React, Vue, Svelte, Angular, Solid, Preact, Lit — qualquer framework que use Nanostores

npx nanostores-mcp

Pergunte à sua IA: "Analise minha arquitetura de stores" ou "Quais stores são atualizadas com mais frequência?"

Feito na Evil Martians, consultoria de produtos para ferramentas de desenvolvimento.

Sumário

Recursos
Requisitos
Instalação
Configuração
Início Rápido
Interface MCP
Monitoramento em Tempo Real
- Leitura de Resultados
- Privacidade e Segurança
Exemplos de Consultas
Arquitetura
Limitações e Ressalvas
Desenvolvimento
Solução de Problemas

Recursos

📊 Análise Estática (baseada em AST)

Entenda sua arquitetura de nanostores sem executar seu aplicativo:

Varredura de projetos — encontre todos os stores, assinantes e relações de importação/exportação
Gráfico de dependências — visualize como os stores dependem uns dos outros (diagramas Mermaid)
Inspeção de stores — tipo (atom/map/computed/batched/persistentAtom/persistentMap/router), localização, padrões de uso, arquivos relacionados
Detecção de assinantes ciente de framework — reconhece chamadas .subscribe() / .listen() e vínculos de componentes em React, Vue, Svelte e Angular
Suporte a Vue SFC — analisa blocos <script> e <script setup> em arquivos .vue (requer @vue/compiler-sfc)
Suporte a Svelte — analisa blocos <script context="module"> e de instância <script>, assinaturas automáticas ($storeName em templates) e filtra runes do Svelte 5 ($state, $derived, $effect, etc.) para que não sejam confundidos com referências de stores (requer svelte)
Suporte a DI do Angular — resolve injeções de construtor @nanostores/angular NanostoresService e detecta padrões de chamada this.nanostores.useStore(...) em arquivos TypeScript de componentes

🔥 Monitoramento em Tempo Real (Integração com Logger)

Insights em tempo real sobre seu aplicativo em execução:

Captura de eventos ao vivo — montagem/desmontagem, mudanças de valor, chamadas de ação do @nanostores/logger
Análise de desempenho — encontre stores ruidosos, altas taxas de erro, gargalos de desempenho
Métricas de atividade — frequência de mudanças, taxas de sucesso/falha de ações, duração de ações
Análise combinada — mescle estrutura estática com comportamento em tempo real para depuração profunda

📚 Pesquisa de Documentação

Pesquise e navegue pela documentação do Nanostores diretamente do seu assistente de IA:

Pesquisa de texto completo — encontre guias, referências de API e melhores práticas por consulta
Consulta por tipo de store — obtenha documentação relevante para um tipo específico de store (atom, map, computed, etc.)
Detecção automática — capta documentação de nanostores no seu node_modules automaticamente

Requisitos

Requisito	Versão
Node.js	`^20.0.0 \|\| >=22.0.0`

Dependência de pares obrigatória (para análise estática):

npm install nanostores

Dependências de pares opcionais — instale apenas se usar o formato de arquivo correspondente:

Pacote	Quando necessário
`@vue/compiler-sfc`	Varredura de arquivos Vue SFC (`.vue`)
`svelte`	Varredura de arquivos Svelte (`.svelte`)
`@nanostores/logger`	Monitoramento em tempo real (`attachMcpLogger`)

Sem esses pacotes opcionais, o servidor ainda funciona — ele simplesmente ignora silenciosamente tipos de arquivo não suportados.

Instalação

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

Ou execute diretamente sem instalação:

npx nanostores-mcp

Configuração

Claude Desktop

Adicione ao ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %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

Requer a extensão GitHub Copilot (VS Code 1.99+). Crie .vscode/mcp.json no seu projeto:

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

As ferramentas estão disponíveis no modo Agente do Copilot (selecione "Agente" no menu suspenso do Copilot Chat).

Cursor

Crie .cursor/mcp.json na raiz do seu projeto (ou ~/.cursor/mcp.json para global):

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

Zed

Adicione ao seu settings.json do Zed:

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

O servidor aparece nas configurações do Painel de Agente do Zed.

Windsurf

Adicione ao ~/.codeium/windsurf/mcp_config.json:

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

Você também pode abrir este arquivo pelo ícone MCP no painel Cascade → "Configurar".

Claude Code

Adicione via CLI:

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

Ou crie .mcp.json na raiz do seu projeto (compartilhado com a equipe):

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

Variáveis de Ambiente

Variável	Padrão	Descrição
`NANOSTORES_MCP_ROOT`	cwd	Caminho da raiz do projeto
`NANOSTORES_MCP_ROOTS`	—	Raízes delimitadas por plataforma (`:` no Unix, `;` no Windows) para configuração de múltiplos projetos
`WORKSPACE_FOLDER`	—	Alias para `NANOSTORES_MCP_ROOT` — definido automaticamente pelo VS Code e alguns editores
`WORKSPACE_FOLDER_PATHS`	—	Alias para `NANOSTORES_MCP_ROOTS` — definido automaticamente por alguns editores
`NANOSTORES_MCP_LOGGER_ENABLED`	`true`	Defina como `false` ou `0` para desativar a coleta de eventos em tempo real e a ponte do logger
`NANOSTORES_MCP_LOGGER_PORT`	`3999`	Porta HTTP para a ponte do logger
`NANOSTORES_MCP_LOGGER_HOST`	`127.0.0.1`	Host para vincular. Valores permitidos: `127.0.0.1`, `localhost`, `::1`
`NANOSTORES_DOCS_ROOT`	detecção automática	Caminho para o diretório de documentação
`NANOSTORES_DOCS_PATTERNS`	`*/.md`	Padrões glob separados por vírgula para documentação

Como a Raiz do Projeto é Resolvida

O servidor escolhe as raízes do workspace em ordem de prioridade:

Variáveis de ambiente (maior prioridade) — NANOSTORES_MCP_ROOTS / NANOSTORES_MCP_ROOT / WORKSPACE_FOLDER_PATHS / WORKSPACE_FOLDER
Raízes do cliente — raízes relatadas pelo cliente MCP via capacidade roots/list (definidas automaticamente por alguns editores)
Diretório de trabalho atual — process.cwd() usado como fallback quando nem env nem raízes do cliente estão configurados

Quando uma ferramenta é chamada sem um argumento projectRoot explícito, o servidor usa a primeira raiz configurada. Em uma configuração de múltiplas raízes, sempre passe projectRoot para evitar ambiguidade.

Início Rápido

1. Análise Estática

Funciona imediatamente — basta apontar para o seu projeto e perguntar:

"Analise minha arquitetura de stores"
"Explique como o nanostores é usado neste projeto"
"Dê-me um resumo do store $cart"
"Meus stores mudaram — reescaneie o projeto" ← a IA forçará uma nova varredura

2. Pesquisa de Documentação

Detectada automaticamente de nanostores no seu node_modules:

"Como uso stores computed?"
"Mostre-me a documentação para persistentAtom"

3. Monitoramento em Tempo Real (Opcional)

Requer integração do logger no seu aplicativo. Veja Monitoramento em Tempo Real abaixo.

"Quais stores são atualizadas com mais frequência?"
"Mostre-me atividade recente para $user"
"Dê-me um relatório geral de saúde"

Verifique Sua Configuração

Execute estas quatro ferramentas em ordem para confirmar que tudo está funcionando:

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)

Se nanostores_scan_project retornar zero stores, verifique se NANOSTORES_MCP_ROOT aponta para o diretório correto do projeto.

Interface MCP

Recursos MCP

Recurso	Descrição
`nanostores://graph`	Gráfico de dependências completo (texto + Mermaid)
`nanostores://store/{key}`	Detalhes do store por nome ou id
`nanostores://docs`	Índice de documentação — todas as páginas e tags
`nanostores://docs/page/{id}`	Conteúdo completo de uma página de documentação

Ferramentas MCP

Análise Estática

Ferramenta	Descrição
`nanostores_scan_project`	Escaneie o projeto em busca de todos os stores, assinantes e dependências
`nanostores_store_summary`	Resumo detalhado de um store específico
`nanostores_project_outline`	Visão geral de alto nível: tipos de stores, diretórios principais, stores centrais
`nanostores_store_subgraph`	Vizinhança de dependência expandida por BFS de um store
`nanostores_store_impact`	Cadeia causal downstream — o que recalcula/re-renderiza se X mudar

Monitoramento em Tempo Real

Ferramenta	Descrição
`nanostores_runtime_overview`	Relatório geral de saúde com estatísticas para todos os stores
`nanostores_store_activity`	Linha do tempo de atividade para um store específico (filtrável por tipo/ação)
`nanostores_find_noisy_stores`	Identifique stores com alta frequência de mudanças ou altas taxas de erro
`nanostores_runtime_coverage`	Compare o gráfico estático com eventos em tempo real para encontrar lacunas de cobertura

Documentação

Ferramenta	Descrição
`nanostores_docs_search`	Pesquise documentação por `query` (texto completo), `storeKind` (atom, map, computed, persistentAtom, etc.) ou ambos. Opcional: `limit` (padrão 10), `tags`

Use o recurso nanostores://docs/page/{id} para ler o conteúdo completo das páginas retornadas pela pesquisa.

Utilitários

Ferramenta	Descrição
`nanostores_ping`	Verificação de saúde do servidor e status da ponte do logger
`nanostores_clear_cache`	Limpe o cache do índice do projeto para forçar uma nova varredura

Prompts MCP

Prompt	Parâmetros	Descrição
`explain-project`	`focus` (opcional)	Explicação guiada por IA da arquitetura de stores do seu projeto. `focus` restringe a um recurso/domínio (ex.: `"cart"`, `"auth"`)
`explain-store`	`store_name` (obrigatório)	Análise aprofundada da implementação e uso de um store específico
`debug-store`	`store_name` (obrigatório)	Análise abrangente combinando dados estáticos + de runtime
`debug-project-activity`	—	Análise de desempenho do projeto e otimização
`docs-how-to`	`task` (obrigatório)	Orientação passo a passo para uma tarefa com Nanostores, apoiada pela documentação (ex.: `"How do I sync a map store to localStorage?"`)

Argumentos Avançados das Ferramentas

A maioria das ferramentas aceita estes argumentos opcionais que alteram significativamente seu comportamento:

Argumento	Tipo	Usado em	Descrição
`storeId`	`string`	`store_summary`, `store_subgraph`, `store_impact`	Identificador exato do store — formato: `store:src/stores.ts#$counterName`. Tem prioridade sobre `name` quando ambos são fornecidos.
`name`	`string`	`store_summary`, `store_subgraph`, `store_impact`	Nome do store (ex.: `"$user"`). Usado quando `storeId` não é fornecido.
`radius`	`number` (0–10, padrão `2`)	`nanostores_store_subgraph`	Saltos BFS ao redor do store. `1` = apenas dependências diretas; `2` = dependências das dependências. Aviso: em stores hub altamente conectados (pontuação de hub > 5), raio ≥ 2 pode retornar a maior parte do projeto — comece com `1`.
`projectRoot`	`string`	a maioria das ferramentas	Qual raiz do projeto analisar em configurações multi-raiz. Omita para usar a primeira raiz configurada. Sempre especifique em projetos multi-raiz.
`windowMs`	`number`	`store_activity`, `find_noisy_stores`, `runtime_overview`	Janela de retrospectiva em milissegundos (ex.: `60000` = últimos 60 s). Filtra eventos para esse intervalo de tempo.
`kinds`	`string[]`	`nanostores_store_activity`	Filtra eventos por tipo. Valores: `"mount"`, `"unmount"`, `"change"`, `"action-start"`, `"action-end"`, `"action-error"`.
`actionName`	`string`	`nanostores_store_activity`	Filtra eventos para uma ação específica (ex.: `"increment"`).
`compact`	`boolean`	`scan_project`, `find_noisy_stores`, `runtime_overview`	Retorna uma tabela compacta e eficiente em tokens em vez de texto completo. Útil para projetos grandes para reduzir o uso de contexto.

Monitoramento de Runtime

Para análise de runtime, integre o cliente MCP Logger ao seu aplicativo.

1. Instale no seu aplicativo e habilite a ponte do logger:

npm install nanostores-mcp

A ponte do logger inicia automaticamente — nenhuma configuração extra é necessária. Para desativá-la, defina NANOSTORES_MCP_LOGGER_ENABLED=false na configuração do seu servidor MCP.

2. Defina stores com logger anexado (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. Use os stores normalmente — eventos (mount, unmount, change, actions) são capturados automaticamente e enviados em lote ao servidor MCP a cada segundo.

4. Pergunte ao seu assistente de IA:

"Quais stores mudam com mais frequência?" → nanostores_find_noisy_stores
"Mostre atividade recente para $user" → nanostores_store_activity
"Dê-me um relatório geral de saúde" → nanostores_runtime_overview

Opções do 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;
	},
});

Liberar Antes do Encerramento

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

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

Leitura dos Resultados

Resumo de saúde nanostores_runtime_overview

A visão geral agrupa os stores em três categorias:

Stores mais ativos — ordenados por contagem total de eventos (changes + actions). Um store que aparece aqui com centenas de mudanças em segundos pode ser uma preocupação de desempenho.
Stores propensos a erros — stores com eventos action-error. Contagens altas de erros indicam ações assíncronas com falha.
Stores não desmontados — stores vistos no mount, mas nunca desmontados. Podem indicar vazamentos de memória.

nanostores_runtime_coverage

Compara seu grafo estático de stores com os eventos de runtime observados:

Termo	Significado
somente estático	Store encontrado pela varredura AST, mas sem eventos de runtime observados. Possível código morto, inicialização adiada ou chamada `attachMcpLogger` ausente.
somente runtime	Eventos recebidos para um store não encontrado pelo scanner. Comum para stores criados dinamicamente, padrões de fábrica ou stores em `node_modules`.
Cobertura por tipo	Ex.: `atom: 3/5 (60%)` — 3 de 5 stores atom receberam eventos de runtime. 0% para um tipo geralmente significa que `attachMcpLogger` não foi chamado para esses stores.

nanostores_find_noisy_stores

Retorna stores classificados por atividade total (changes + actions combinados) dentro do período windowMs. Um store é considerado "ruidoso" quando sua frequência de mudanças é desproporcionalmente alta em relação às atualizações visíveis da interface — use isso para encontrar pontos de re-renderização ou cadeias computadas instáveis.

Privacidade e Segurança

O logger de runtime foi projetado para permanecer na sua máquina local:

Vinculação somente em loopback — a ponte HTTP aceita conexões exclusivamente de 127.0.0.1, localhost ou ::1. A vinculação a 0.0.0.0 é explicitamente bloqueada. Os dados nunca saem da sua máquina.
O que é transmitido — do seu aplicativo para o servidor MCP via localhost: nome do store, timestamp, tipo de evento e, opcionalmente, snapshots de valores (truncados em 200 caracteres). Nada é enviado à Anthropic ou a terceiros.
Nada é persistido — os eventos são mantidos em um buffer circular (máximo de 5 000 eventos) na memória do processo e descartados quando o servidor reinicia.
Mascare dados sensíveis — use maskEvent para filtrar ou mascarar eventos no lado do cliente antes de serem enviados em lote:

initMcpLogger({
	maskEvent: event => {
		if (event.storeName === "$authToken") return null; // drop entirely
		if (event.storeName === "$paymentInfo") return { ...event, newValue: undefined }; // strip value
		return event;
	},
});

CORS — a ponte rejeita solicitações de origens cruzadas que não sejam de loopback.

Exemplos de Consultas

Faça perguntas em linguagem natural ao seu assistente de IA:

Análise Estática:

"Analise minha arquitetura de stores em busca de problemas potenciais"
"O que acontece quando $user muda? Mostre assinantes e stores derivados"

Depuração de Runtime:

"Quais stores atualizam com mais frequência?"
"Existem stores declarados no código, mas nunca usados em runtime?"
"Depure o store $user — combine análise estática com comportamento de runtime"

Com Playwright MCP:

"Abra meu aplicativo no navegador, interaja com ele e analise quais stores causam mais recálculos"

Documentação:

"Como uso stores computados?"
"Mostre-me boas práticas para stores persistentes"

Arquitetura

┌──────────────────────┐
│   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, …) │
└──────────────────────┘

Limitações e Ressalvas

Multi-raiz: mesmo nome de store em vários projetos

No modo multi-raiz, um store chamado $user pode existir em dois projetos diferentes. O armazenamento de eventos de runtime usa uma chave composta (projectRoot + storeName) para mantê-los separados, mas as visualizações de resumo podem mostrar o mesmo nome duas vezes sem rótulo de projeto. Sempre especifique projectRoot ao consultar ferramentas em uma configuração multi-raiz para obter resultados inequívocos.

A análise estática cobre apenas arquivos descobertos

O scanner AST segue importações TypeScript/JavaScript a partir da raiz do seu projeto. Stores criados dinamicamente em runtime, gerados por fábricas ou localizados em node_modules não aparecerão nos resultados estáticos — eles podem aparecer como "somente runtime" nos relatórios de cobertura.

A análise de Vue e Svelte requer dependências opcionais

Se @vue/compiler-sfc ou svelte não estiverem instalados, os arquivos .vue / .svelte são silenciosamente ignorados durante a varredura. Instale-os como dependências de desenvolvimento se quiser cobertura completa para esses tipos de arquivo.

O buffer circular de eventos tem limite de 5 000 eventos

Eventos mais antigos são descartados quando o buffer está cheio. Para stores de alta frequência, use windowMs para restringir suas consultas a dados recentes, ou reduza batchMs em initMcpLogger para entregar eventos com mais frequência e reduzir a chance de estouro do buffer durante picos.

radius em stores hub pode ser muito grande

Stores com muitas dependências (pontuação de hub > 5) podem retornar a maior parte do grafo do projeto em radius=2. Comece com radius=1 e aumente somente se precisar de contexto mais amplo.

Desenvolvimento

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

Solução de Problemas

Logger não recebendo eventos:

Use a ferramenta ping para verificar se a ponte do logger está habilitada e em execução
Verifique o console do navegador para avisos [nanostores-mcp] sobre problemas de conexão
Confirme se a porta corresponde entre o servidor (NANOSTORES_MCP_LOGGER_PORT) e a URL do cliente
Teste com um store atom simples para verificar se os eventos fluem

Conflitos de porta:

# Change server port
NANOSTORES_MCP_LOGGER_PORT=4000 npx nanostores-mcp

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

Erros de TypeScript:

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

Documentação não encontrada:

O servidor detecta automaticamente a documentação de nanostores no seu node_modules
Certifique-se de que nanostores esteja instalado: npm install nanostores
Ou defina NANOSTORES_DOCS_ROOT para apontar para um diretório de documentação manualmente

Projetos Relacionados

Ecossistema Nanostores:

nanostores — Gerenciador de estado minúsculo (atom, map, computed, batched, deepMap)
@nanostores/logger — Sistema de logger e ações
@nanostores/persistent — Stores persistentes (localStorage, sessionStorage)
@nanostores/router — Roteador SPA
@nanostores/i18n — Internacionalização
@nanostores/react, @nanostores/vue, @nanostores/preact, @nanostores/solid, @nanostores/lit — Integrações com frameworks

MCP:

Model Context Protocol — especificação MCP
Playwright MCP — Automação de navegador (funciona com nanostores-mcp para análise em tempo de execução)

Licença

MIT

Contribuição

Contribuições são bem-vindas! Por favor, abra uma issue ou PR.