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

npm install -g breathe-api

2. Configure Cursor

Add to your Cursor settings:

{
  "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.

{
  "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).

{
  "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)

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

Multi-Environment Setup (Optional)

# 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 for details on configuring custom APIs.

Development

# 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.

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