Nano Stores MCP

Model Context Protocol server for Nanostores — analyze, debug and monitor

your nanostores in AI assistants like Claude Desktop.

• 📊 Static Analysis: AST-based project scanning, dependency graphs, store inspection
• 🔥 Runtime Monitoring: Live events from `@nanostores/logger`, performance metrics, activity tracking
• 📚 Documentation: Search and browse Nanostores docs by topic or store kind
• 🎯 Zero Config: Works out of the box — auto-detects project roots and nanostores docs
• 🌐 Framework-Agnostic: Works with React, Vue, Svelte, Angular, Solid, Preact, Lit — any framework that uses Nanostores

npx nanostores-mcp

Ask your AI: _"Analyze my store architecture"_ or _"Which stores update most frequently?"_

Made at , product consulting for developer tools.

Table of Contents

• Features
• Requirements
• Installation
• Configuration
• Quick Start
• MCP Interface
  • Resources
  • Tools
  • Advanced Tool Arguments
  • Prompts
• Runtime Monitoring
  • Reading Results
  • Privacy & Security
• Example Queries
• Architecture
• Limitations & Caveats
• Development
• Troubleshooting

Features

📊 Static Analysis (AST-based)

Understand your nanostores architecture without running your app:

• Project scanning — find all stores, subscribers, and import/export relationships
• Dependency graph — visualize how stores depend on each other (Mermaid diagrams)
• Store inspection — type (atom/map/computed/batched/persistentAtom/persistentMap/router), location, usage patterns, related files
• Framework-aware subscriber detection — recognizes `.subscribe()` / `.listen()` calls and component bindings across React, Vue, Svelte, and Angular
• Vue SFC support — parses both `` and `` blocks in `.vue` files (requires `@vue/compiler-sfc`)
• Svelte support — parses `` and instance `` blocks, auto-subscriptions (`$storeName` in templates), and filters out Svelte 5 runes (`$state`, `$derived`, `$effect`, etc.) so they are not mistaken for store references (requires `svelte`)
• Angular DI support — resolves `@nanostores/angular` `NanostoresService` constructor injections and detects `this.nanostores.useStore(...)` call patterns in TypeScript component files

🔥 Runtime Monitoring (Logger Integration)

Real-time insights into your running application:

• Live event capture — mount/unmount, value changes, action calls from `@nanostores/logger`
• Performance analysis — find noisy stores, high error rates, performance bottlenecks
• Activity metrics — change frequency, action success/failure rates, action duration
• Combined analysis — merge static structure with runtime behavior for deep debugging

📚 Documentation Search

Search and browse Nanostores documentation directly from your AI assistant:

• Full-text search — find guides, API references, and best practices by query
• Store-kind lookup — get docs relevant to a specific store type (atom, map, computed, etc.)
• Auto-detection — picks up docs from `nanostores` in your `node_modules` automatically

Requirements

Required peer dependency (for static analysis):

npm install nanostores

Optional peer dependencies — install only if you use the corresponding file format:

Without these optional packages the server still works — it silently skips unsupported file types.

Installation

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

Or run directly without installation:

npx nanostores-mcp

Configuration

Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%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

Requires GitHub Copilot extension (VS Code 1.99+). Create `.vscode/mcp.json` in your project:

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

Tools are available in Copilot's Agent mode (select "Agent" in the Copilot Chat dropdown).

Cursor

Create `.cursor/mcp.json` in your project root (or `~/.cursor/mcp.json` for global):

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

Zed

Add to your Zed `settings.json`:

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

The server appears in Zed's Agent Panel settings.

Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

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

You can also open this file from the MCP icon in the Cascade panel → "Configure".

Claude Code

Add via CLI:

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

Or create `.mcp.json` in your project root (shared with the team):

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

Environment Variables

How the Project Root Is Resolved

The server picks workspace roots in priority order:

1. Environment variables (highest priority) — `NANOSTORES_MCP_ROOTS` / `NANOSTORES_MCP_ROOT` / `WORKSPACE_FOLDER_PATHS` / `WORKSPACE_FOLDER`

2. Client roots — roots reported by the MCP client via the `roots/list` capability (set automatically by some editors)

3. Current working directory — `process.cwd()` used as fallback when neither env nor client roots are configured

When a tool is called without an explicit `projectRoot` argument the server uses the first configured root. In a multi-root setup always pass `projectRoot` to avoid ambiguity.

Quick Start

1. Static Analysis

Works out of the box — just point at your project and ask:

• _"Analyze my store architecture"_
• _"Explain how nanostores is used in this project"_
• _"Give me a summary of the $cart store"_
• _"My stores changed — re-scan the project"_ ← the AI will force a fresh scan

2. Documentation Search

Auto-detected from `nanostores` in your `node_modules`:

• _"How do I use computed stores?"_
• _"Show me the docs for persistentAtom"_

3. Runtime Monitoring (Optional)

Requires logger integration in your app. See Runtime Monitoring below.

• _"Which stores update most frequently?"_
• _"Show me recent activity for $user"_
• _"Give me an overall health report"_

Verify Your Setup

Run these four tools in order to confirm everything is working:

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)

If `nanostores_scan_project` returns zero stores, check that `NANOSTORES_MCP_ROOT` points to the correct project directory.

MCP Interface

MCP Resources

MCP Tools

Static Analysis

Runtime Monitoring

Documentation

Use `nanostores://docs/page/{id}` resource to read the full content of pages returned by search.

Utilities

MCP Prompts

Advanced Tool Arguments

Most tools accept these optional arguments that significantly change their behavior:

Runtime Monitoring

For runtime analysis, integrate the MCP Logger client into your application.

1. Install in your app and enable the logger bridge:

npm install nanostores-mcp

The logger bridge starts automatically — no extra config needed. To disable it, set `NANOSTORES_MCP_LOGGER_ENABLED=false` in your MCP server config.

2. Define stores with logger attached (`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 stores normally — events (mount, unmount, change, actions) are captured automatically and batched to the MCP server every second.

4. Ask your AI assistant:

• _"Which stores change most frequently?"_ → `nanostores_find_noisy_stores`
• _"Show me recent activity for $user"_ → `nanostores_store_activity`
• _"Give me an overall health report"_ → `nanostores_runtime_overview`

Logger Options

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;
	},
});

Flush Before Shutdown

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

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

Reading Results

`nanostores_runtime_overview` health summary

The overview groups stores into three categories:

• Top active stores — sorted by total event count (changes + actions). A store that appears here with hundreds of changes in seconds may be a performance concern.
• Error-prone stores — stores with `action-error` events. High error counts indicate failing async actions.
• Unmounted stores — stores seen at mount but never unmounted. May indicate memory leaks.

`nanostores_runtime_coverage`

Compares your static store graph against observed runtime events:

`nanostores_find_noisy_stores`

Returns stores ranked by total activity (changes + actions combined) within the `windowMs` period. A store is considered "noisy" when its change frequency is disproportionately high relative to visible UI updates — use this to find re-render hotspots or thrashing computed chains.

Privacy & Security

The runtime logger is designed to stay on your local machine:

• Loopback-only binding — the HTTP bridge accepts connections exclusively from `127.0.0.1`, `localhost`, or `::1`. Binding to `0.0.0.0` is explicitly blocked. Data never leaves your machine.
• What is transmitted — from your app to the MCP server over localhost: store name, timestamp, event kind, and optionally value snapshots (truncated to 200 characters). Nothing is sent to Anthropic or any third party.
• Nothing is persisted — events are held in a ring buffer (5 000 events max) in process memory and discarded when the server restarts.
• Mask sensitive data — use `maskEvent` to filter or redact events client-side before they are batched and sent:

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

• CORS — the bridge rejects cross-origin requests from non-loopback origins.

Example Queries

Ask your AI assistant natural language questions:

Static Analysis:

• _"Analyze my store architecture for potential issues"_
• _"What happens when $user changes? Show subscribers and derived stores"_

Runtime Debugging:

• _"Which stores update most frequently?"_
• _"Are there stores declared in code but never used at runtime?"_
• _"Debug the $user store — combine static analysis with runtime behavior"_

**With Playwright MCP:**

• _"Open my app in the browser, interact with it, and analyze which stores cause the most recalculations"_

Documentation:

• _"How do I use computed stores?"_
• _"Show me best practices for persistent stores"_

Architecture

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

Limitations & Caveats

Multi-root: same store name in multiple projects

In multi-root mode a store named `$user` can exist in two different projects. The runtime event store uses a composite key (`projectRoot + storeName`) to keep them separate, but summary views may show the same name twice with no project label. Always specify `projectRoot` when querying tools in a multi-root setup to get unambiguous results.

Static analysis only covers discovered files

The AST scanner follows TypeScript/JavaScript imports from your project root. Stores created dynamically at runtime, generated by factories, or living in `node_modules` will not appear in static results — they may show up as "runtime-only" in coverage reports.

Vue and Svelte parsing requires optional dependencies

If `@vue/compiler-sfc` or `svelte` are not installed, `.vue` / `.svelte` files are silently skipped during scanning. Install them as dev dependencies if you want full coverage for those file types.

Event ring buffer is capped at 5 000 events

Older events are dropped when the buffer is full. For high-frequency stores use `windowMs` to narrow your queries to recent data, or lower `batchMs` in `initMcpLogger` to deliver events more frequently and reduce the chance of buffer overflow during bursts.

`radius` on hub stores can be very large

Stores with many dependencies (hub score > 5) can return most of the project graph at `radius=2`. Start with `radius=1` and increase only if you need broader context.

Development

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

Troubleshooting

Logger not receiving events:

1. Use the `ping` tool to verify logger bridge is enabled and running

2. Check browser console for `[nanostores-mcp]` warnings about connection issues

3. Confirm the port matches between server (`NANOSTORES_MCP_LOGGER_PORT`) and client URL

4. Test with a simple atom store to verify events flow

Port conflicts:

# Change server port
NANOSTORES_MCP_LOGGER_PORT=4000 npx nanostores-mcp

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

TypeScript errors:

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

Documentation not found:

• The server auto-detects docs from `nanostores` in your `node_modules`
• Make sure `nanostores` is installed: `npm install nanostores`
• Or set `NANOSTORES_DOCS_ROOT` to point at a docs directory manually

Related Projects

Nanostores ecosystem:

• nanostores — Tiny state manager (atom, map, computed, batched, deepMap)
• @nanostores/logger — Logger and action system
• @nanostores/persistent — Persistent stores (localStorage, sessionStorage)
• @nanostores/router — SPA router
• @nanostores/i18n — Internationalization
• @nanostores/react, @nanostores/vue, @nanostores/preact, @nanostores/solid, @nanostores/lit — Framework bindings

MCP:

• Model Context Protocol — MCP specification
• Playwright MCP — Browser automation (works with nanostores-mcp for runtime analysis)

License

MIT

Contributing

Contributions are welcome! Please open an issue or PR.