starwind-ui/starwind-ui-mcp

·
io.github.starwind-ui/mcp
A TypeScript Model Context Protocol server for Starwind UI v3 and Starwind Pro. It gives AI clients current, framework-aware guidance for Astro and React projects.
Quick start
For the maintained client setup guide, see the Starwind UI MCP documentation.
Codex (~/.codex/config.toml):
Claude Code (.mcp.json) or Cursor (.cursor/mcp.json):
Restart the client or reload its MCP servers after changing the configuration.
v3 model
Starwind UI v3 has three related surfaces. The MCP keeps them distinct:
| Surface | What it represents | MCP behavior |
| --- | --- | --- |
| Styled components | Copy-owned UI components with Astro and/or React implementations | Search and install with starwind_search and starwind_add |
| Primitives | Lower-level Astro and React adapters, backed by Starwind Runtime where applicable | Search with surface: "primitive"; install with the v3 primitives add command |
| Runtime | Framework-neutral behavior APIs | Fetch with starwind_docs using the Runtime topic or surface |
The server validates these layers against the versioned ai-manifest.json, caches validated data, and falls back to a bundled v3 snapshot if the site is unavailable.
Tools
| Tool | Purpose |
| --- | --- |
| starwind_init | Generate v3 initialization commands for an existing Astro or React project. Pro is opt-in. |
| starwind_add | Validate requests and generate installation or deferred-install commands for styled components, primitives, or Astro-only Pro blocks. |
| starwind_search | Search styled components, primitives, and Pro blocks with framework metadata and filters. |
| starwind_docs | Resolve exact component, primitive, Runtime, migration, and framework documentation. |
| starwind_migrate | Inspect a project and generate safe, interactive-first v2-to-v3 migration guidance. |
Tool calls return both readable JSON text and MCP structuredContent.
Requirements and behavior
- Generated v3 CLI commands require Node.js 22.12.0 or newer.
- starwind_init targets existing Astro 5+ or React 18+ projects and lets the CLI auto-detect the framework unless framework is supplied.
- Free @starwind-pro/* catalog blocks work after ordinary initialization. Paid blocks require explicit authorization; pass pro: true only when it is required.
- Starwind Pro blocks currently target Astro. React searches omit them, and React add requests reject them explicitly.
- Migration is interactive by default. Set yes: true only when backup-and-overwrite behavior is intended.
- Package-manager and project context are detected locally when possible, and add commands pass the resolved package manager to the CLI. No tool executes the generated command.