@idealyst/mcp-server 1.0.86 → 1.0.88

package/README.md

@@ -1,33 +1,68 @@
 # @idealyst/mcp-server
 
-Model Context Protocol (MCP) server providing documentation, examples, and usage instructions for the Idealyst framework.
+> Model Context Protocol server for the Idealyst Framework
 
-## What is this?
+Provides AI assistants like Claude Code with access to accurate, type-checked documentation and examples for Idealyst components, theme, and navigation.
 
-This MCP server allows AI assistants (like Claude) to access comprehensive documentation about the Idealyst framework, including:
+## Features
 
-- Component documentation and examples
-- CLI usage instructions
-- Framework setup guides
-- Best practices and patterns
+- 🔍 **Type-Driven Documentation**: Extract TypeScript types directly from source packages
+- ✅ **Validated Examples**: All examples are type-checked and guaranteed to compile
+- 🎨 **Theme Type Access**: Get Size, Intent, Color, and other theme types
+- 🧭 **Navigation Types**: Access to routing and navigator type definitions
+- 🔎 **Icon Search**: Search through 7,447 Material Design Icons
+- 📚 **Component Docs**: Detailed documentation with props, usage, and best practices
 
 ## Installation
 
-```bash
-# From the Idealyst monorepo
-cd packages/mcp-server
-yarn install
-yarn build
+### Global Installation
 
-# Or install globally
+```bash
 npm install -g @idealyst/mcp-server
 ```
 
-## Usage with Claude Desktop
+### Project Installation
+
+```bash
+npm install --save-dev @idealyst/mcp-server
+# or
+yarn add -D @idealyst/mcp-server
+```
+
+## Usage with Claude Code
+
+### Project-Level Configuration
+
+Add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "idealyst": {
+      "command": "npx",
+      "args": ["@idealyst/mcp-server"]
+    }
+  }
+}
+```
+
+### User-Level Configuration
+
+Add to `~/.config/claude-code/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "idealyst": {
+      "command": "idealyst-mcp"
+    }
+  }
+}
+```
 
-Add this server to your Claude Desktop configuration:
+### Claude Desktop Configuration
 
-### macOS/Linux
+#### macOS/Linux
 
 Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
@@ -35,16 +70,14 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
 {
   "mcpServers": {
     "idealyst": {
-      "command": "node",
-      "args": [
-        "/absolute/path/to/idealyst-framework/packages/mcp-server/dist/index.js"
-      ]
+      "command": "npx",
+      "args": ["@idealyst/mcp-server"]
     }
   }
 }
 ```
 
-### Windows
+#### Windows
 
 Edit `%APPDATA%\Claude\claude_desktop_config.json`:
 
@@ -52,151 +85,306 @@ Edit `%APPDATA%\Claude\claude_desktop_config.json`:
 {
   "mcpServers": {
     "idealyst": {
-      "command": "node",
-      "args": [
-        "C:\\path\\to\\idealyst-framework\\packages\\mcp-server\\dist\\index.js"
-      ]
+      "command": "npx",
+      "args": ["@idealyst/mcp-server"]
     }
   }
 }
 ```
 
-After adding the configuration, restart Claude Desktop.
-
 ## Available Tools
 
-### list_components
+### Component Tools
 
-List all available Idealyst components with brief descriptions.
+#### `get_component_types`
 
-**Example:**
-```
-List all Idealyst components
+Get TypeScript type definitions for a component.
+
+```typescript
+{
+  component: "Button",
+  format: "both" // "typescript" | "json" | "both"
+}
 ```
 
-### get_component_docs
+Returns the actual TypeScript interface and/or parsed JSON schema with prop details.
 
-Get detailed documentation for a specific component including props, usage, and examples.
+#### `get_component_docs`
 
-**Parameters:**
-- `component` (string): Component name (e.g., 'Button', 'Card', 'Input')
+Get comprehensive documentation for a component including props, usage, features, and best practices.
 
-**Example:**
-```
-Get documentation for the Button component
+```typescript
+{
+  component: "Button"
+}
 ```
 
-### get_component_example
+#### `get_component_example`
 
-Get code examples for a specific component.
+Get a specific example type for a component.
 
-**Parameters:**
-- `component` (string): Component name
-- `example_type` (optional): 'basic', 'variants', 'with-icons', or 'interactive'
+```typescript
+{
+  component: "Button",
+  example_type: "basic" // "basic" | "variants" | "with-icons" | "interactive"
+}
+```
 
-**Example:**
+#### `get_component_examples_ts`
+
+Get validated TypeScript examples that are guaranteed to compile.
+
+```typescript
+{
+  component: "Button"
+}
 ```
-Show me an interactive example of the Dialog component
+
+#### `list_components`
+
+List all available Idealyst components with descriptions.
+
+#### `search_components`
+
+Search for components by name, category, or feature.
+
+```typescript
+{
+  query: "form",
+  category: "form" // optional: "layout" | "form" | "display" | "navigation" | "overlay" | "data"
+}
 ```
 
-### get_cli_usage
+### Theme Tools
 
-Get information about Idealyst CLI commands.
+#### `get_theme_types`
 
-**Parameters:**
-- `command` (optional): Specific CLI command
+Get all theme type definitions (Size, Intent, Color, etc.).
 
-**Example:**
+```typescript
+{
+  format: "json" // "typescript" | "json" | "both"
+}
 ```
-How do I use the Idealyst CLI to create a new web app?
+
+### Navigation Tools
+
+#### `get_navigation_types`
+
+Get navigation type definitions for routers, navigators, and screens.
+
+```typescript
+{
+  format: "typescript" // "typescript" | "json" | "both"
+}
 ```
 
-### search_components
+### Icon Tools
 
-Search for components by name, category, or feature.
+#### `search_icons`
 
-**Parameters:**
-- `query` (optional): Search query
-- `category` (optional): Filter by category ('layout', 'form', 'display', 'navigation', 'overlay', 'data')
+Search through 7,447 Material Design Icons.
 
-**Example:**
+```typescript
+{
+  query: "arrow",
+  limit: 20 // optional, default: 20
+}
 ```
-Search for form components in Idealyst
+
+### CLI Tools
+
+#### `get_cli_usage`
+
+Get information about Idealyst CLI commands.
+
+```typescript
+{
+  command: "init" // optional, omit for all commands
+}
 ```
 
-## Available Resources
+## Type Extraction System
 
-The server also provides framework guides as resources:
+This MCP server uses a unique **type-driven architecture** to ensure documentation accuracy:
 
-- **Getting Started**: Complete setup guide
-- **Components Overview**: All available components organized by category
-- **Theming Guide**: Customizing themes
-- **CLI Reference**: Complete CLI documentation
+1. **Extract Types**: Parse TypeScript from `@idealyst/components`, `@idealyst/theme`, `@idealyst/navigation`
+2. **Validate Examples**: Type-check all examples against extracted types
+3. **Serve Types**: Provide both raw TypeScript and JSON schema via MCP tools
+
+See [TYPE-SYSTEM.md](./TYPE-SYSTEM.md) for detailed documentation.
 
 ## Development
 
+### Setup
+
 ```bash
 # Install dependencies
 yarn install
 
+# Extract types from packages
+yarn extract-types
+
+# Validate examples
+yarn validate-examples
+
 # Build
 yarn build
 
-# Watch mode
-yarn dev
+# Run locally
+yarn start
+```
+
+### Adding Examples
 
-# Test the server
-node dist/index.js
+Create TypeScript example files in `examples/components/`:
+
+```typescript
+// examples/components/Button.examples.tsx
+import React from 'react';
+import { Button } from '@idealyst/components';
+
+export function BasicButton() {
+  return (
+    <Button type="contained" intent="primary">
+      Save
+    </Button>
+  );
+}
+```
+
+Then validate:
+
+```bash
+yarn validate-examples
 ```
 
+### Project Structure
+
+```
+packages/mcp-server/
+├── src/
+│   ├── index.ts              # MCP server entry point
+│   ├── tools/                # MCP tool implementations
+│   │   └── get-types.ts      # Type extraction tools
+│   ├── data/                 # Component documentation
+│   │   ├── components/       # Component docs
+│   │   ├── cli-commands.ts   # CLI documentation
+│   │   └── framework-guides.ts
+│   └── generated/            # Auto-generated (gitignored)
+│       └── types.json        # Extracted types
+├── scripts/
+│   ├── extract-types.ts      # Type extraction script
+│   ├── type-extractor.ts     # Extraction utilities
+│   └── validate-examples.ts  # Example validation
+├── examples/
+│   └── components/           # Type-checked examples
+│       ├── Button.examples.tsx
+│       ├── Card.examples.tsx
+│       └── ...
+├── ARCHITECTURE.md           # System architecture
+├── TYPE-SYSTEM.md           # Type system documentation
+└── package.json
+```
+
+## Build Process
+
+The build includes type extraction and validation:
+
+```json
+{
+  "scripts": {
+    "prebuild": "yarn extract-types && yarn validate-examples",
+    "build": "tsc && chmod +x dist/index.js"
+  }
+}
+```
+
+This ensures:
+- ✅ Types are up-to-date
+- ✅ Examples are valid
+- ✅ Build fails if examples have type errors
+
+## Resources
+
+The server also provides markdown resources accessible via MCP:
+
+- `idealyst://framework/getting-started` - Getting started guide
+- `idealyst://framework/components-overview` - Components overview
+- `idealyst://framework/theming` - Theming guide
+- `idealyst://framework/cli` - CLI reference
+- `idealyst://navigation/overview` - Navigation system overview
+- `idealyst://navigation/route-configuration` - Route configuration
+- `idealyst://navigation/navigator-types` - Navigator types guide
+- `idealyst://icons/reference` - Icon reference with common icons
+
+## Benefits
+
+### For AI Assistants
+- 🎯 **Accurate Types**: Get exact TypeScript interfaces from source
+- ✅ **Validated Examples**: Examples guaranteed to compile
+- 📊 **Multiple Formats**: TypeScript and JSON schema formats
+- 🔄 **Always Updated**: Types extracted from actual packages
+
+### For Developers
+- 🚀 **Fast Development**: AI generates correct code on first try
+- 📖 **Reliable Docs**: Documentation always matches reality
+- 🔍 **Easy Discovery**: Search components, icons, and types
+- 💡 **Best Practices**: Built-in guidance and examples
+
 ## Example Queries for Claude
 
-Once the MCP server is connected to Claude, you can ask questions like:
+Once the MCP server is connected, you can ask:
 
 - "List all Idealyst components"
-- "Show me how to use the Button component with icons"
+- "Get the TypeScript types for the Button component"
+- "Show me validated examples for the Card component"
+- "What are the available Size values in the theme?"
+- "Search for arrow 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?"
+- "What navigation types are available?"
 
-## Architecture
+## Troubleshooting
 
-The server exposes:
+### "Types file not found" Error
 
-- **Tools**: Callable functions for querying component docs, examples, and CLI usage
-- **Resources**: Static framework guides and documentation
+Run type extraction:
+```bash
+yarn extract-types
+```
 
-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
+### Examples Have Type Errors
 
-## Adding New Components
+This means the examples don't match the current types (which is good - we caught it!):
+```bash
+yarn validate-examples  # See errors
+# Fix examples, then re-validate
+```
 
-To add documentation for a new component, edit `src/data/components.ts`:
+### Types Are Out of Date
 
-```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`
+Re-extract after changing component packages:
+```bash
+yarn extract-types
+yarn build
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Add/update examples with type validation
+4. Run `yarn validate-examples`
+5. Submit a pull request
+
+See [ARCHITECTURE.md](./ARCHITECTURE.md) and [TYPE-SYSTEM.md](./TYPE-SYSTEM.md) for technical details.
 
 ## License
 
 MIT
+
+## Links
+
+- [Idealyst Framework](https://github.com/IdealystIO/idealyst-framework)
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [Claude Code](https://code.claude.com/)