Skip to main content
Glama
deenesjakoruzh
starwind-ui

Starwind UI MCP Server

by starwind-ui
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

一个用于 Starwind UI v3 和 Starwind Pro 的 TypeScript Model Context Protocol 服务器。它为 AI 客户端提供基于当前框架的、针对 Astro 和 React 项目的指导。

快速开始

关于维护的客户端设置指南，请参阅 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 服务器。

Related MCP server: shadcn-ui MCP Server

v3 模型

Starwind UI v3 有三个相关的表层。MCP 将它们区分开来：

表层

表示的内容

MCP 行为

样式组件（Styled components）

拥有副本的 UI 组件，带有 Astro 和/或 React 实现

使用 starwind_search 和 starwind_add 搜索和安装

原语（Primitives）

较低级别的 Astro 和 React 适配器，在适用时由 Starwind Runtime 支持

使用 surface: "primitive" 搜索；使用 v3 的 primitives add 命令安装

运行时（Runtime）

框架无关的行为 API

使用 starwind_docs 并指定 Runtime 主题或表层来获取

服务器会根据版本化的 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。

安全性

Available Tools

5 tools
starwind_addA

Generates validated Starwind UI v3 install commands for styled components, vendored primitives, or Starwind Pro blocks, with optional Astro or React targeting.

ParametersJSON Schema
NameRequiredDescriptionDefault
toNoPrimitive destination passed to --to.
cwdNo
proNoConfigure paid Pro authorization during optional init.
initNoPrepend project initialization for a new setup.
surfaceNoDefaults to styled.
frameworkNoOptional framework override.
overwriteNoAllow the CLI to overwrite existing files.
componentsYesNames to install, or a single 'all'/'--all' item.
packageManagerNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYesStructured Starwind installation result.

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavior. It states 'generates validated... commands' but does not clarify whether the tool only outputs commands or also executes them. Parameters like 'init' and 'overwrite' suggest potential side effects, yet the description omits any discussion of safety, authentication, or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that efficiently conveys the core purpose without unnecessary words. Every element earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 9 parameters and an output schema. While the description covers the high-level purpose, it lacks details on parameter relationships, the fact that 'components' can be 'all', and whether the tool executes commands or just generates them. The output schema exists, so return values are not missing, but the behavioral and contextual gaps reduce completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 78%, so the schema already documents most parameters. The description adds no additional meaning beyond the schema. Baseline 3 is appropriate as the description does not improve understanding of the two undocumented parameters (cwd, packageManager).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('generates') and resource ('validated Starwind UI v3 install commands') and clearly distinguishes from siblings like starwind_init (initialization) and starwind_search (search) by focusing on component installation with optional framework targeting.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use for adding components after setup, but does not explicitly state when to use this tool versus starwind_init or starwind_migrate. No when-not-to-use or alternative guidance is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

starwind_docsB

Fetches current Starwind UI v3 documentation across styled components, primitives, Runtime, migration, and Astro or React framework guides.

ParametersJSON Schema
NameRequiredDescriptionDefault
fullNoUse the full aggregate reference when no exact page is found.
topicNo
surfaceNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYesStructured Starwind documentation result.

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full responsibility for behavioral disclosure. The word 'Fetches' implies a safe, read-only operation, but the description does not explicitly state that it produces no side effects, requires authentication, or has any rate limits. This is adequate but lacks the explicitness needed for agents to confidently assess risk.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, focused sentence that leads with the verb 'Fetches' and immediately conveys the resource. It packs multiple categories without wasted words. While slightly long due to enumeration, every clause adds relevant scope. No unnecessary repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema (so return values need not be detailed) and the absence of annotations, the description covers the tool's scope adequately. However, it omits guidance on how the 'full' parameter differs from a non-full request, when to use different surfaces, and how to combine parameters effectively. The context is sufficient for basic use but lacks depth for complex queries.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is low (33%: only the 'full' parameter has a description). The description adds contextual meaning by enumerating categories that align with the 'surface' enum values, helping an agent understand what each surface likely refers to. However, 'topic' remains entirely undefined, and the relationship between 'topic' and 'surface' is not clarified. The description partially compensates for the schema gap but leaves ambiguity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Fetches'), the resource ('current Starwind UI v3 documentation'), and the scope across multiple categories (styled components, primitives, Runtime, migration, framework guides). This sharply distinguishes it from sibling tools like starwind_init, starwind_add, starwind_search, or starwind_migrate, which serve different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus the sibling tool starwind_search, or when to avoid it. It lists what the tool fetches but does not explain prerequisites, exclusion criteria, or the relationship between the surface enum values and the listed categories. An agent must guess the intended usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

starwind_initA

Generates a Starwind UI v3 initialization command for an existing Astro or React project. The CLI auto-detects the framework unless an override is provided. Paid Pro authorization is opt-in and currently targets Astro.

ParametersJSON Schema
NameRequiredDescriptionDefault
cwdNoProject directory used for package manager and framework detection.
proNoConfigure paid Starwind Pro authorization. Defaults to false.
frameworkNoOptional CLI framework override.
packageManagerNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYesStructured Starwind initialization result.

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses that the tool generates a command (not directly modifying anything), mentions auto-detection behavior, and notes Pro is opt-in targeting Astro. This is strong coverage of behavioral effects, missing only potential side effects or return format.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler. Front-loaded with the core action, then specifics on auto-detection and Pro. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists (not shown but flagged as present), the description does not need to detail return values. It covers generation scope, framework detection, and Pro behavior. Completeness is high; minor gap could be a note that this does not install dependencies or modify files directly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 75% (3 of 4 parameters described). The description adds context that 'pro' is opt-in and targets Astro, and that 'framework' override is optional. The 'packageManager' parameter lacks any description enrichment, but the overall additive value is moderate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool generates a Starwind UI v3 initialization command for existing Astro or React projects. This specific verb+resource combination clearly distinguishes it from siblings like 'starwind_add', 'starwind_search', 'starwind_docs', and 'starwind_migrate'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions CLI auto-detects the framework unless overridden, and that Pro authorization is opt-in targeting Astro. This provides clear context for when to override vs. not, though it does not explicitly state when this tool is preferred over siblings or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

starwind_migrateB

Generates the safe Starwind UI v3 migration command for a legacy Astro project. Interactive migration is the default; non-interactive overwrite behavior must be explicitly requested.

ParametersJSON Schema
NameRequiredDescriptionDefault
cwdNoLegacy Starwind project directory to inspect.
yesNoAdd --yes to create a backup and overwrite registered conflicts without prompts.
packageManagerNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYesStructured Starwind migration guidance.

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full weight for behavioral disclosure. It reveals that the tool has interactive and non-interactive modes, but omits critical details: what 'safe' means, whether it actually executes migration or just prints a command, what happens during overwrite (backup? destructive?), and any permission or side-effect notifications. Given the complexity of migration, this is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose. Every word earns its place. No fluff or redundancy. The structure efficiently communicates the core action and key behavioral choice.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite an output schema being present, the description leaves major ambiguities: does the tool execute migration or just output a command? How does the packageManager parameter affect behavior? What is the interactive workflow? The description is too sparse for an agent to reliably invoke the tool, especially given the absence of annotations to provide safety cues.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 67% (cwd and yes have descriptions, packageManager does not). The main description adds no parameter information beyond the schema. For packageManager, there is no description in either the schema or the description, leaving the agent unaware of its role. The description fails to compensate for the missing parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool generates a migration command for a specific context ('Starwind UI v3 migration command for a legacy Astro project'). The verb 'generates' and resource 'migration command' are precise. The interactive vs. non-interactive nuance further clarifies behavior. This easily distinguishes it from sibling tools like starwind_init or starwind_add.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description hints at usage context (legacy Astro projects) and default behavior (interactive), but does not explicitly state when NOT to use this tool versus alternatives, nor mention prerequisites or conditions. For example, it is unclear if starwind_migrate should be used over starwind_init for an existing project. The description provides some context but lacks exclusions or comparative guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv0.5.0
    • Changedstarwind_add11 fields changed
      • changedInput schema / properties / components / description
        Previous value: -"Array of component names to install (e.g., ['button', 'card', 'dialog']). Use '--all' as a single item to install all components."New value: +"Names to install, or a single 'all'/'--all' item."
      • addedInput schema / properties / components / minItems
        Added value: +1
      • removedInput schema / properties / cwd / description
        Removed value: -"Working directory for package manager detection. Defaults to current directory."
      • addedInput schema / properties / framework
        Added value: +{
+  "description": "Optional framework override.",
+  "enum": [
+    "astro",
+    "react"
+  ],
+  "type": "string"
+}
      • changedInput schema / properties / init / description
        Previous value: -"Whether to include the init command for new projects. Set to true if Starwind UI has not been initialized in the project yet."New value: +"Prepend project initialization for a new setup."
      • addedInput schema / properties / overwrite
        Added value: +{
+  "description": "Allow the CLI to overwrite existing files.",
+  "type": "boolean"
+}
      • removedInput schema / properties / packageManager / description
        Removed value: -"Override the auto-detected package manager. Use this if package manager detection fails or you want to force a specific one."
      • changedInput schema / properties / pro / description
        Previous value: -"Set to true for Starwind Pro projects. This adds --pro to the init command. Required when using @starwind-pro/ blocks. Auto-detected if components contain @starwind-pro/ prefix."New value: +"Configure paid Pro authorization during optional init."
      • addedInput schema / properties / surface
        Added value: +{
+  "description": "Defaults to styled.",
+  "enum": [
+    "styled",
+    "primitive"
+  ],
+  "type": "string"
+}
      • addedInput schema / properties / to
        Added value: +{
+  "description": "Primitive destination passed to --to.",
+  "type": "string"
+}
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "result": {
+      "additionalProperties": {},
+      "description": "Structured Starwind installation result.",
+      "type": "object"
+    }
+  },
+  "required": [
+    "result"
+  ],
+  "type": "object"
+}
    • Changedstarwind_docs4 fields changed
      • changedInput schema / properties / full / description
        Previous value: -"Whether to fetch the full documentation with complete code examples. Defaults to false for a more concise version."New value: +"Use the full aggregate reference when no exact page is found."
      • addedInput schema / properties / surface
        Added value: +{
+  "enum": [
+    "auto",
+    "component",
+    "primitive",
+    "guide",
+    "runtime"
+  ],
+  "type": "string"
+}
      • removedInput schema / properties / topic / description
        Removed value: -"Optional topic to filter documentation (e.g., 'button', 'accordion', 'theming', 'installation'). Leave empty to get all documentation."
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "result": {
+      "additionalProperties": {},
+      "description": "Structured Starwind documentation result.",
+      "type": "object"
+    }
+  },
+  "required": [
+    "result"
+  ],
+  "type": "object"
+}
    • Changedstarwind_init5 fields changed
      • changedInput schema / properties / cwd / description
        Previous value: -"Working directory for package manager detection. Defaults to current directory."New value: +"Project directory used for package manager and framework detection."
      • addedInput schema / properties / framework
        Added value: +{
+  "description": "Optional CLI framework override.",
+  "enum": [
+    "astro",
+    "react"
+  ],
+  "type": "string"
+}
      • removedInput schema / properties / packageManager / description
        Removed value: -"Override the auto-detected package manager. Use this if package manager detection fails or you want to force a specific one."
      • changedInput schema / properties / pro / description
        Previous value: -"Whether to initialize with Starwind Pro support. Defaults to TRUE. Pro setup enables both standard components AND Pro blocks. Only set to false if you specifically want standard-only setup."New value: +"Configure paid Starwind Pro authorization. Defaults to false."
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "result": {
+      "additionalProperties": {},
+      "description": "Structured Starwind initialization result.",
+      "type": "object"
+    }
+  },
+  "required": [
+    "result"
+  ],
+  "type": "object"
+}
    • Addedstarwind_migrate
    • Changedstarwind_search9 fields changed
      • removedInput schema / properties / category / description
        Removed value: -"Filter Starwind Pro blocks by category."
      • addedInput schema / properties / cwd
        Added value: +{
+  "description": "Project directory used to detect existing Pro setup.",
+  "type": "string"
+}
      • addedInput schema / properties / framework
        Added value: +{
+  "enum": [
+    "astro",
+    "react",
+    "all"
+  ],
+  "type": "string"
+}
      • changedInput schema / properties / limit / description
        Previous value: -"Maximum number of Pro blocks to return. Defaults to 20, maximum 50."New value: +"Pro result limit; defaults to 20 and caps at 50."
      • removedInput schema / properties / offset / description
        Removed value: -"Offset for paginating Pro block results. Defaults to 0."
      • removedInput schema / properties / plan / description
        Removed value: -"Filter Starwind Pro blocks by plan type."
      • removedInput schema / properties / query / description
        Removed value: -"Search query for components and Pro blocks."
      • addedInput schema / properties / surface
        Added value: +{
+  "description": "Defaults to all.",
+  "enum": [
+    "styled",
+    "primitive",
+    "all"
+  ],
+  "type": "string"
+}
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "result": {
+      "additionalProperties": {},
+      "description": "Structured layered Starwind search result.",
+      "type": "object"
+    }
+  },
+  "required": [
+    "result"
+  ],
+  "type": "object"
+}
  2. 10 tool updatesv0.4.0
    • Removedfetch_llm_data
    • Removedget_documentation
    • Removedget_package_manager
    • Removedinit_project
    • Removedinstall_component
    • Addedstarwind_add
    • Addedstarwind_docs
    • Addedstarwind_init
    • Addedstarwind_search
    • Removedupdate_component
  3. 6 tool updates
    • First observedfetch_llm_data
    • First observedget_documentation
    • First observedget_package_manager
    • First observedinit_project
    • First observedinstall_component
    • First observedupdate_component
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A3.6/5.0

Scored across 5 tools

Disambiguation4/5

Each tool has a clear, distinct purpose: initialization, adding components, searching, documentation, and migration. The only minor ambiguity is between starwind_init and starwind_add, as both generate CLI commands. However, starwind_init is specifically for project initialization, while starwind_add handles component and block installation, which is a reasonable distinction.

Naming Consistency4/5

All tools follow a consistent starwind_ prefix followed by an imperative verb (init, add, search, docs, migrate). This is a clean, predictable pattern. The slight deduction is because the imperative verb is not strictly a verb_noun pattern (e.g., starwind_search instead of starwind_search_components), but this is a minor and common stylistic choice.

Tool Count5/5

With 5 tools, the server is very well-scoped. It covers the core actions a developer would need when using the Starwind UI library within an MCP context: initializing, adding components, searching, and migrating. Each tool clearly earns its place, and the count feels appropriate for the scope of managing and interacting with a UI component library.

Completeness4/5

The tool set covers the primary development workflow: initializing, adding components, searching, accessing documentation, and managing migrations. This provides a comprehensive foundation. The only arguably missing piece might be a tool for direct configuration management or status checks. However, for an MCP interface, this set is remarkably complete and avoids common gaps in lifecycle management.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches