npm package: @sproutsocial/seeds-mcp-server
Description: Model Context Protocol server for the Seeds Design System - provides AI assistance for component migrations and design system knowledge
Author: Sprout Social, Inc.
Latest version: 1.0.0

# Seeds Design System MCP Server

A Model Context Protocol (MCP) server that provides AI assistance for the Seeds Design System. This server enables engineers to get intelligent help with component migrations, usage guidance, and design system knowledge.

## Features

- **Component Migration Assistance**: Automatically analyze deprecated components and provide migration paths to newer versions
- **Component Search & Discovery**: Find components by name, functionality, or use case
- **Detailed Usage Information**: Get comprehensive documentation, props, examples, and best practices for any component
- **Real-time Component Analysis**: Access live component metadata and documentation
- **Migration Planning**: Generate step-by-step migration plans for complex component updates

## Installation

### Manual Installation

To install the Seeds MCP Server, you'll need to manually clone the repository and build it:

```bash
# Clone the Seeds repository
git clone https://github.com/sproutsocial/seeds-packets.git
cd seeds-packets/seeds-tooling/seeds-mcp-server

# Install dependencies and build
yarn install
yarn build
```

### Connecting to Claude Desktop

Add the following to your Claude Desktop MCP configuration. You'll need to update the path to point to your cloned version of the Seeds repository:

```json
{
  "mcpServers": {
    "seeds-design-system": {
      "command": "node",
      "args": [
        "/path/to/your/seeds-packets/seeds-tooling/seeds-mcp-server/dist/index.js",
        "--seeds-root",
        "/path/to/your/seeds-packets"
      ],
      "env": {}
    }
  }
}
```

**Example with actual paths:**
```json
{
  "mcpServers": {
    "seeds-design-system": {
      "command": "node",
      "args": [
        "/Users/ozzy/code/seeds/seeds-tooling/seeds-mcp-server/dist/index.js",
        "--seeds-root",
        "/Users/ozzy/code/seeds"
      ],
      "env": {}
    }
  }
}
```

### Connecting to Other MCP Clients

The server uses stdio transport and follows the MCP specification, making it compatible with any MCP client. Use the same configuration format as shown above, adapting the paths to your specific setup.

## Available Tools

### 🔄 `migrate_component`
Analyze React code and provide migration assistance for deprecated Seeds components.

**Parameters:**
- `code` (required): React code snippet to analyze
- `sourceComponent` (optional): Specific deprecated component to migrate from
- `targetComponent` (optional): Specific component to migrate to

**Example:**
```
Migrate this menu code:
<Menu>
  <Menu.Group title="Actions">
    <Menu.Item onClick={handleEdit}>Edit</Menu.Item>
    <Menu.Item onClick={handleDelete}>Delete</Menu.Item>
  </Menu.Group>
</Menu>
```

### 🔍 `search_components`
Search for Seeds components by name, functionality, or use case.

**Parameters:**
- `query` (required): Search term (e.g., "button", "menu", "form input")
- `includeDeprecated` (optional): Include deprecated components in results
- `includeExamples` (optional): Include code examples in results

**Example:**
```
Search for form input components
```

### 📖 `get_component_usage`
Get comprehensive usage information for a specific Seeds component.

**Parameters:**
- `componentName` (required): Name of the component (e.g., "Button", "Avatar")
- `includeAllExamples` (optional): Include all available examples
- `includeAdvancedUsage` (optional): Include advanced patterns and recipes

**Example:**
```
Show me how to use the Button component
```

## Available Resources

### 📦 Component Resources
- `seeds://components/all` - All Seeds components with metadata
- `seeds://components/current` - Current (non-deprecated) components
- `seeds://components/deprecated` - Deprecated components and replacements

### 📚 Documentation Resources
- `seeds://documentation/all` - Complete design system documentation
- `seeds://migration/mappings` - Component migration mappings

## Common Use Cases

### 1. Migrating Deprecated Components

```
I have this old menu code that needs to be updated:

<MenuButton content={<Menu>...</Menu>}>
  Open Menu
</MenuButton>

Can you help me migrate it to the new menu system?
```

### 2. Finding the Right Component

```
I need a component for user profile pictures. What's available in Seeds?
```

### 3. Learning Component Usage

```
How do I use the new ActionMenu component? Show me examples and props.
```

### 4. Understanding Migration Paths

```
What's the migration path from the old Menu component to the new menu system?
```

## Development

### Building

```bash
yarn build
```

### Development Mode

```bash
yarn dev
```

### Testing

```bash
yarn test
```

### Linting

```bash
yarn lint
yarn lint:fix
```

## Configuration

The server automatically detects the Seeds repository location, but you can override it:

```bash
seeds-mcp-server --seeds-root /custom/path/to/seeds
```

## Architecture

The MCP server is built with a modular architecture:

- **Analyzers**: Parse and analyze components and documentation
  - `ComponentAnalyzer`: Extracts component metadata from source code
  - `DocumentationAnalyzer`: Parses MDX documentation files
  - `MigrationAnalyzer`: Generates migration mappings and guidance

- **Tools**: Provide AI-callable functions for specific tasks
  - `MigrationTool`: Component migration assistance
  - `ComponentSearchTool`: Component discovery and search
  - `ComponentUsageTool`: Detailed component usage information

- **Resources**: Expose structured data for AI context
  - `ComponentResource`: Component metadata and documentation

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Support

For issues and questions:

- [GitHub Issues](https://github.com/sproutsocial/seeds-packets/issues)
- [Seeds Documentation](https://seeds.sproutsocial.com)
- [MCP Documentation](https://modelcontextprotocol.io)

## License

MIT © Sprout Social, Inc.