tremor-ui-mcp-server/CONTRIBUTING.md

A Model Context Protocol (MCP) server providing AI assistants with access to Tremor UI components, blocks, and templates for React dashboard development

# Contributing to Tremor UI MCP Server

Thank you for your interest in contributing to the Tremor UI MCP Server! This document provides guidelines and information for contributors.

## Development Setup

### Prerequisites

- Node.js 18 or higher
- npm or yarn package manager
- Git
- GitHub Personal Access Token (optional, for enhanced API limits)

### Getting Started

1. **Fork and Clone**
   ```bash
   git clone https://github.com/your-username/tremor-ui-mcp-server.git
   cd tremor-ui-mcp-server
   ```

2. **Install Dependencies**
   ```bash
   npm install
   ```

3. **Create Environment File**
   ```bash
   cp .env.example .env
   # Add your GitHub token if available
   echo "GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here" >> .env
   ```

4. **Build the Project**
   ```bash
   npm run build
   ```

5. **Run Tests**
   ```bash
   npm test
   ```

6. **Start Development Server**
   ```bash
   npm run dev
   ```

### Development Commands

| Command | Description |
|---------|-------------|
| `npm run build` | Compile TypeScript to JavaScript |
| `npm run dev` | Start development server with hot reload |
| `npm test` | Run the test suite |
| `npm run start` | Start the production server |
| `npm run lint` | Run ESLint for code quality |
| `npm run format` | Format code with Prettier |

### Testing Your Changes

1. **Unit Tests**
   ```bash
   npm test
   ```

2. **Integration Testing**
   ```bash
   # Test with actual MCP client
   echo '{"method": "tools/list", "params": {}}' | node dist/index.js
   ```

3. **Manual Testing**
   ```bash
   # Test specific tools
   npx @tremor-ui/mcp-server --help
   ```

## Project Structure

```
tremor-ui-mcp-server/
├── src/
│   ├── index.ts              # Main server entry point
│   ├── services/
│   │   ├── github.ts         # GitHub API service
│   │   └── tremor.ts         # Tremor UI service logic
│   └── types/
│       └── index.ts          # TypeScript type definitions
├── dist/                     # Compiled JavaScript output
├── tests/                    # Test files
├── package.json              # Project configuration
├── tsconfig.json            # TypeScript configuration
├── README.md                # Main documentation
└── CONTRIBUTING.md          # This file
```

## Making Changes

### Branching Strategy

1. **Create a Feature Branch**
   ```bash
   git checkout -b feature/your-feature-name
   ```

2. **Branch Naming Convention**
   - `feature/` - New features
   - `fix/` - Bug fixes
   - `docs/` - Documentation updates
   - `refactor/` - Code refactoring
   - `test/` - Test improvements

### Code Style

- **TypeScript**: Use strict TypeScript with proper type definitions
- **Formatting**: We use Prettier for code formatting
- **Linting**: ESLint for code quality
- **Naming**: Use camelCase for variables and functions, PascalCase for classes

### Adding New Components

To add support for a new Tremor component:

1. **Update the Component Registry** in `src/services/tremor.ts`:
   ```typescript
   'NewComponent': {
     name: 'NewComponent',
     description: 'Description of the new component',
     category: 'CategoryName',
     props: [
       { name: 'propName', type: 'string', required: true, description: 'Prop description' }
     ],
     dependencies: ['@tremor/react', 'react']
   }
   ```

2. **Add Tests** in `tests/` directory:
   ```typescript
   describe('NewComponent', () => {
     it('should return component information', async () => {
       // Test implementation
     });
   });
   ```

3. **Update Documentation** in README.md if needed

### Adding New Tools

To add a new MCP tool:

1. **Define the Tool** in `src/index.ts` in the `ListToolsRequestSchema` handler
2. **Implement the Handler** in the `CallToolRequestSchema` handler
3. **Add Service Method** in `src/services/tremor.ts` if needed
4. **Add Tests** for the new functionality
5. **Update Documentation** in README.md

## Testing Guidelines

### Writing Tests

- Place tests in the `tests/` directory
- Use descriptive test names
- Test both success and error cases
- Mock external dependencies (GitHub API)

### Test Structure

```typescript
import { TremorService } from '../src/services/tremor';

describe('TremorService', () => {
  let service: TremorService;

  beforeEach(() => {
    service = new TremorService();
  });

  it('should list components', async () => {
    const components = await service.listComponents();
    expect(components).toBeDefined();
    expect(Array.isArray(components)).toBe(true);
  });
});
```

## Documentation

### README Updates

When making changes that affect usage:

1. Update relevant sections in README.md
2. Add new examples if applicable
3. Update the tools documentation
4. Ensure all links work correctly

### Code Documentation

- Use JSDoc comments for functions and classes
- Document complex logic with inline comments
- Keep comments up-to-date with code changes

## Pull Request Process

### Before Submitting

1. **Run Tests**
   ```bash
   npm test
   ```

2. **Build Successfully**
   ```bash
   npm run build
   ```

3. **Check Code Quality**
   ```bash
   npm run lint
   npm run format
   ```

4. **Update Documentation** if needed

### PR Requirements

- Clear, descriptive title
- Detailed description of changes
- Link to related issues
- Tests pass
- Code follows style guidelines
- Documentation updated if needed

### PR Template

```markdown
## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Refactoring

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed

## Documentation
- [ ] README updated
- [ ] Code comments added
- [ ] Examples updated

## Related Issues
Fixes #issue_number
```

## Release Process

### Versioning

We follow [Semantic Versioning (SemVer)](https://semver.org/):

- **MAJOR**: Incompatible API changes
- **MINOR**: Backward compatible functionality additions
- **PATCH**: Backward compatible bug fixes

### Release Checklist

1. Update version in `package.json`
2. Update CHANGELOG.md
3. Create release notes
4. Tag the release
5. Publish to npm

## Getting Help

### Community

- **GitHub Issues**: Report bugs or request features
- **Discussions**: Ask questions or share ideas
- **Discord**: Join the Tremor community

### Resources

- [Tremor UI Documentation](https://tremor.so/docs)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [TypeScript Documentation](https://www.typescriptlang.org/docs/)

## Code of Conduct

### Our Standards

- Be respectful and inclusive
- Focus on constructive feedback
- Help others learn and grow
- Maintain professionalism

### Enforcement

Violations of the code of conduct should be reported to the maintainers.

## Recognition

Contributors will be:

- Listed in the README.md
- Mentioned in release notes
- Given credit in commit messages

## License

By contributing, you agree that your contributions will be licensed under the MIT License.

---

Thank you for contributing to Tremor UI MCP Server! 🎉