Nanostores MCP

Nano Stores MCP

Nanostores 的 Model Context Protocol 服务——在 Claude Desktop 等 AI 助手中分析、调试和监控你的 nanostores。

• 📊 静态分析： 基于 AST 的项目扫描、依赖图、store 检查
• 🔥 运行时监控： 来自 @nanostores/logger 的实时事件、性能指标、活动跟踪
• 📚 文档： 按主题或 store 类型搜索和浏览 Nanostores 文档
• 🎯 零配置： 开箱即用——自动检测项目根目录和 nanostores 文档
• 🌐 框架无关： 支持 React、Vue、Svelte、Angular、Solid、Preact、Lit——以及任何使用 Nanostores 的框架

npx nanostores-mcp

向 AI 提问：“分析我的 store 架构” 或 “哪些 store 更新最频繁？”

---

由 Evil Martians 打造，为 开发者工具 提供产品咨询。

---

目录

• 功能
• 要求
• 安装
• 配置
• 快速开始
• MCP 接口
  • 资源
  • 工具
  • 高级工具参数
  • 提示词
• 运行时监控
  • 读取结果
  • 隐私与安全
• 示例查询
• 架构
• 限制与注意事项
• 开发
• 故障排除

功能

📊 静态分析（基于 AST）

无需运行应用即可了解 nanostores 架构：

• 项目扫描——查找所有 store、订阅者以及导入／导出关系
• 依赖图——可视化 store 之间的依赖关系（Mermaid 图表）
• Store 检查——类型（atom/map/computed/batched/persistentAtom/persistentMap/router）、位置、使用模式、相关文件
• 感知框架的订阅者检测——识别 React、Vue、Svelte 和 Angular 中的 .subscribe() / .listen() 调用及组件绑定
• Vue SFC 支持——解析 .vue 文件中的 <script> 和 <script setup> 块（需要 @vue/compiler-sfc）
• Svelte 支持——解析 <script context="module"> 和实例 <script> 块、自动订阅（模板中的 $storeName），并过滤 Svelte 5 runes（$state、$derived、$effect 等），避免将其误认为 store 引用（需要 svelte）
• Angular DI 支持——解析 @nanostores/angular NanostoresService 构造函数注入，并检测 TypeScript 组件文件中的 this.nanostores.useStore(...) 调用模式

🔥 运行时监控（Logger 集成）

深入了解正在运行的应用：

• 实时事件捕获——来自 @nanostores/logger 的挂载／卸载、值变更、操作调用事件
• 性能分析——查找频繁触发的 store、高错误率和性能瓶颈
• 活动指标——变更频率、操作成功／失败率、操作持续时间
• 综合分析——将静态结构与运行时行为结合，深入调试

📚 文档搜索

直接通过 AI 助手搜索和浏览 Nanostores 文档：

• 全文搜索——根据查询查找指南、API 参考和最佳实践
• 按 store 类型查找——获取与特定 store 类型（atom、map、computed 等）相关的文档
• 自动检测——自动从 node_modules 中的 nanostores 获取文档

要求

要求	版本
Node.js	^20.0.0 || >=22.0.0

必需的对等依赖项（用于静态分析）：

npm install nanostores

可选的对等依赖项 — 仅在使用相应文件格式时安装：

包	使用场景
@vue/compiler-sfc	扫描 Vue SFC（.vue）文件
svelte	扫描 Svelte（.svelte）文件
@nanostores/logger	运行时监控（attachMcpLogger）

没有这些可选软件包，服务仍可运行——它会静默跳过不支持的文件类型。

安装

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

也可以直接运行，无需安装：

npx nanostores-mcp

配置

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %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

需要 GitHub Copilot 扩展（VS Code 1.99+）。在项目中创建 .vscode/mcp.json：

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

工具可在 Copilot 的 Agent 模式中使用（在 Copilot Chat 下拉菜单中选择“Agent”）。

Cursor

在项目根目录创建 .cursor/mcp.json（全局配置则创建 ~/.cursor/mcp.json）：

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

Zed

添加到 Zed 的 settings.json：

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

该服务会显示在 Zed 的 Agent 面板设置中。

Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json：

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

也可以从 Cascade 面板中的 MCP 图标打开此文件 →“配置”。

Claude Code

通过 CLI 添加：

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

或者在项目根目录创建 .mcp.json（与团队共享）：

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

环境变量

变量	默认值	说明
NANOSTORES_MCP_ROOT	cwd	项目根路径
NANOSTORES_MCP_ROOTS	—	以平台分隔符分隔的根路径（Unix 上为 :，Windows 上为 ;），用于多项目配置
WORKSPACE_FOLDER	—	NANOSTORES_MCP_ROOT 的别名 — 由 VS Code 和某些编辑器自动设置
WORKSPACE_FOLDER_PATHS	—	NANOSTORES_MCP_ROOTS 的别名 — 由某些编辑器自动设置
NANOSTORES_MCP_LOGGER_ENABLED	true	设置为 false 或 0 可禁用运行时事件收集和日志记录桥接
NANOSTORES_MCP_LOGGER_PORT	3999	日志记录桥接的 HTTP 端口
NANOSTORES_MCP_LOGGER_HOST	127.0.0.1	绑定的主机。允许的值：127.0.0.1、localhost、::1
NANOSTORES_DOCS_ROOT	自动检测	文档目录路径
NANOSTORES_DOCS_PATTERNS	**/*.md	以逗号分隔的文档 glob 模式

项目根目录的解析方式

服务按优先级顺序选择工作区根目录：

1. 环境变量（最高优先级）— NANOSTORES_MCP_ROOTS / NANOSTORES_MCP_ROOT / WORKSPACE_FOLDER_PATHS / WORKSPACE_FOLDER
2. 客户端根目录 — MCP 客户端通过 roots/list 能力报告的根目录（由某些编辑器自动设置）
3. 当前工作目录 — 在未配置环境变量或客户端根目录时，使用 process.cwd() 作为后备

调用工具时若未提供显式的 projectRoot 参数，服务会使用第一个已配置的根目录。在多根配置中，请始终传入 projectRoot 以避免歧义。

快速入门

1. 静态分析

开箱即用，只需指定你的项目并提问：

• “分析我的 store 架构”
• “解释 nanostores 在此项目中的用法”
• “总结一下 $cart store”
• “我的 stores 已更改——重新扫描项目” ← AI 会强制重新扫描

2. 文档搜索

从 node_modules 中的 nanostores 自动检测：

• “如何使用 computed stores？”
• “展示 persistentAtom 的文档”

3. 运行时监控（可选）

需要在应用中集成 logger。请参阅下文的运行时监控。

• “哪些 stores 更新最频繁？”
• “展示 $user 的近期活动”
• “生成整体健康状况报告”

验证设置

按顺序运行以下四个工具，以确认一切正常：

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)

如果 nanostores_scan_project 返回的 store 数量为零，请检查 NANOSTORES_MCP_ROOT 是否指向正确的项目目录。

MCP 接口

MCP 资源

资源	描述
nanostores://graph	完整依赖关系图（文本 + Mermaid）
nanostores://store/{key}	按名称或 ID 查看 store 详情
nanostores://docs	文档索引——所有页面和标签
nanostores://docs/page/{id}	文档页面的完整内容

MCP 工具

静态分析

工具	描述
nanostores_scan_project	扫描项目中的所有 stores、订阅者和依赖关系
nanostores_store_summary	特定 store 的详细摘要
nanostores_project_outline	高层概览：store 类型、主要目录、中心 store
nanostores_store_subgraph	通过 BFS 扩展的 store 依赖关系邻域
nanostores_store_impact	下游因果链——X 变化时会重新计算／渲染哪些内容

运行时监控

工具	描述
nanostores_runtime_overview	整体健康状况报告，包含所有 stores 的统计信息
nanostores_store_activity	特定 store 的活动时间线（可按类型／操作筛选）
nanostores_find_noisy_stores	找出更改频率或错误率较高的 stores
nanostores_runtime_coverage	将静态图与运行时事件进行比较，以找出覆盖缺口

文档

工具	描述
nanostores_docs_search	按 query（全文）、storeKind（atom、map、computed、persistentAtom 等）或两者搜索文档。可选参数：limit（默认值为 10）、tags

使用 nanostores://docs/page/{id} 资源阅读搜索结果中页面的完整内容。

实用工具

工具	描述
nanostores_ping	服务健康检查和 logger 桥接状态
nanostores_clear_cache	清除项目索引缓存，以强制重新扫描

MCP 提示词

提示词	参数	描述
explain-project	focus (可选)	AI 引导你了解项目的存储架构。focus 可缩小到某项功能或领域（例如 "cart"、"auth"）
explain-store	store_name (必填)	深入了解特定存储的实现和用法
debug-store	store_name (必填)	结合静态数据和运行时数据进行全面分析
debug-project-activity	—	项目范围的性能分析和优化
docs-how-to	task (必填)	基于文档，逐步指导你完成 Nanostores 任务（例如 "How do I sync a map store to localStorage?"）

高级工具参数

大多数工具接受以下可大幅改变其行为的可选参数：

参数	类型	用于	描述
storeId	string	store_summary、store_subgraph、store_impact	精确的 store 标识符——格式：store:src/stores.ts#$counterName。同时提供 storeId 和 name 时，优先使用 storeId。
name	string	store_summary、store_subgraph、store_impact	Store 名称（例如 "$user"）。未提供 storeId 时使用。
radius	number (0–10, 默认值为 2)	nanostores_store_subgraph	Store 周围的 BFS 跳数。1 = 仅直接依赖项；2 = 依赖项的依赖项。警告： 对于连接度很高的枢纽 Store（枢纽得分 > 5），半径 ≥ 2 可能会返回项目中的大部分内容——建议从 1 开始。
projectRoot	string	大多数工具	在多根目录设置中要分析的项目根目录。省略时使用第一个已配置的根目录。在多根目录项目中，请始终指定此参数。
windowMs	number	store_activity、find_noisy_stores、runtime_overview	回溯窗口，单位为毫秒（例如 60000 = 最近 60 s）。将事件筛选到此时间范围内。
kinds	string[]	nanostores_store_activity	按类型筛选事件。可选值："mount"、"unmount"、"change"、"action-start"、"action-end"、"action-error"。
actionName	string	nanostores_store_activity	将事件筛选为特定操作（例如 "increment"）。
compact	boolean	scan_project、find_noisy_stores、runtime_overview	返回压缩且节省令牌的表格，而不是完整文本。对于大型项目，这有助于减少上下文用量。

运行时监控

如需进行运行时分析，请在应用中集成 MCP Logger 客户端。

1. 在应用中安装并启用日志记录桥接：

npm install nanostores-mcp

日志记录桥接会自动启动——无需额外配置。要禁用它，请在 MCP 服务配置中将 NANOSTORES_MCP_LOGGER_ENABLED=false。

2. 定义附带日志记录器的 Store（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. 正常使用 Store——事件（挂载、卸载、变更、操作）会自动捕获，并每秒批量发送到 MCP 服务。

4. 向你的 AI 助手提问：

• “哪些 Store 的变化最频繁？” → nanostores_find_noisy_stores
• “显示 $user 的近期活动” → nanostores_store_activity
• “提供整体健康状况报告” → nanostores_runtime_overview

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

关闭前刷新

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

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

读取结果

nanostores_runtime_overview 健康摘要

概览将存储分为三类：

• 活跃度最高的存储 — 按事件总数（更改 + 操作）排序。如果某个存储在几秒内出现数百次更改，可能存在性能问题。
• 易出错的存储 — 出现 action-error 事件的存储。错误计数较高表示异步操作失败。
• 未卸载的存储 — 在挂载时出现，但从未卸载的存储。可能表示存在内存泄漏。

nanostores_runtime_coverage

将静态存储图与观测到的运行时事件进行比较：

术语	含义
仅静态	AST 扫描发现的存储，但未观测到运行时事件。可能是无用代码、延迟初始化，或缺少 attachMcpLogger 调用。
仅运行时	收到某个存储的事件，但该存储未被扫描器发现。常见于动态创建的存储、工厂模式，或 node_modules 中的存储。
按类型划分的覆盖率	例如，atom: 3/5 (60%) — 5 个 atom 存储中有 3 个收到运行时事件。某类的覆盖率为 0% 通常表示未对这些存储调用 attachMcpLogger。

nanostores_find_noisy_stores

返回在 windowMs 时段内按总活动量（更改 + 操作）排名的存储。如果某个存储的更改频率相对于可见 UI 更新明显偏高，则视为“嘈杂”存储；可用此工具查找重新渲染热点或反复触发计算的链路。

隐私与安全

运行时日志记录器旨在确保数据留在本地计算机上：

• 仅绑定环回地址 — HTTP 桥接仅接受来自 127.0.0.1、localhost 或 ::1 的连接。明确禁止绑定到 0.0.0.0。数据不会离开你的计算机。
• 传输内容 — 从你的应用通过 localhost 发送到 MCP 服务的内容包括：存储名称、时间戳、事件类型，以及可选的值快照（截断至 200 个字符）。不会向 Anthropic 或任何第三方发送任何内容。
• 不持久化任何内容 — 事件保存在进程内存中的环形缓冲区（最多 5 000 个事件）内，服务重启时会被丢弃。
• 屏蔽敏感数据 — 使用 maskEvent 在客户端筛选或删改事件，然后再将其批量发送：

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

• CORS — 桥接会拒绝来自非环回来源的跨源请求。

示例查询

用自然语言向你的 AI 助手提问：

静态分析：

• “分析我的存储架构，找出潜在问题”
• “$user 发生变化时会怎样？显示订阅者和派生存储”

运行时调试：

• “哪些存储更新最频繁？”
• “代码中是否有声明但在运行时从未使用的存储？”
• “调试 $user 存储——结合静态分析与运行时行为”

搭配 Playwright MCP：

• “在浏览器中打开我的应用，与它交互，并分析哪些存储导致最多的重新计算”

文档：

• “如何使用计算型存储？”
• “显示持久化存储的最佳实践”

架构

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

限制与注意事项

多根模式：多个项目中存在同名存储

在多根模式下，两个不同的项目中可以存在名为 $user 的存储。运行时事件存储使用组合键（projectRoot + storeName）将它们区分开来，但摘要视图可能会在没有项目标签的情况下显示两次相同的名称。在多根配置中查询工具时，请务必指定 projectRoot，以获得明确的结果。

静态分析仅涵盖已发现的文件

AST 扫描器会从项目根目录跟踪 TypeScript/JavaScript 导入。运行时动态创建的存储、由工厂生成的存储或位于 node_modules 中的存储不会出现在静态分析结果中——它们可能会在覆盖率报告中显示为“仅运行时”。

解析 Vue 和 Svelte 需要可选依赖项

如果未安装 @vue/compiler-sfc 或 svelte，扫描时会静默跳过 .vue / .svelte 文件。如果你希望完整覆盖这些文件类型，请将它们安装为开发依赖项。

事件环形缓冲区最多可容纳 5 000 个事件

缓冲区满时会丢弃较早的事件。对于高频存储，请使用 windowMs 将查询范围缩小到近期数据，或者在 initMcpLogger 中调低 batchMs，以更频繁地传递事件，降低突发事件期间缓冲区溢出的可能性。

中心存储的 radius 可能会很大

依赖项较多的存储（中心度得分 > 5）在 radius=2 时可能会返回项目图中的大部分内容。请从 radius=1 开始，仅在需要更广泛的上下文时再增大该值。

开发

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

故障排除

日志记录器未接收事件：

1. 使用 ping 工具确认日志记录器桥接已启用并正在运行
2. 检查浏览器控制台中是否有关于连接问题的 [nanostores-mcp] 警告
3. 确认服务器（NANOSTORES_MCP_LOGGER_PORT）和客户端 URL 中的端口一致
4. 使用简单的 atom 存储进行测试，确认事件能够正常流动

端口冲突：

# Change server port
NANOSTORES_MCP_LOGGER_PORT=4000 npx nanostores-mcp

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

TypeScript 错误：

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

找不到文档：

• 服务器会自动从 node_modules 中的 nanostores 检测文档
• 确保已安装 nanostores：npm install nanostores
• 或手动将 NANOSTORES_DOCS_ROOT 设置为指向文档目录

相关项目

Nanostores 生态系统：

• nanostores — 轻量级状态管理器（atom、map、computed、batched、deepMap）
• @nanostores/logger — 日志记录器和操作系统
• @nanostores/persistent — 持久化存储（localStorage、sessionStorage）
• @nanostores/router — SPA 路由器
• @nanostores/i18n — 国际化
• @nanostores/react、@nanostores/vue、@nanostores/preact、@nanostores/solid、@nanostores/lit — 框架绑定

MCP：

• Model Context Protocol — MCP 规范
• Playwright MCP — 浏览器自动化（可与 nanostores-mcp 配合进行运行时分析）

许可证

MIT

贡献

欢迎贡献！请提交 issue 或 PR。