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
• 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

| nanostores_runtime_coverage | Compare stati