mcpengine/servers/rippling/README.md

# Rippling MCP Server

Complete Model Context Protocol (MCP) server for the Rippling HR Platform API.

## Overview

This MCP server provides comprehensive integration with Rippling's HR platform, enabling AI assistants to interact with employee data, payroll, time tracking, benefits, recruiting (ATS), learning management, device inventory, and more.

## Features

### 🔧 **50+ Tools Across 10 Categories**

#### Employees (7 tools)
- `rippling_list_employees` - List all employees with filters
- `rippling_get_employee` - Get detailed employee information
- `rippling_create_employee` - Create new employee records
- `rippling_update_employee` - Update employee information
- `rippling_terminate_employee` - Terminate an employee
- `rippling_list_employee_custom_fields` - List custom fields
- `rippling_get_org_chart` - Get organizational chart

#### Companies (5 tools)
- `rippling_get_company` - Get company information
- `rippling_list_departments` - List all departments
- `rippling_create_department` - Create new department
- `rippling_list_locations` - List work locations
- `rippling_list_teams` - List all teams

#### Payroll (4 tools)
- `rippling_list_pay_runs` - List payroll runs
- `rippling_get_pay_run` - Get pay run details
- `rippling_list_pay_statements` - List pay statements
- `rippling_get_pay_statement` - Get detailed pay statement

#### Time Tracking (11 tools)
- `rippling_list_time_entries` - List time clock entries
- `rippling_create_time_entry` - Create time entry
- `rippling_update_time_entry` - Update time entry
- `rippling_delete_time_entry` - Delete time entry
- `rippling_get_timesheet` - Get timesheet
- `rippling_approve_timesheet` - Approve timesheet
- `rippling_list_time_off_requests` - List PTO requests
- `rippling_create_time_off_request` - Create PTO request
- `rippling_approve_time_off_request` - Approve PTO
- `rippling_deny_time_off_request` - Deny PTO

#### Benefits (4 tools)
- `rippling_list_benefits_plans` - List benefits plans
- `rippling_get_benefits_plan` - Get plan details
- `rippling_list_benefits_enrollments` - List enrollments
- `rippling_get_benefits_enrollment` - Get enrollment details

#### ATS/Recruiting (6 tools)
- `rippling_list_candidates` - List candidates
- `rippling_get_candidate` - Get candidate details
- `rippling_list_jobs` - List job postings
- `rippling_get_job` - Get job details
- `rippling_list_applications` - List applications
- `rippling_update_application_stage` - Move candidate through pipeline

#### Learning (4 tools)
- `rippling_list_courses` - List training courses
- `rippling_get_course` - Get course details
- `rippling_list_course_assignments` - List assignments
- `rippling_assign_course` - Assign course to employee

#### Devices (4 tools)
- `rippling_list_devices` - List hardware devices
- `rippling_get_device` - Get device details
- `rippling_list_apps` - List software/app licenses
- `rippling_get_app` - Get app license details

#### Groups (6 tools)
- `rippling_list_groups` - List groups
- `rippling_get_group` - Get group details
- `rippling_create_group` - Create new group
- `rippling_update_group` - Update group
- `rippling_add_group_member` - Add member to group
- `rippling_remove_group_member` - Remove member from group

#### Custom Objects (5 tools)
- `rippling_list_custom_objects` - List custom objects
- `rippling_get_custom_object` - Get custom object
- `rippling_create_custom_object` - Create custom object
- `rippling_update_custom_object` - Update custom object
- `rippling_query_custom_objects` - Query custom objects with filters

### 🎨 **16 React UI Components**

1. **EmployeeDashboard** - Overview of employee metrics and departments
2. **EmployeeDetail** - Detailed employee profile view
3. **EmployeeDirectory** - Searchable employee directory with filters
4. **OrgChart** - Visual organizational chart
5. **PayrollDashboard** - Payroll overview and recent runs
6. **PayrollDetail** - Detailed pay statement breakdown
7. **TimeTracker** - Clock in/out interface and time entry viewer
8. **TimesheetApprovals** - Approve/reject employee timesheets
9. **TimeOffCalendar** - PTO calendar and requests
10. **BenefitsOverview** - Benefits plans and enrollments
11. **ATSPipeline** - Recruiting pipeline visualization
12. **JobBoard** - Job postings board
13. **LearningDashboard** - Training and course completion dashboard
14. **DeviceInventory** - Hardware and device management
15. **TeamOverview** - Team composition and management
16. **DepartmentGrid** - Department overview and headcount

## Installation

```bash
npm install
```

## Configuration

Set the following environment variables:

```bash
# Option 1: API Key authentication
export RIPPLING_API_KEY="your_api_key_here"

# Option 2: OAuth2 Bearer token
export RIPPLING_ACCESS_TOKEN="your_access_token_here"

# Optional: Custom API base URL
export RIPPLING_BASE_URL="https://api.rippling.com"
```

## Usage

### As MCP Server

Add to your MCP settings configuration:

```json
{
  "mcpServers": {
    "rippling": {
      "command": "node",
      "args": ["/path/to/rippling/dist/index.js"],
      "env": {
        "RIPPLING_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### Development

```bash
# Build TypeScript
npm run build

# Run in development mode
npm run dev
```

## API Client

The `RipplingClient` class provides:

- ✅ Automatic authentication (API key or OAuth2)
- ✅ Cursor-based pagination support
- ✅ Comprehensive error handling
- ✅ Type-safe requests and responses
- ✅ Automatic retry logic
- ✅ Request/response interceptors

### Example Usage

```typescript
import { RipplingClient } from './clients/rippling.js';

const client = new RipplingClient({
  apiKey: process.env.RIPPLING_API_KEY,
});

// List employees with pagination
const employees = await client.listEmployees({
  status: 'ACTIVE',
  departmentId: 'dept_123',
  limit: 100,
});

// Get all pages automatically
const allEmployees = await client.getAllPaginated('/v1/employees');

// Create a new employee
const newEmployee = await client.createEmployee({
  firstName: 'John',
  lastName: 'Doe',
  email: 'john.doe@company.com',
  title: 'Software Engineer',
});
```

## Architecture

```
rippling/
├── src/
│   ├── clients/
│   │   └── rippling.ts          # API client with auth & pagination
│   ├── tools/
│   │   ├── employees-tools.ts   # Employee management (7 tools)
│   │   ├── companies-tools.ts   # Company/dept/location (5 tools)
│   │   ├── payroll-tools.ts     # Payroll operations (4 tools)
│   │   ├── time-tools.ts        # Time tracking & PTO (11 tools)
│   │   ├── benefits-tools.ts    # Benefits management (4 tools)
│   │   ├── ats-tools.ts         # Recruiting/ATS (6 tools)
│   │   ├── learning-tools.ts    # Learning management (4 tools)
│   │   ├── devices-tools.ts     # Device/app inventory (4 tools)
│   │   ├── groups-tools.ts      # Group management (6 tools)
│   │   └── custom-objects-tools.ts # Custom objects (5 tools)
│   ├── types/
│   │   └── index.ts             # TypeScript type definitions
│   ├── ui/
│   │   └── react-app/           # 16 React UI components
│   ├── server.ts                # MCP server setup
│   └── index.ts                 # Entry point
├── package.json
├── tsconfig.json
└── README.md
```

## Type Safety

All API interactions are fully typed with TypeScript interfaces including:

- Employee, Department, Location, Team
- PayRun, PayStatement, EarningsLine, TaxLine, DeductionLine
- TimeEntry, Timesheet, TimeOffRequest
- BenefitsPlan, BenefitsEnrollment, Dependent
- Candidate, Job, Application, Interview
- Course, CourseAssignment
- Device, AppLicense
- Group, CustomObject
- PaginatedResponse, RipplingError

## Error Handling

The client automatically handles:

- HTTP errors with detailed messages
- Rate limiting (with retry logic)
- Invalid authentication
- Malformed requests
- Network errors

Errors are returned in a consistent format:

```typescript
{
  message: string;
  code?: string;
  statusCode?: number;
  details?: any;
}
```

## Pagination

All list endpoints support cursor-based pagination:

```typescript
// Manual pagination
let cursor: string | undefined;
do {
  const response = await client.listEmployees({ cursor, limit: 100 });
  // Process response.data
  cursor = response.nextCursor;
} while (response.hasMore);

// Automatic pagination (gets all pages)
const allEmployees = await client.getAllPaginated('/v1/employees');
```

## License

MIT

## Support

For issues or questions:
- Check the [Rippling API Documentation](https://developer.rippling.com/)
- Review the type definitions in `src/types/index.ts`
- Examine the client implementation in `src/clients/rippling.ts`

## Contributing

Contributions welcome! Please ensure:
- All new tools have proper Zod schemas
- Type definitions are updated
- Error handling is comprehensive
- Tests are added (when test suite is created)