breathe-api/README.md

Model Context Protocol server for Breathe HR APIs with Swagger/OpenAPI support - also works with custom APIs

# Breathe HR API MCP Server

A Model Context Protocol (MCP) server specifically designed for Breathe HR APIs, providing comprehensive tools for interacting with Breathe HR's Main API and ELMO Roster API through Swagger/OpenAPI specifications.

## Features

### Breathe HR Integration

- **Automatic API Discovery**: Seamlessly works with both Main HR and ELMO Roster APIs
- **Smart Feature Detection**: Automatically searches both APIs when you mention "breathe"
- **Complete Coverage**: Kudos, leave requests, timesheets, shifts, employees, documents, and more
- **Pre-configured Authentication**: Simple setup with username/password
- **Breathe-Specific Prompts**: 10+ pre-built workflows for common HR tasks

### Enhanced Capabilities

- **🚀 Performance**: Multi-tier caching reduces API calls by up to 90%
- **🔒 Security**: Type-safe credentials, input sanitization, and rate limiting
- **📊 Progress Tracking**: Real-time updates for long-running operations
- **🛡️ Reliability**: Retry logic with exponential backoff and circuit breakers
- **🌍 Multi-Environment**: Support for production, staging, development, and sandbox
- **💻 Code Generation**: Generate React, React Native, Next.js, and Ruby clients

## Quick Start for Breathe HR

### 1. Install

```bash
npm install -g breathe-api
```

### 2. Configure Cursor

Add to your Cursor settings:

```json
{
  "mcpServers": {
    "breathe-api": {
      "command": "npx",
      "args": ["-y", "breathe-api@latest"],
      "env": {
        "BREATHE_API_USERNAME": "your-username",
        "BREATHE_API_PASSWORD": "your-password"
      }
    }
  }
}
```

### 3. Start Using

Ask Cursor:

- "Generate a React component for leave requests. use breathe-api mcp"
- "Explain how timesheets work in Breathe using breathe-apic mcp"
- "You have access to breathe-api mcp, go ahead to create a kudos recognition system"

## Breathe HR API Features

Based on the official Breathe HR documentation, this MCP server provides access to:

### Main HR API Features

- **Employee Management**: Access employee profiles, documents, and onboarding workflows
- **Leave/Absence Management**: Handle leave requests, check balances, and manage approvals
- **Kudos & Recognition**: Implement employee recognition and rewards systems
- **Company Structure**: Manage departments and organizational hierarchies
- **Holiday Management**: Track and manage company holidays and time off

### ELMO Roster API Features

- **Shift Scheduling**: Create and manage employee shift schedules
- **Timesheets**: Track time entries and manage timesheet submissions
- **Punch Clock**: Digital clock-in/clock-out functionality
- **Roster Planning**: Plan and optimize staff rosters
- **Shift Swapping**: Enable employees to swap shifts with approval workflows

## Available Tools

### 1. explain_api_feature

Understand how Breathe HR features work with implementation examples.

```
Example: "Explain timesheets on breathe"
Result: Detailed explanation with code examples for timesheet implementation
```

### 2. generate_api_client

Generate complete API client code for Breathe HR integration.

```json
{
  "name": "generate_api_client",
  "arguments": {
    "swaggerUrl": "<your-breathe-swagger-url>",
    "platform": "react",
    "outputDir": "./breathe-client"
  }
}
```

### 3. api_request

Make API calls to Breathe HR endpoints (requires proper authentication).

```json
{
  "name": "api_request",
  "arguments": {
    "url": "<breathe-api-endpoint>",
    "method": "GET"
  }
}
```

### 4. Environment Management Tools

- **list_environments** - View production, staging, development environments
- **switch_environment** - Switch between different Breathe HR environments
- **test_environment** - Test connectivity and authentication
- **discover_endpoints** - Explore available Breathe HR endpoints

### 5. Resource Access

Access Breathe HR data using intuitive URI schemes:

```
breathe://production/employees
breathe://production/leave/{employeeId}
breathe://staging/timesheets
```

## Breathe HR Prompt Templates

Pre-built workflows for common HR tasks:

1. **setup-employee-onboarding** - Complete onboarding workflow
2. **implement-leave-management** - Leave request and approval system
3. **setup-timesheet-system** - Timesheet tracking implementation
4. **kudos-recognition-system** - Employee recognition platform
5. **shift-scheduling** - Shift management with ELMO Roster
6. **hr-dashboard** - Comprehensive HR metrics dashboard
7. **employee-directory** - Searchable employee directory
8. **api-integration-guide** - Step-by-step Breathe HR integration
9. **troubleshoot-api** - Debug common Breathe HR API issues
10. **migrate-to-breathe** - Migration guide from other HR systems

## Environment Configuration

### Basic Setup (Required)

```bash
export BREATHE_API_USERNAME="your-username"
export BREATHE_API_PASSWORD="your-password"
```

### Multi-Environment Setup (Optional)

```bash
# Production
export BREATHE_PRODUCTION_USERNAME="prod-username"
export BREATHE_PRODUCTION_PASSWORD="prod-password"

# Staging
export BREATHE_STAGING_USERNAME="staging-username"
export BREATHE_STAGING_PASSWORD="staging-password"

# Development (for local testing)
export BREATHE_DEV_URL="<your-dev-endpoint>"
```

## Advanced Features

### Performance Optimization

- **Smart Caching**: Swagger specs cached for 1 hour, API responses for 5 minutes
- **Request Deduplication**: Prevents duplicate concurrent requests
- **Connection Pooling**: Efficient resource utilization

### Security & Reliability

- **Secure Credential Storage**: Type-safe credential handling
- **Automatic Retry**: Handles transient failures gracefully
- **Circuit Breakers**: Prevents cascading failures
- **Rate Limiting**: Respects API limits automatically

### Multi-Language Support

Generate API clients in:

- **React** - Hooks-based API client with TypeScript
- **React Native** - Mobile-optimized client
- **Next.js** - Server and client components
- **Ruby** - Full SDK with models and documentation

## Common Use Cases

### 1. Employee Onboarding

```
"Create an employee onboarding workflow for React"
```

### 2. Leave Management Dashboard

```
"Build a leave request dashboard showing balances and pending approvals"
```

### 3. Timesheet Integration

```
"Generate a timesheet submission component with project allocation"
```

### 4. Shift Scheduling System

```
"Create a shift scheduling interface using ELMO Roster API"
```

## Troubleshooting

### Authentication Issues

```
Tool: test_environment
Result: Detailed connectivity and auth status
```

### API Discovery

```
Tool: discover_endpoints
Arguments: {"filter": "employee"}
Result: All employee-related endpoints
```

### Performance Monitoring

```
Tool: cache_stats
Result: Cache hit rates and performance metrics
```

## Custom API Support

While this server is optimized for Breathe HR, it can also work with other APIs. See [CUSTOM_API_SETUP.md](./CUSTOM_API_SETUP.md) for details on configuring custom APIs.

## Development

```bash
# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Run tests
npm test
```

## Contributing

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

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Support

For issues and feature requests, please use the [GitHub issue tracker](https://github.com/yourusername/breathe-api-mcp/issues).

## Changelog

### v1.0.0 (Latest)

- ✨ Enhanced Breathe HR integration with 10+ prompt templates
- 🚀 Performance optimizations with multi-tier caching
- 🔒 Security enhancements and type-safe credentials
- 📊 Progress notifications for long operations
- 🌍 Multi-environment support for Breathe HR
- 🛡️ Reliability improvements with retry logic
- 💻 Full code generation for React, React Native, Next.js, and Ruby
- 🔧 Resource management with URI schemes
- 🎯 Custom API support as secondary feature