Starwind UI MCP Server

官方 MCP 注册表 · io.github.starwind-ui/mcp

这是一个适用于 Starwind UI v3 和 Starwind Pro 的 TypeScript Model Context Protocol 服务。它为 Astro 和 React 项目中的 AI 客户端提供最新的、兼顾框架特性的指导。

快速开始

如需查看维护中的客户端配置指南，请参阅 Starwind UI MCP 文档。

Codex（~/.codex/config.toml）：

[mcp_servers.starwind_ui]
command = "npx"
args = ["-y", "@starwind-ui/mcp"]
enabled = true

Claude Code（.mcp.json）或 Cursor（.cursor/mcp.json）：

{
  "mcpServers": {
    "starwind-ui": {
      "command": "npx",
      "args": ["-y", "@starwind-ui/mcp"]
    }
  }
}

更改配置后，请重启客户端或重新加载其 MCP 服务。

v3 模型

Starwind UI v3 有三个相关部分。MCP 会将它们区分开来：

部分	含义	MCP 行为
样式组件	由副本管理、包含 Astro 和/或 React 实现的 UI 组件	使用 starwind_search 搜索，并使用 starwind_add 安装
基元	更底层的 Astro 和 React 适配器（适用时由 Starwind Runtime 提供支持）	使用 surface: "primitive" 搜索；使用 v3 的 primitives add 命令安装
Runtime	与框架无关的行为 API	使用 Runtime 主题或部分，通过 starwind_docs 获取

服务会根据版本化的 ai-manifest.json 验证这些层级，缓存已验证的数据，并在网站不可用时回退到内置的 v3 快照。

工具

工具	用途
starwind_init	为现有 Astro 或 React 项目生成 v3 初始化命令。Pro 为可选项。
starwind_add	验证请求，并为样式组件、基元或仅适用于 Astro 的 Pro 区块生成安装命令或延迟安装命令。
starwind_search	根据框架元数据和筛选条件搜索样式组件、基元和 Pro 区块。
starwind_docs	定位准确的组件、基元、Runtime、迁移和框架文档。
starwind_migrate	检查项目并生成安全、优先采用交互方式的 v2 到 v3 迁移指南。

工具调用会同时返回易读的 JSON 文本和 MCP structuredContent。

要求和行为

• 生成的 v3 CLI 命令要求使用 Node.js 22.12.0 或更高版本。
• starwind_init 面向现有的 Astro 5+ 或 React 18+ 项目；除非提供 framework，否则 CLI 会自动检测框架。
• 免费的 @starwind-pro/* 目录区块在常规初始化后即可使用。付费区块需要明确授权；只有在必要时才传入 pro: true。
• Starwind Pro 区块目前面向 Astro。React 搜索会排除这些区块，React 添加请求也会明确拒绝它们。
• 迁移默认采用交互方式。只有在确实需要备份并覆盖时，才设置 yes: true。
• 尽可能在本地检测包管理器和项目上下文，并将解析出的包管理器传递给 CLI 执行添加命令。任何工具都不会执行生成的命令。

从免费版升级到 Pro

MCP 确保用户能发现 Pro，同时无需强制付费设置。搜索结果会链接到 Pro 目录，免费的 Pro 模块仍可直接安装，而付费结果则包含结构化的 proUpgrade 路径，其中提供购买和安装链接。

对于现有的 Astro 项目，MCP 建议：

pnpm dlx starwind@latest setup --yes

设置命令会自动检测项目的包管理器，因此无需添加 --package-manager 标志。它会准备 Pro 注册表和 .env.local；将 STARWIND_LICENSE_KEY 占位符替换为购买的密钥，然后运行返回的 deferredCommand。请将密钥视为敏感信息：不要将 .env.local 纳入源代码管理，也绝不要在日志或客户端代码中暴露密钥。使用 pro: true 初始化的项目会收到等效的 init --pro 命令。

开发

pnpm build
pnpm lint
pnpm test:run

使用以下命令运行选择启用的生产清单契约测试：

RUN_LIVE_CONTRACT_TESTS=1 pnpm test:run src/utils/starwind_live_contract.test.ts

许可证

MIT。请参阅 LICENSE。

安全