@abraracs/better-shopify-wc-mcp 1.0.0

package/README.md

@@ -0,0 +1,110 @@
+# Better Shopify Web Components MCP
+
+An MCP (Model Context Protocol) server that provides accurate Shopify Polaris web component documentation to AI tools like Cursor, GitHub Copilot, and Claude.
+
+## Why This Exists
+
+Shopify's official MCP often **hallucinates attributes** because:
+
+- Polaris web components have **specialized attributes only**
+- Standard HTML attributes (`style`, `class`, `onclick`) **don't work**
+- AI models haven't learned the correct patterns yet
+
+This MCP provides:
+
+- ✅ **Only valid attributes** from official docs
+- ✅ **Workaround patterns** for styling limitations
+- ✅ **System prompts** with Polaris-specific rules
+
+## Installation
+
+### Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "polaris": {
+      "command": "npx",
+      "args": ["-y", "@abraracs/better-shopify-wc-mcp"]
+    }
+  }
+}
+```
+
+### GitHub Copilot (VS Code)
+
+Add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "polaris": {
+      "command": "npx",
+      "args": ["-y", "@abraracs/better-shopify-wc-mcp"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "polaris": {
+      "command": "npx",
+      "args": ["-y", "@abraracs/better-shopify-wc-mcp"]
+    }
+  }
+}
+```
+
+## Usage
+
+Once configured, the AI will have access to:
+
+### Tools
+
+- `list_components` - List all 47 Polaris components
+- `get_component` - Get full documentation for a component
+- `search_components` - Search by keyword
+
+### Resources
+
+- `polaris://components/{name}` - Direct access to component docs
+
+### Prompts
+
+- `polaris_rules` - Critical rules and workaround patterns
+
+## Key Concept: Styling Workarounds
+
+Polaris web components don't support `style` or `class` attributes. When you need custom styling, put it **INSIDE** the component:
+
+```html
+<!-- ❌ WRONG: style on component does nothing -->
+<s-paragraph style="text-align: center;">Text</s-paragraph>
+
+<!-- ✅ CORRECT: style on inner element -->
+<s-paragraph>
+  <div style="text-align: center;">Text</div>
+</s-paragraph>
+```
+
+## Components Included
+
+47 Polaris web components including:
+
+- Actions: `button`, `buttongroup`, `link`, `menu`
+- Forms: `textfield`, `select`, `checkbox`, `datepicker`
+- Layout: `box`, `stack`, `grid`, `section`, `page`
+- Feedback: `banner`, `modal`, `popover`, `tooltip`
+- Display: `text`, `heading`, `badge`, `avatar`, `icon`
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * Better Shopify Web Components MCP Server
+ *
+ * Provides accurate Polaris web component documentation with:
+ * - Only valid attributes (no hallucinations)
+ * - Workaround patterns for styling limitations
+ * - System prompts with Polaris-specific rules
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,325 @@
+#!/usr/bin/env node
+/**
+ * Better Shopify Web Components MCP Server
+ *
+ * Provides accurate Polaris web component documentation with:
+ * - Only valid attributes (no hallucinations)
+ * - Workaround patterns for styling limitations
+ * - System prompts with Polaris-specific rules
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import * as fs from "fs";
+import * as path from "path";
+import { fileURLToPath } from "url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const DOCS_DIR = path.join(__dirname, "..", "docs");
+function loadDocs() {
+    const docs = [];
+    const files = fs.readdirSync(DOCS_DIR).filter(f => f.endsWith(".md"));
+    for (const file of files) {
+        const content = fs.readFileSync(path.join(DOCS_DIR, file), "utf-8");
+        const name = file.replace(".md", "");
+        // Extract description from frontmatter or first paragraph
+        let description = "";
+        const descMatch = content.match(/description:\s*>-?\s*\n\s+(.+?)(?:\n[a-z_]+:|---)/s);
+        if (descMatch) {
+            description = descMatch[1].replace(/\n\s+/g, " ").trim();
+        }
+        docs.push({ name, filename: file, content, description });
+    }
+    return docs;
+}
+const componentDocs = loadDocs();
+// Create server
+const server = new Server({
+    name: "better-shopify-wc-mcp",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        resources: {},
+        tools: {},
+        prompts: {},
+    },
+});
+// ============ RESOURCES ============
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    return {
+        resources: componentDocs.map(doc => ({
+            uri: `polaris://components/${doc.name}`,
+            name: doc.name,
+            description: doc.description || `Documentation for ${doc.name} component`,
+            mimeType: "text/markdown",
+        })),
+    };
+});
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const uri = request.params.uri;
+    const match = uri.match(/^polaris:\/\/components\/(.+)$/);
+    if (!match) {
+        throw new Error(`Invalid resource URI: ${uri}`);
+    }
+    const componentName = match[1].toLowerCase();
+    const doc = componentDocs.find(d => d.name.toLowerCase() === componentName);
+    if (!doc) {
+        throw new Error(`Component not found: ${componentName}`);
+    }
+    return {
+        contents: [
+            {
+                uri,
+                mimeType: "text/markdown",
+                text: doc.content,
+            },
+        ],
+    };
+});
+// ============ TOOLS ============
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "list_components",
+                description: "List all available Shopify Polaris web components",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                },
+            },
+            {
+                name: "get_component",
+                description: "Get full documentation for a specific Polaris component including all valid attributes",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        name: {
+                            type: "string",
+                            description: "Component name (e.g., 'button', 'modal', 'stack')",
+                        },
+                    },
+                    required: ["name"],
+                },
+            },
+            {
+                name: "search_components",
+                description: "Search for Polaris components by keyword in name or description",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        query: {
+                            type: "string",
+                            description: "Search keyword",
+                        },
+                    },
+                    required: ["query"],
+                },
+            },
+        ],
+    };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    switch (name) {
+        case "list_components": {
+            const list = componentDocs.map(d => ({
+                name: d.name,
+                tag: `<s-${d.name}>`,
+                description: d.description.slice(0, 100) + (d.description.length > 100 ? "..." : ""),
+            }));
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(list, null, 2),
+                    },
+                ],
+            };
+        }
+        case "get_component": {
+            const componentName = args.name.toLowerCase();
+            const doc = componentDocs.find(d => d.name.toLowerCase() === componentName);
+            if (!doc) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Component "${componentName}" not found. Use list_components to see available components.`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: doc.content,
+                    },
+                ],
+            };
+        }
+        case "search_components": {
+            const query = args.query.toLowerCase();
+            const results = componentDocs.filter(d => d.name.toLowerCase().includes(query) ||
+                d.description.toLowerCase().includes(query) ||
+                d.content.toLowerCase().includes(query));
+            if (results.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `No components found matching "${query}"`,
+                        },
+                    ],
+                };
+            }
+            const summary = results.map(d => ({
+                name: d.name,
+                tag: `<s-${d.name}>`,
+                description: d.description.slice(0, 150) + (d.description.length > 150 ? "..." : ""),
+            }));
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(summary, null, 2),
+                    },
+                ],
+            };
+        }
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+});
+// ============ PROMPTS ============
+server.setRequestHandler(ListPromptsRequestSchema, async () => {
+    return {
+        prompts: [
+            {
+                name: "polaris_rules",
+                description: "Critical rules for working with Shopify Polaris web components - MUST READ before generating any Polaris UI code",
+            },
+        ],
+    };
+});
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    if (request.params.name === "polaris_rules") {
+        return {
+            description: "Critical rules for Shopify Polaris web components",
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: POLARIS_RULES_PROMPT,
+                    },
+                },
+            ],
+        };
+    }
+    throw new Error(`Unknown prompt: ${request.params.name}`);
+});
+// ============ SYSTEM PROMPT ============
+const POLARIS_RULES_PROMPT = `# Shopify Polaris Web Components - Critical Rules
+
+You are working with Shopify Polaris web components (tags starting with \`s-\`).
+These are SPECIALIZED WEB COMPONENTS with strict rules. Follow them exactly.
+
+## ⚠️ CRITICAL: Attribute Rules
+
+1. **ONLY use attributes documented for each component**
+2. **DO NOT use standard HTML attributes** - they will NOT work:
+   - ❌ style
+   - ❌ class
+   - ❌ id  
+   - ❌ onclick / onchange / on*
+   - ❌ data-*
+   
+3. Each component has its OWN specific attributes (e.g., \`variant\`, \`tone\`, \`gap\`)
+
+## 🔧 Styling Workarounds
+
+When you need styling that's not available as a component attribute,
+put the override **INSIDE** the web component using standard HTML:
+
+### Example: Center-aligned text
+\`\`\`html
+<!-- ❌ WRONG: style attribute on s-paragraph does nothing -->
+<s-paragraph style="text-align: center;">Text</s-paragraph>
+
+<!-- ✅ CORRECT: put styled div INSIDE the component -->
+<s-paragraph>
+  <div style="text-align: center;">Text</div>
+</s-paragraph>
+\`\`\`
+
+### Example: Custom spacing
+\`\`\`html
+<!-- ❌ WRONG: margin on component does nothing -->
+<s-button style="margin-top: 20px;">Click</s-button>
+
+<!-- ✅ CORRECT: use s-box or s-stack for spacing -->
+<s-stack gap="large">
+  <s-text>Some text above</s-text>
+  <s-button>Click</s-button>
+</s-stack>
+\`\`\`
+
+### Example: Flex / Grid layouts
+\`\`\`html
+<!-- ✅ Use s-stack with direction for flex-like layouts -->
+<s-stack direction="inline" gap="base">
+  <s-button>Button 1</s-button>
+  <s-button>Button 2</s-button>
+</s-stack>
+
+<!-- ✅ Use s-grid for grid layouts -->
+<s-grid columns="2">
+  <s-box>Cell 1</s-box>
+  <s-box>Cell 2</s-box>
+</s-grid>
+\`\`\`
+
+## 📋 Common Workaround Patterns
+
+| Need | Wrong Approach | Correct Pattern |
+|------|----------------|-----------------|
+| Center text | \`<s-paragraph style="text-align:center">\` | \`<s-paragraph><div style="text-align:center">text</div></s-paragraph>\` |
+| Custom margins | \`<s-button style="margin:...">\` | Use \`<s-stack>\` or \`<s-box>\` with gap/padding attrs |
+| Inline layout | \`<div style="display:flex">\` | \`<s-stack direction="inline">\` |
+| Colors | \`<s-text style="color:red">\` | Use \`tone\` attribute if available |
+| Visibility | \`style="display:none"\` | Wrap in \`<div>\` with display logic |
+
+## 🏷️ Component Tag Format
+
+All Polaris web components use the \`s-\` prefix:
+- \`<s-button>\` - Buttons
+- \`<s-stack>\` - Flex layouts  
+- \`<s-box>\` - Container with padding
+- \`<s-modal>\` - Modal dialogs
+- \`<s-text>\` - Text display
+- etc.
+
+## 📚 Before Using Any Component
+
+1. Use \`get_component\` tool to fetch its documentation
+2. Check the **Properties** section for valid attributes
+3. Check **Examples** for proper usage patterns
+4. NEVER assume an attribute exists - verify in docs first
+
+## 🚫 Common Mistakes to Avoid
+
+1. Using \`className\` or \`class\` - use component's own styling props
+2. Using inline \`style\` on components - put styles on inner elements
+3. Using React event handlers (\`onClick\`) - components have their own events
+4. Assuming HTML attributes work - they don't on web components
+`;
+// ============ START SERVER ============
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Better Shopify WC MCP server running on stdio");
+}
+main().catch(console.error);