Nanostores MCP

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](#features)
• [Requirements](#requirements)
• [Installation](#installation)
• [Configuration](#configuration)
• [Quick Start](#quick-start)
• [MCP Interface](#mcp-interface)
• [Resources](#mcp-resources)
• [Tools](#mcp-tools)
• [Advanced Tool Arguments](#advanced-tool-arguments)
• [Prompts](#mcp-prompts)
• [Runtime Monitoring](#runtime-monitoring)
• [Reading Results](#reading-results)
• [Privacy & Security](#privacy--security)
• [Example Queries](#example-queries)
• [Architecture](#architecture)
• [Limitations & Caveats](#limitations--caveats)
• [Development](#development)
• [Troubleshooting](#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

| 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](#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

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Valyay
• Source: Valyay/nanostores-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.