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 Evil Martians, 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 <script> and <script setup> blocks in .vue files (requires @vue/compiler-sfc)
• Svelte support — parses <script context="module"> and instance <script> 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

| Requirement | Version | | ----------- | ----------------------- | | Node.js | ^20.0.0 \|\| >=22.0.0 |

Required peer dependency (for static analysis):

npm install nanostores

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

| Package | When needed | | -------------------- | -------------------------------------- | | @vue/compiler-sfc | Vue SFC (.vue) file scanning | | svelte | Svelte (.svelte) file scanning | | @nanostores/logger | Runtime monitoring (attachMcpLogger) |

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

| Variable | Default | Description | | ------------------------------- | ----------- | ------------------------------------------------------------------------------- | | NANOSTORES_MCP_ROOT | cwd | Project root path | | NANOSTORES_MCP_ROOTS | — | Platform-delimited roots (: on Unix, ; on Windows) for multi-project setup | | WORKSPACE_FOLDER | — | Alias for NANOSTORES_MCP_ROOT — set automatically by VS Code and some editors | | WORKSPACE_FOLDER_PATHS | — | Alias for NANOSTORES_MCP_ROOTS — set automatically by some editors | | NANOSTORES_MCP_LOGGER_ENABLED | true | Set to false or 0 to disable runtime event collection and the logger bridge | | NANOSTORES_MCP_LOGGER_PORT | 3999 | HTTP port for logger bridge | | NANOSTORES_MCP_LOGGER_HOST | 127.0.0.1 | Host to bind. Allowed values: 127.0.0.1, localhost, ::1 | | NANOSTORES_DOCS_ROOT | auto-detect | Path to documentation directory | | NANOSTORES_DOCS_PATTERNS | **/*.md | Comma-separated glob patterns for docs |

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

| Resource | Description | | ----------------------------- | ---------------------------------------- | | nanostores://graph | Full dependency graph (text + Mermaid) | | nanostores://store/{key} | Store details by name or id | | nanostores://docs | Documentation index — all pages and tags | | nanostores://docs/page/{id} | Full content of a documentation page |

MCP Tools

Static Analysis

| Tool | Description | | ---------------------------- | ----------------------------------------------------------------- | | nanostores_scan_project | Scan project for all stores, subscribers, and dependencies | | nanostores_store_summary | Detailed summary of a specific store | | nanostores_project_outline | High-level overview: store kinds, top directories, hub stores | | nanostores_store_subgraph | BFS-expanded dependency neighborhood of a store | | nanostores_store_impact | Downstream causal chain — what recomputes/re-renders if X changes |

Runtime Monitoring

| Tool | Description | | ------------------------------ | ------------------------------------------------------------------ | | nanostores_runtime_overview | Overall health report with statistics for all stores | | nanostores_store_activity | Activity timeline for a specific store (filterable by kind/action) | | nanostores_find_noisy_stores | Identify stores with high change frequency or error rates | | nanostores_runtime_coverage | Compare static graph with runtime events to find coverage gaps |

Documentation

| Tool | Description | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | nanostores_docs_search | Search docs by query (full-text), storeKind (atom, map, computed, persistentAtom, etc.), or both. Optional: limit (default 10), tags |

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

Utilities

| Tool | Description | | ------------------------ | -------------------------------------------- | | nanostores_ping | Server health check and logger bridge status | | nanostores_clear_cache | Clear project index cache to force rescan |

MCP Prompts

| Prompt | Parameters | Description | | ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | explain-project | focus (optional) | AI-guided explanation of your project's store architecture. focus narrows to a feature/domain (e.g. "cart", "auth") | | explain-store | store_name (required) | Deep dive into a specific store's implementation and usage | | debug-store | store_name (required) | Comprehensive analysis combining static + runtime data | | debug-project-activity | — | Project-wide performance analysis and optimization | | docs-how-to | task (required) | Step-by-step guidance for a Nanostores task, backed by docs (e.g. "How do I sync a map store to localStorage?") |

Advanced Tool Arguments

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

| Argument | Type | Used in | Description | | ------------- | ---------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | storeId | string | store_summary, store_subgraph, store_impact | Exact store identifier — format: store:src/stores.ts#$counterName. Takes priority over name when both are provided. | | name | string | store_summary, store_subgraph, store_impact | Store name (e.g. "$user"). Used when storeId is not provided. | | radius | number (0–10, default 2) | nanostores_store_subgraph | BFS hops around the store. 1 = direct deps only; 2 = deps of deps. Warning: on highly-connected hub stores (hub score > 5) radius ≥ 2 may return most of the project — start with 1. | | projectRoot | string | most tools | Which project root to analyze in multi-root setups. Omit to use the first configured root. Always specify this in multi-root projects. | | windowMs | number | store_activity, find_noisy_stores, runtime_overview | Look-back window in milliseconds (e.g. 60000 = last 60 s). Filters events to that time range. | | kinds | string[] | nanostores_store_activity | Filter events by type. Values: "mount", "unmount", "change", "action-start", "action-end", "action-error". | | actionName | string | nanostores_store_activity | Filter events to a specific action (e.g. "increment"). | | compact | boolean | scan_project, find_noisy_stores, runtime_overview | Return a compressed token-efficient table instead of full text. Useful for large projects to reduce context usage. |

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:

| Term | Meaning | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | static-only | Store found by AST scan but no runtime events observed. Possible dead code, deferred initialization, or missing attachMcpLogger call. | | runtime-only | Events received for a store not found by the scanner. Common for dynamically-created stores, factory patterns, or stores in node_modules. | | Coverage by kind | E.g. atom: 3/5 (60%) — 3 out of 5 atom stores received runtime events. 0% for a kind usually means attachMcpLogger was not called for those stores. |

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.