@idealyst/mcp-server

> Model Context Protocol server for the Idealyst Framework

Provides AI assistants like Claude Code with access to accurate, type-checked documentation and examples for Idealyst components, theme, and navigation.

Features

- 🔍 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

$3

``bash
npm install -g @idealyst/mcp-server
`

$3

`bash
npm install --save-dev @idealyst/mcp-server


or


yarn add -D @idealyst/mcp-server
`

Usage with Claude Code

$3

Add to your project's .mcp.json:

`json
{
"mcpServers": {
"idealyst": {
"command": "npx",
"args": ["@idealyst/mcp-server"]
}
}
}
`

$3

Add to ~/.config/claude-code/mcp_config.json:

`json
{
"mcpServers": {
"idealyst": {
"command": "idealyst-mcp"
}
}
}
`

$3

#### macOS/Linux

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

`json
{
"mcpServers": {
"idealyst": {
"command": "npx",
"args": ["@idealyst/mcp-server"]
}
}
}
`

#### Windows

Edit %APPDATA%\Claude\claude_desktop_config.json:

`json
{
"mcpServers": {
"idealyst": {
"command": "npx",
"args": ["@idealyst/mcp-server"]
}
}
}
`

Available Tools

$3

#### get_component_types

Get TypeScript type definitions for a component.

`typescript
{
component: "Button",
format: "both" // "typescript" | "json" | "both"
}
`

Returns the actual TypeScript interface and/or parsed JSON schema with prop details.

#### get_component_docs

Get comprehensive documentation for a component including props, usage, features, and best practices.

`typescript
{
component: "Button"
}
`

#### get_component_example

Get a specific example type for a component.

`typescript
{
component: "Button",
example_type: "basic" // "basic" | "variants" | "with-icons" | "interactive"
}
`

#### get_component_examples_ts

Get validated TypeScript examples that are guaranteed to compile.

`typescript
{
component: "Button"
}
`

#### 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"
}
`

$3

#### get_theme_types

Get all theme type definitions (Size, Intent, Color, etc.).

`typescript
{
format: "json" // "typescript" | "json" | "both"
}
`

$3

#### get_navigation_types

Get navigation type definitions for routers, navigators, and screens.

`typescript
{
format: "typescript" // "typescript" | "json" | "both"
}
`

$3

#### search_icons

Search through 7,447 Material Design Icons.

`typescript
{
query: "arrow",
limit: 20 // optional, default: 20
}
`

$3

#### get_cli_usage

Get information about Idealyst CLI commands.

`typescript
{
command: "init" // optional, omit for all commands
}
`

Type Extraction System

This MCP server uses a unique type-driven architecture to ensure documentation accuracy:

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 for detailed documentation.

Development

$3

`bash


Install dependencies

yarn install

Extract types from packages

yarn extract-types

Validate examples

yarn validate-examples

Build

yarn build

Run locally

yarn start
`

$3

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 (

Save

);
}
`

Then validate:

`bash
yarn validate-examples
`

$3

`
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

$3

- 🎯 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

$3

- 🚀 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, you can ask:

- "List all Idealyst components"
- "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 navigation types are available?"

Troubleshooting

$3

Run type extraction:
`bash
yarn extract-types
`

$3

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


`

$3

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 and TYPE-SYSTEM.md for technical details.

License

MIT

Links

- Idealyst Framework
- Model Context Protocol
- Claude Code