@trimble-oss/modus-mcp-server/README.md

An MCP server providing information about Modus React form and UI components

# Modus MCP Server

An MCP (Model Context Protocol) server providing comprehensive information about Modus Design System React components, including properties, events, usage examples, and installation guidelines.

## Features

- 🎨 **Complete Component Library**: Access to all Modus 2.0 Web Components
- 📚 **Rich Documentation**: Properties, events, methods, and usage examples
- 🔍 **Icon Search**: Search through Modus icon library with prefix filtering
- 📖 **Installation Guidelines**: Step-by-step setup instructions
- 🚀 **stdio Transport**: Optimized for local MCP client integration

## Installation

### Global Installation (Recommended)

```bash
npm install -g modus-mcp-server
```

### Local Installation

```bash
npm install modus-mcp-server
```

## Usage

### With Claude Desktop

Add the following configuration to your IDE :

```json
{
  "mcpServers": {
    "modus-components": {
      "command": "npx",
      "args": ["-y", "modus-mcp-server@latest"]
    }
  }
}
```

**Alternative for Windows (if npx doesn't work):**
```json
{
  "mcpServers": {
    "modus-components": {
      "command": "node",
      "args": ["-p", "require('modus-mcp-server/dist/index.js')"]
    }
  }
}
```

### Manual Execution

```bash
# If installed globally
modus-mcp-server

# If installed locally
npx modus-mcp-server
```

## Available Tools

### 1. `getting_started_guidelines`
Get comprehensive installation and setup guidelines for Modus components.

**Usage:**
```
Use the getting_started_guidelines tool to get setup instructions.
```

### 2. `get_list_of_all_modus_components`
Retrieve a complete list of all available Modus components.

**Usage:**
```
Use get_list_of_all_modus_components to see all available components.
```

### 3. `get_component_details`
Get detailed information about a specific component including properties, events, and usage examples.

**Parameters:**
- `component_name` (required): The name of the Modus component
- `framework` (optional): Target framework ('react' or 'angular', defaults to 'react')

**Usage:**
```
Use get_component_details with component_name "ModusWcButton" to get button component details.
```

### 4. `get_modus_icons_by_char`
Search for Modus icons by character prefix.

**Parameters:**
- `char_prefix` (optional): Character prefix to filter icons (e.g., "arrow", "check")

**Usage:**
```
Use get_modus_icons_by_char with char_prefix "arrow" to find arrow-related icons.
```

## Development

### Building from Source

```bash
# Clone the repository
git clone https://github.com/your-org/modus-mcp-server
cd modus-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev
```

### Project Structure

```
modus-mcp-server/
├── src/
│   ├── index.ts              # Main MCP server
│   └── modules/
│       └── component-registry.ts  # Component data management
├── knowledge-base/           # Modus component documentation
│   ├── modus2_components.json
│   ├── modus2_react_KB.md
│   ├── modus_icons.json
│   └── Modus2_guidelines.md
├── dist/                     # Compiled JavaScript
├── package.json
└── tsconfig.json
```

## Configuration

The server uses stdio transport for seamless integration with MCP clients like Claude Desktop. No additional configuration is required for basic usage.

## Troubleshooting

### Common Issues

1. **Command not found**: Ensure the package is installed globally or use `npx`
2. **Permission errors**: On Unix systems, you may need to run with appropriate permissions
3. **Path issues**: The server automatically resolves knowledge base paths relative to the package installation

### Debug Mode

The server outputs debug information to stderr, which won't interfere with MCP communication but can help with troubleshooting:

```bash
modus-mcp-server 2> debug.log
```

## License

MIT License - see LICENSE file for details.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## Support

For issues and questions:
- GitHub Issues: [Create an issue](https://github.com/trimble-oss/modus2-p2c-agent/issues)
- Modus Design System: [Official Documentation](https://modus.trimble.com/)

## Changelog

### v1.0.1

- **Critical Fix**: Resolved MCP protocol initialization error
- Improved schema validation with `additionalProperties: false`
- Improved the Readme file.
- Fixed the Knowledge Base Modus Card error

### v1.0.0

- Initial release
- stdio transport support
- Complete Modus 2.0 component library
- Icon search functionality
- Installation guidelines