# Contributing to SmartSuite MCP Server
Thank you for your interest in contributing! This document provides guidelines and instructions for contributing to the project.
## Table of Contents
1. [Code of Conduct](#code-of-conduct)
2. [Getting Started](#getting-started)
3. [Development Workflow](#development-workflow)
4. [Code Standards](#code-standards)
5. [Testing Requirements](#testing-requirements)
6. [Commit Guidelines](#commit-guidelines)
7. [Pull Request Process](#pull-request-process)
8. [Project Structure](#project-structure)
---
## Code of Conduct
### Our Standards
- Be respectful and inclusive
- Welcome newcomers and help them learn
- Focus on what is best for the community
- Show empathy towards other contributors
### Unacceptable Behavior
- Harassment, discrimination, or trolling
- Publishing others' private information
- Unprofessional or unwelcome conduct
---
## Getting Started
### Prerequisites
- Node.js 18.x or higher (20.x recommended)
- npm 10.x or higher
- Git
- TypeScript knowledge
- Familiarity with MCP protocol (helpful)
### Initial Setup
```bash
# Fork and clone repository
git clone https://github.com/YOUR_USERNAME/smartsuite-mcp.git
cd smartsuite-mcp
# Add upstream remote
git remote add upstream https://github.com/elevanaltd/smartsuite-mcp.git
# Install dependencies
npm install
# Create .env from template
cp .env.example .env
# Edit .env with your test credentials
# Run quality gates
npm run quality-gates
# Build project
npm run build
# Run tests
npm test
```
---
## Development Workflow
### 1. Create Feature Branch
```bash
# Update main branch
git checkout main
git pull upstream main
# Create feature branch
git checkout -b feature/your-feature-name
# Or for bug fixes
git checkout -b fix/issue-description
```
### 2. Make Changes
```bash
# Run in development mode (hot reload)
npm run dev
# Make your changes...
# Test continuously
npm run test:watch
```
### 3. Before Committing
```bash
# Run all quality gates
npm run quality-gates
# This runs:
# - npm run lint (ESLint)
# - npm run typecheck (TypeScript)
# - npm run test:ci (Unit tests)
# All three MUST pass before committing
```
### 4. Commit Changes
```bash
# Stage changes
git add .
# Commit with descriptive message
git commit -m "feat: add new field validation"
# Pre-commit hooks will run automatically
# (lint-staged + quality checks)
```
### 5. Push and Create PR
```bash
# Push to your fork
git push origin feature/your-feature-name
# Create Pull Request on GitHub
# Fill out PR template completely
```
---
## Code Standards
### TypeScript
- **Strict Mode**: All code must pass `strict: true`
- **No Implicit Any**: Explicit types required
- **Null Safety**: Use strict null checks
```typescript
// ✅ GOOD
function processRecord(id: string): Promise<Record<string, unknown>> {
return client.getRecord(id);
}
// ❌ BAD
function processRecord(id) { // Missing types
return client.getRecord(id);
}
```
### ESLint
- Follow `.eslintrc.cjs` configuration
- No warnings allowed in production code
- Use `eslint-disable` comments sparingly with justification
```typescript
// ✅ GOOD - Justified disable
// eslint-disable-next-line no-console -- MCP lifecycle logging to stderr
console.error('Server starting...');
// ❌ BAD - Blanket disable
/* eslint-disable */
```
### Naming Conventions
- **Files**: `kebab-case.ts` (e.g., `smartsuite-client.ts`)
- **Classes**: `PascalCase` (e.g., `SmartSuiteClient`)
- **Functions**: `camelCase` (e.g., `getRecords`)
- **Constants**: `UPPER_SNAKE_CASE` (e.g., `DEFAULT_LIMIT`)
- **Interfaces**: `PascalCase` (e.g., `ToolSchema`)
### Code Organization
```typescript
// 1. Imports (grouped and sorted)
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import type { SmartSuiteClient } from '../core/smartsuite-client.js';
// 2. Type definitions
interface ToolConfig {
name: string;
handler: Function;
}
// 3. Constants
const DEFAULT_TIMEOUT = 30000;
// 4. Functions (exported first)
export function createTool(config: ToolConfig): Tool {
// Implementation
}
// 5. Helper functions (internal)
function validateConfig(config: ToolConfig): boolean {
// Implementation
}
```
---
## Testing Requirements
### Test Coverage
- **Minimum**: 80% code coverage
- **Target**: 98% (per vitest.config.ts)
- All new features MUST include tests
### Test Structure
```typescript
describe('FeatureName', () => {
describe('functionName', () => {
it('should handle normal case', () => {
// Arrange
const input = 'test';
// Act
const result = functionName(input);
// Assert
expect(result).toBe('expected');
});
it('should handle error case', () => {
expect(() => functionName(null)).toThrow('Expected error');
});
});
});
```
### Running Tests
```bash
# Run all tests
npm test
# Run with coverage
npm run test:coverage
# Run specific file
npm test -- test/unit/core/smartsuite-client.test.ts
# Watch mode
npm run test:watch
# Unit tests only (CI)
npm run test:ci
```
### Test Categories
1. **Unit Tests**: Test individual functions/classes
2. **Integration Tests**: Test component interactions
3. **Contract Tests**: Verify behavioral contracts
---
## Commit Guidelines
### Conventional Commits
We use [Conventional Commits](https://www.conventionalcommits.org/) for clear changelog generation.
**Format**: `<type>(<scope>): <subject>`
### Types
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `style`: Code formatting (no logic change)
- `refactor`: Code restructuring (no behavior change)
- `test`: Adding or updating tests
- `chore`: Build process or tooling changes
- `perf`: Performance improvements
### Examples
```bash
# Feature
git commit -m "feat(query): add count operation support"
# Bug fix
git commit -m "fix(client): handle 429 rate limit errors correctly"
# Documentation
git commit -m "docs(api): add filtering examples to API.md"
# Breaking change
git commit -m "feat(tools)!: remove deprecated undo tool
BREAKING CHANGE: The undo tool has been removed as SmartSuite API does not support rollback operations."
# Multiple files
git commit -m "refactor(handlers): extract common validation logic"
```
### Commit Message Rules
- Use imperative mood ("add" not "added")
- First line max 72 characters
- Blank line before detailed description
- Reference issues: "Fixes #123" or "Relates to #456"
---
## Pull Request Process
### PR Checklist
- [ ] Branch is up to date with main
- [ ] All tests passing (`npm run quality-gates`)
- [ ] No ESLint warnings
- [ ] No TypeScript errors
- [ ] Test coverage maintained or improved
- [ ] Documentation updated
- [ ] CHANGELOG.md updated (if applicable)
- [ ] Commits follow conventional commit format
### PR Template
```markdown
## Description
Brief description of changes
## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update
## Testing
Describe testing performed
## Checklist
- [ ] Code follows style guidelines
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] Quality gates pass
```
### Review Process
1. **Automated Checks**: CI must pass
2. **Code Review**: At least one approval required
3. **Testing**: Reviewer tests functionality
4. **Documentation**: Verify docs are complete
5. **Merge**: Squash and merge with clean commit message
### After Merge
- Delete feature branch
- Update local main: `git pull upstream main`
- Close related issues
---
## Project Structure
```
smartsuite-mcp/
├── src/ # Source code
│ ├── index.ts # Entry point
│ ├── core/ # Core functionality
│ │ ├── smartsuite-client.ts
│ │ └── field-translator.ts
│ ├── mcp/ # MCP server layer
│ │ ├── server.ts
│ │ └── tools.ts
│ └── operations/ # Operation handlers
│ ├── query-handler.ts
│ ├── record-handler.ts
│ └── ...
├── test/ # Test files
│ ├── unit/ # Unit tests
│ └── fixtures/ # Test fixtures
├── config/ # Configuration files
│ ├── knowledge/ # Knowledge base patterns
│ └── field-mappings/ # Field translations
├── docs/ # Documentation
│ ├── API.md
│ ├── DEPLOYMENT.md
│ ├── TROUBLESHOOTING.md
│ └── CONTRIBUTING.md
├── .github/ # GitHub configuration
│ └── workflows/ # CI/CD workflows
└── build/ # Compiled output (gitignored)
```
### Key Architectural Principles
1. **Layered Architecture**: Entry → Server → Tools → Handlers → Client → API
2. **Test-First**: Write behavioral contracts before implementation
3. **Type Safety**: Strict TypeScript throughout
4. **Minimal Intervention**: Only essential abstractions
5. **Error Boundaries**: Comprehensive error handling
---
## Development Tips
### Debugging
```bash
# Enable debug logging
DEBUG=true npm run dev
# Debug specific test
node --inspect-brk node_modules/.bin/vitest test/unit/core/smartsuite-client.test.ts
# Use Chrome DevTools
# chrome://inspect
```
### Hot Reload
```bash
# Auto-restart on changes
npm run dev
# Watch tests
npm run test:watch
```
### Code Quality
```bash
# Fix auto-fixable issues
npm run lint:fix
# Format code
npm run format
# Check types
npm run typecheck
```
---
## Common Tasks
### Adding a New Tool
1. Define tool schema in `src/mcp/tools.ts`
2. Create handler in `src/operations/`
3. Add execute function in tools.ts
4. Write tests in `test/unit/mcp/tools.test.ts`
5. Update API documentation
6. Add knowledge base patterns if needed
### Adding New Field Type Support
1. Update `src/core/field-translator.ts`
2. Add validation rules
3. Add tests
4. Document in knowledge base
5. Update API.md with examples
### Fixing a Bug
1. Write failing test that reproduces bug
2. Fix the bug
3. Verify test passes
4. Add regression test if needed
5. Document in CHANGELOG.md
---
## Release Process
### Version Numbering
We follow [Semantic Versioning](https://semver.org/):
- **MAJOR**: Breaking changes
- **MINOR**: New features (backwards compatible)
- **PATCH**: Bug fixes
### Creating a Release
```bash
# Update version
npm version [major|minor|patch]
# Update CHANGELOG.md
# Create git tag
git tag -a v1.1.0 -m "Release v1.1.0"
# Push tag
git push origin v1.1.0
# Create GitHub release with notes
```
---
## Questions?
- **Documentation**: Check [docs/](../README.md)
- **Issues**: Search existing GitHub issues
- **Discussions**: Start a GitHub discussion
- **Security**: See [SECURITY.md](../SECURITY.md)
---
## Recognition
Contributors are recognized in:
- README.md contributors section
- GitHub insights
- Release notes
Thank you for contributing! 🎉
---
**Version**: 1.0.0
**Last Updated**: 2025-11-11
