@idealyst/mcp-server 1.0.84

package/README.md

@@ -0,0 +1,202 @@
+# @idealyst/mcp-server
+
+Model Context Protocol (MCP) server providing documentation, examples, and usage instructions for the Idealyst framework.
+
+## What is this?
+
+This MCP server allows AI assistants (like Claude) to access comprehensive documentation about the Idealyst framework, including:
+
+- Component documentation and examples
+- CLI usage instructions
+- Framework setup guides
+- Best practices and patterns
+
+## Installation
+
+```bash
+# From the Idealyst monorepo
+cd packages/mcp-server
+yarn install
+yarn build
+
+# Or install globally
+npm install -g @idealyst/mcp-server
+```
+
+## Usage with Claude Desktop
+
+Add this server to your Claude Desktop configuration:
+
+### macOS/Linux
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "idealyst": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/idealyst-framework/packages/mcp-server/dist/index.js"
+      ]
+    }
+  }
+}
+```
+
+### Windows
+
+Edit `%APPDATA%\Claude\claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "idealyst": {
+      "command": "node",
+      "args": [
+        "C:\\path\\to\\idealyst-framework\\packages\\mcp-server\\dist\\index.js"
+      ]
+    }
+  }
+}
+```
+
+After adding the configuration, restart Claude Desktop.
+
+## Available Tools
+
+### list_components
+
+List all available Idealyst components with brief descriptions.
+
+**Example:**
+```
+List all Idealyst components
+```
+
+### get_component_docs
+
+Get detailed documentation for a specific component including props, usage, and examples.
+
+**Parameters:**
+- `component` (string): Component name (e.g., 'Button', 'Card', 'Input')
+
+**Example:**
+```
+Get documentation for the Button component
+```
+
+### get_component_example
+
+Get code examples for a specific component.
+
+**Parameters:**
+- `component` (string): Component name
+- `example_type` (optional): 'basic', 'variants', 'with-icons', or 'interactive'
+
+**Example:**
+```
+Show me an interactive example of the Dialog component
+```
+
+### get_cli_usage
+
+Get information about Idealyst CLI commands.
+
+**Parameters:**
+- `command` (optional): Specific CLI command
+
+**Example:**
+```
+How do I use the Idealyst CLI to create a new web app?
+```
+
+### search_components
+
+Search for components by name, category, or feature.
+
+**Parameters:**
+- `query` (optional): Search query
+- `category` (optional): Filter by category ('layout', 'form', 'display', 'navigation', 'overlay', 'data')
+
+**Example:**
+```
+Search for form components in Idealyst
+```
+
+## Available Resources
+
+The server also provides framework guides as resources:
+
+- **Getting Started**: Complete setup guide
+- **Components Overview**: All available components organized by category
+- **Theming Guide**: Customizing themes
+- **CLI Reference**: Complete CLI documentation
+
+## Development
+
+```bash
+# Install dependencies
+yarn install
+
+# Build
+yarn build
+
+# Watch mode
+yarn dev
+
+# Test the server
+node dist/index.js
+```
+
+## Example Queries for Claude
+
+Once the MCP server is connected to Claude, you can ask questions like:
+
+- "List all Idealyst components"
+- "Show me how to use the Button component with icons"
+- "How do I create a new Idealyst workspace?"
+- "What form components are available in Idealyst?"
+- "Give me an example of using the Dialog component"
+- "How do I customize the theme in Idealyst?"
+
+## Architecture
+
+The server exposes:
+
+- **Tools**: Callable functions for querying component docs, examples, and CLI usage
+- **Resources**: Static framework guides and documentation
+
+All data is stored in TypeScript files under `src/data/`:
+- `components.ts`: Component documentation and examples
+- `cli-commands.ts`: CLI command reference
+- `framework-guides.ts`: Framework setup and usage guides
+
+## Adding New Components
+
+To add documentation for a new component, edit `src/data/components.ts`:
+
+```typescript
+export const components: Record<string, any> = {
+  YourComponent: {
+    category: "display",
+    description: "Brief description",
+    props: "Props documentation...",
+    features: ["Feature 1", "Feature 2"],
+    bestPractices: ["Practice 1", "Practice 2"],
+    usage: "Basic usage example...",
+    examples: {
+      basic: "Basic example code...",
+      variants: "Variants example code...",
+      "with-icons": "Icon example code...",
+      interactive: "Interactive example code...",
+    },
+  },
+};
+```
+
+Then rebuild: `yarn build`
+
+## License
+
+MIT

package/dist/data/cli-commands.d.ts

@@ -0,0 +1,2 @@
+export declare const cliCommands: Record<string, any>;
+//# sourceMappingURL=cli-commands.d.ts.map

package/dist/data/cli-commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-commands.d.ts","sourceRoot":"","sources":["../../src/data/cli-commands.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAsG3C,CAAC"}

package/dist/data/cli-commands.js

@@ -0,0 +1,100 @@
+export const cliCommands = {
+    init: {
+        description: "Initialize a new Idealyst workspace with monorepo structure",
+        usage: "idealyst init <workspace-name> [options]",
+        options: [
+            {
+                flag: "workspace-name",
+                description: "Name for the new workspace (required)",
+            },
+            {
+                flag: "--git",
+                description: "Initialize git repository (default: true)",
+            },
+            {
+                flag: "--install",
+                description: "Install dependencies after creation (default: true)",
+            },
+        ],
+        examples: [
+            "idealyst init my-app",
+            "idealyst init my-company-workspace --no-git",
+        ],
+    },
+    create: {
+        description: "Create a new package within the Idealyst workspace",
+        usage: "idealyst create <name> --type <type> [options]",
+        options: [
+            {
+                flag: "name",
+                description: "Name for the new package (required)",
+            },
+            {
+                flag: "--type",
+                description: "Package type: web | native | api | database | shared (required)",
+            },
+            {
+                flag: "--app-name",
+                description: "Display name for native app (required for native type)",
+            },
+            {
+                flag: "--with-trpc",
+                description: "Include tRPC setup (for web/native)",
+            },
+            {
+                flag: "--no-trpc",
+                description: "Exclude tRPC setup (for web/native)",
+            },
+        ],
+        examples: [
+            "idealyst create web --type web --with-trpc",
+            "idealyst create mobile --type native --app-name \"My App\" --with-trpc",
+            "idealyst create api --type api",
+            "idealyst create database --type database",
+            "idealyst create shared --type shared",
+        ],
+    },
+    dev: {
+        description: "Start development server for a package",
+        usage: "cd packages/<name> && yarn dev",
+        options: [
+            {
+                flag: "--port",
+                description: "Port number for dev server (web only)",
+            },
+        ],
+        examples: [
+            "cd packages/web && yarn dev",
+            "cd packages/native && yarn dev",
+        ],
+    },
+    build: {
+        description: "Build a package for production",
+        usage: "cd packages/<name> && yarn build",
+        options: [],
+        examples: [
+            "cd packages/web && yarn build",
+            "cd packages/api && yarn build",
+        ],
+    },
+    test: {
+        description: "Run tests for packages",
+        usage: "yarn test [options]",
+        options: [
+            {
+                flag: "--watch",
+                description: "Run tests in watch mode",
+            },
+            {
+                flag: "--coverage",
+                description: "Generate coverage report",
+            },
+        ],
+        examples: [
+            "yarn test",
+            "yarn test:watch",
+            "yarn test:coverage",
+        ],
+    },
+};
+//# sourceMappingURL=cli-commands.js.map

package/dist/data/cli-commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-commands.js","sourceRoot":"","sources":["../../src/data/cli-commands.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,WAAW,GAAwB;IAC9C,IAAI,EAAE;QACJ,WAAW,EAAE,6DAA6D;QAC1E,KAAK,EAAE,0CAA0C;QACjD,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,gBAAgB;gBACtB,WAAW,EAAE,uCAAuC;aACrD;YACD;gBACE,IAAI,EAAE,OAAO;gBACb,WAAW,EAAE,2CAA2C;aACzD;YACD;gBACE,IAAI,EAAE,WAAW;gBACjB,WAAW,EAAE,qDAAqD;aACnE;SACF;QACD,QAAQ,EAAE;YACR,sBAAsB;YACtB,6CAA6C;SAC9C;KACF;IAED,MAAM,EAAE;QACN,WAAW,EAAE,oDAAoD;QACjE,KAAK,EAAE,gDAAgD;QACvD,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAM;gBACZ,WAAW,EAAE,qCAAqC;aACnD;YACD;gBACE,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,iEAAiE;aAC/E;YACD;gBACE,IAAI,EAAE,YAAY;gBAClB,WAAW,EAAE,wDAAwD;aACtE;YACD;gBACE,IAAI,EAAE,aAAa;gBACnB,WAAW,EAAE,qCAAqC;aACnD;YACD;gBACE,IAAI,EAAE,WAAW;gBACjB,WAAW,EAAE,qCAAqC;aACnD;SACF;QACD,QAAQ,EAAE;YACR,4CAA4C;YAC5C,wEAAwE;YACxE,gCAAgC;YAChC,0CAA0C;YAC1C,sCAAsC;SACvC;KACF;IAED,GAAG,EAAE;QACH,WAAW,EAAE,wCAAwC;QACrD,KAAK,EAAE,gCAAgC;QACvC,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,uCAAuC;aACrD;SACF;QACD,QAAQ,EAAE;YACR,6BAA6B;YAC7B,gCAAgC;SACjC;KACF;IAED,KAAK,EAAE;QACL,WAAW,EAAE,gCAAgC;QAC7C,KAAK,EAAE,kCAAkC;QACzC,OAAO,EAAE,EAAE;QACX,QAAQ,EAAE;YACR,+BAA+B;YAC/B,+BAA+B;SAChC;KACF;IAED,IAAI,EAAE;QACJ,WAAW,EAAE,wBAAwB;QACrC,KAAK,EAAE,qBAAqB;QAC5B,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,SAAS;gBACf,WAAW,EAAE,yBAAyB;aACvC;YACD;gBACE,IAAI,EAAE,YAAY;gBAClB,WAAW,EAAE,0BAA0B;aACxC;SACF;QACD,QAAQ,EAAE;YACR,WAAW;YACX,iBAAiB;YACjB,oBAAoB;SACrB;KACF;CACF,CAAC"}

package/dist/data/components/Accordion.d.ts

@@ -0,0 +1,15 @@
+export declare const Accordion: {
+    category: string;
+    description: string;
+    props: string;
+    features: string[];
+    bestPractices: string[];
+    usage: string;
+    examples: {
+        basic: string;
+        variants: string;
+        "with-icons": string;
+        interactive: string;
+    };
+};
+//# sourceMappingURL=Accordion.d.ts.map

package/dist/data/components/Accordion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Accordion.d.ts","sourceRoot":"","sources":["../../../src/data/components/Accordion.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,SAAS;;;;;;;;;;;;;CAiHrB,CAAC"}

package/dist/data/components/Accordion.js

@@ -0,0 +1,112 @@
+export const Accordion = {
+    category: "display",
+    description: "Expandable/collapsible content sections with support for single or multiple open items",
+    props: `
+- \`items\`: AccordionItem[] - Array of accordion items
+  - \`id\`: string - Unique identifier for the item
+  - \`title\`: string - Title text displayed in the header
+  - \`content\`: ReactNode - Content displayed when expanded
+  - \`disabled\`: boolean - Whether the item is disabled
+- \`allowMultiple\`: boolean - Allow multiple items to be expanded simultaneously (default: false)
+- \`defaultExpanded\`: string[] - Array of item IDs to expand by default
+- \`variant\`: 'default' | 'separated' | 'bordered' - Visual style variant
+- \`intent\`: 'primary' | 'neutral' | 'success' | 'error' | 'warning' - Color scheme
+- \`size\`: 'small' | 'medium' | 'large' - Size of accordion items
+- \`style\`: ViewStyle - Additional custom styles
+- \`testID\`: string - Test identifier
+`,
+    features: [
+        "Single or multiple item expansion modes",
+        "Default expanded items support",
+        "Three visual variants",
+        "Five intent colors",
+        "Three size options",
+        "Disabled item state",
+        "Controlled and uncontrolled modes",
+    ],
+    bestPractices: [
+        "Use 'default' variant for standard content organization",
+        "Use 'separated' variant for distinct sections",
+        "Set allowMultiple to true for FAQs where users may need to compare answers",
+        "Keep accordion titles concise and descriptive",
+        "Use defaultExpanded sparingly to avoid overwhelming users",
+    ],
+    usage: `
+import { Accordion } from '@idealyst/components';
+
+const items = [
+  {
+    id: '1',
+    title: 'What is Idealyst?',
+    content: <Text>Idealyst is a cross-platform React framework...</Text>,
+  },
+  {
+    id: '2',
+    title: 'How do I get started?',
+    content: <Text>Install the CLI and create a new project...</Text>,
+  },
+];
+
+<Accordion
+  items={items}
+  variant="bordered"
+  defaultExpanded={['1']}
+/>
+`,
+    examples: {
+        basic: `import { Accordion, Text } from '@idealyst/components';
+
+const items = [
+  { id: '1', title: 'Section 1', content: <Text>Content 1</Text> },
+  { id: '2', title: 'Section 2', content: <Text>Content 2</Text> },
+];
+
+<Accordion items={items} />`,
+        variants: `import { Accordion, Text } from '@idealyst/components';
+
+const items = [
+  { id: '1', title: 'Item', content: <Text>Content</Text> },
+];
+
+// Different variants
+<Accordion items={items} variant="default" />
+<Accordion items={items} variant="separated" />
+<Accordion items={items} variant="bordered" />`,
+        "with-icons": `import { Accordion, View, Icon, Text } from '@idealyst/components';
+
+const items = [
+  {
+    id: '1',
+    title: 'Account Settings',
+    content: (
+      <View spacing="sm">
+        <Icon name="account" size="md" />
+        <Text>Manage your account preferences</Text>
+      </View>
+    ),
+  },
+];
+
+<Accordion items={items} intent="primary" />`,
+        interactive: `import { Accordion, Text } from '@idealyst/components';
+import { useState } from 'react';
+
+function Example() {
+  const items = [
+    { id: '1', title: 'FAQ 1', content: <Text>Answer 1</Text> },
+    { id: '2', title: 'FAQ 2', content: <Text>Answer 2</Text> },
+    { id: '3', title: 'FAQ 3', content: <Text>Answer 3</Text> },
+  ];
+
+  return (
+    <Accordion
+      items={items}
+      allowMultiple
+      defaultExpanded={['1']}
+      variant="bordered"
+    />
+  );
+}`,
+    },
+};
+//# sourceMappingURL=Accordion.js.map

package/dist/data/components/Accordion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Accordion.js","sourceRoot":"","sources":["../../../src/data/components/Accordion.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,QAAQ,EAAE,SAAS;IACnB,WAAW,EAAE,wFAAwF;IACrG,KAAK,EAAE;;;;;;;;;;;;;CAaR;IACC,QAAQ,EAAE;QACR,yCAAyC;QACzC,gCAAgC;QAChC,uBAAuB;QACvB,oBAAoB;QACpB,oBAAoB;QACpB,qBAAqB;QACrB,mCAAmC;KACpC;IACD,aAAa,EAAE;QACb,yDAAyD;QACzD,+CAA+C;QAC/C,4EAA4E;QAC5E,+CAA+C;QAC/C,2DAA2D;KAC5D;IACD,KAAK,EAAE;;;;;;;;;;;;;;;;;;;;;CAqBR;IACC,QAAQ,EAAE;QACR,KAAK,EAAE;;;;;;;4BAOiB;QAExB,QAAQ,EAAE;;;;;;;;;+CASiC;QAE3C,YAAY,EAAE;;;;;;;;;;;;;;;6CAe2B;QAEzC,WAAW,EAAE;;;;;;;;;;;;;;;;;;EAkBf;KACC;CACF,CAAC"}

package/dist/data/components/ActivityIndicator.d.ts

@@ -0,0 +1,15 @@
+export declare const ActivityIndicator: {
+    category: string;
+    description: string;
+    props: string;
+    features: string[];
+    bestPractices: string[];
+    usage: string;
+    examples: {
+        basic: string;
+        variants: string;
+        "with-icons": string;
+        interactive: string;
+    };
+};
+//# sourceMappingURL=ActivityIndicator.d.ts.map

package/dist/data/components/ActivityIndicator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActivityIndicator.d.ts","sourceRoot":"","sources":["../../../src/data/components/ActivityIndicator.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;CAmF7B,CAAC"}

package/dist/data/components/ActivityIndicator.js

@@ -0,0 +1,82 @@
+export const ActivityIndicator = {
+    category: "feedback",
+    description: "Loading spinner/indicator for showing ongoing processes or loading states",
+    props: `
+- \`animating\`: boolean - Whether the indicator is animating/visible (default: true)
+- \`size\`: 'small' | 'medium' | 'large' | number - Size of the indicator (default: medium)
+- \`intent\`: 'primary' | 'neutral' | 'success' | 'error' | 'warning' - Color scheme (default: primary)
+- \`color\`: string - Custom color override (overrides intent)
+- \`style\`: ViewStyle - Additional custom styles
+- \`testID\`: string - Test identifier
+- \`hidesWhenStopped\`: boolean - Hide indicator when not animating (default: true)
+`,
+    features: [
+        "Animated loading spinner",
+        "Three predefined sizes plus custom numeric size",
+        "Five intent colors",
+        "Custom color support",
+        "Auto-hide when stopped",
+        "Cross-platform support",
+    ],
+    bestPractices: [
+        "Use 'primary' intent for general loading states",
+        "Use 'small' size for inline loading indicators",
+        "Use 'large' size for full-screen loading overlays",
+        "Always provide context about what is loading",
+        "Consider using with overlay for blocking operations",
+    ],
+    usage: `
+import { ActivityIndicator, View, Text } from '@idealyst/components';
+
+<View spacing="md">
+  <ActivityIndicator size="large" intent="primary" />
+  <Text>Loading data...</Text>
+</View>
+`,
+    examples: {
+        basic: `import { ActivityIndicator } from '@idealyst/components';
+
+<ActivityIndicator />`,
+        variants: `import { ActivityIndicator, View } from '@idealyst/components';
+
+<View spacing="md">
+  <ActivityIndicator size="small" />
+  <ActivityIndicator size="medium" />
+  <ActivityIndicator size="large" />
+  <ActivityIndicator size={48} />
+</View>`,
+        "with-icons": `import { ActivityIndicator, View, Text } from '@idealyst/components';
+
+<View spacing="sm" style={{ alignItems: 'center' }}>
+  <ActivityIndicator intent="success" size="large" />
+  <Text>Processing...</Text>
+</View>`,
+        interactive: `import { ActivityIndicator, Button, View, Text } from '@idealyst/components';
+import { useState } from 'react';
+
+function Example() {
+  const [loading, setLoading] = useState(false);
+
+  const handleLoad = async () => {
+    setLoading(true);
+    await new Promise(resolve => setTimeout(resolve, 2000));
+    setLoading(false);
+  };
+
+  return (
+    <View spacing="md">
+      <Button onPress={handleLoad} disabled={loading}>
+        Load Data
+      </Button>
+      {loading && (
+        <View spacing="sm" style={{ alignItems: 'center' }}>
+          <ActivityIndicator size="large" />
+          <Text>Loading...</Text>
+        </View>
+      )}
+    </View>
+  );
+}`,
+    },
+};
+//# sourceMappingURL=ActivityIndicator.js.map

package/dist/data/components/ActivityIndicator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActivityIndicator.js","sourceRoot":"","sources":["../../../src/data/components/ActivityIndicator.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,QAAQ,EAAE,UAAU;IACpB,WAAW,EAAE,2EAA2E;IACxF,KAAK,EAAE;;;;;;;;CAQR;IACC,QAAQ,EAAE;QACR,0BAA0B;QAC1B,iDAAiD;QACjD,oBAAoB;QACpB,sBAAsB;QACtB,wBAAwB;QACxB,wBAAwB;KACzB;IACD,aAAa,EAAE;QACb,iDAAiD;QACjD,gDAAgD;QAChD,mDAAmD;QACnD,8CAA8C;QAC9C,qDAAqD;KACtD;IACD,KAAK,EAAE;;;;;;;CAOR;IACC,QAAQ,EAAE;QACR,KAAK,EAAE;;sBAEW;QAElB,QAAQ,EAAE;;;;;;;QAON;QAEJ,YAAY,EAAE;;;;;QAKV;QAEJ,WAAW,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;EAyBf;KACC;CACF,CAAC"}

package/dist/data/components/Alert.d.ts

@@ -0,0 +1,15 @@
+export declare const Alert: {
+    category: string;
+    description: string;
+    props: string;
+    features: string[];
+    bestPractices: string[];
+    usage: string;
+    examples: {
+        basic: string;
+        variants: string;
+        "with-icons": string;
+        interactive: string;
+    };
+};
+//# sourceMappingURL=Alert.d.ts.map

package/dist/data/components/Alert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Alert.d.ts","sourceRoot":"","sources":["../../../src/data/components/Alert.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,KAAK;;;;;;;;;;;;;CAqIjB,CAAC"}