# EverHour MCP Server

A Model Context Protocol (MCP) server for EverHour time tracking and project management integration. This server enables AI assistants to interact with EverHour's API for comprehensive time tracking, project management, task management, expense tracking, and reporting capabilities.

## Features

### 🕐 Time Tracking
- **Timer Management**: Start, stop, and monitor active timers
- **Time Records**: Create, update, delete, and list time entries
- **Time Reporting**: Generate detailed time reports by project, user, or date range

### 📋 Project Management
- **Project CRUD**: Create, read, update, and delete projects
- **Project Structure**: Manage sections, labels, and project organization
- **Budget Tracking**: Set and monitor project budgets (time and money)
- **Billing Configuration**: Configure hourly rates and billing types

### ✅ Task Management
- **Task Operations**: Full CRUD operations for tasks
- **Task Organization**: Assign tasks to projects, sections, and users
- **Task Estimates**: Set and track time estimates
- **Task Status**: Manage open/closed status and progress

### 👥 User & Team Management
- **User Profiles**: Access user information and permissions
- **Team Organization**: Create and manage teams
- **Role Management**: Handle admin, supervisor, and member roles

### 💰 Client & Expense Management
- **Client Management**: Create and manage client information
- **Expense Tracking**: Record and categorize business expenses
- **Invoice Integration**: Prepare data for invoicing workflows

### 📊 Reporting & Analytics
- **Time Summaries**: Generate comprehensive time tracking reports
- **Project Reports**: Detailed project performance analytics
- **User Reports**: Individual productivity and time allocation reports
- **Custom Filtering**: Filter reports by date, project, user, or task

## Installation

1. **Clone and navigate to the directory**:
   ```bash
   git clone <repository-url>
   cd mcp-everhour
   ```

2. **Install dependencies**:
   ```bash
   npm install
   ```

3. **Get your EverHour API Key**:
   - Go to [EverHour Settings](https://app.everhour.com/)
   - Navigate to Settings → API
   - Generate a new API key
   - Copy the API key for configuration

4. **Validate your API key** (optional but recommended):
   ```bash
   npm run auth "your_api_key_here"
   ```

## Configuration

### Environment Variables

Create a `.env` file in the project root:

```env
# EverHour Configuration
EVERHOUR_API_KEY=your_everhour_api_key_here

# Server Configuration (optional)
PORT=6791
```

### Alternative Configuration

You can also provide the API key during MCP initialization rather than using environment variables.

## Usage

### Development Mode

Start the EverHour MCP server in development mode:

```bash
npm run dev
```

The server will run on `http://localhost:6791/mcp/everhour/`

### Production Mode

1. **Build the project**:
   ```bash
   npm run build
   ```

2. **Start the server**:
   ```bash
   npm run start
   ```

### Testing the Server

Test the server and verify available tools:

```bash
# Start the server in one terminal
npm run dev

# Test the server in another terminal
npm run test:server
```

### MCP Client Configuration

Add the EverHour MCP server to your MCP client configuration:

```json
{
  "mcpServers": {
    "everhour": {
      "command": "npx",
      "args": ["ts-node", "src/index.ts"],
      "cwd": "/path/to/mcp-everhour",
      "env": {
        "EVERHOUR_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

## Available Tools (38 total)

### Authentication
- `set_api_key` - Set the EverHour API key for authentication

### User Management
- `get_me` - Get current user profile information
- `list_users` - List all users in the workspace
- `get_user` - Get specific user details by ID

### Project Management
- `list_projects` - List all projects with filtering options
- `get_project` - Get specific project details
- `create_project` - Create a new project
- `update_project` - Update existing project
- `delete_project` - Delete a project

### Task Management
- `list_tasks` - List tasks with comprehensive filtering
- `get_task` - Get specific task details
- `create_task` - Create a new task
- `update_task` - Update existing task
- `delete_task` - Delete a task

### Time Tracking
- `list_time_records` - List time records with date and project filters
- `get_time_record` - Get specific time record details
- `create_time_record` - Create a new time entry
- `update_time_record` - Update existing time record
- `delete_time_record` - Delete a time record

### Timer Management
- `get_running_timer` - Get currently running timer
- `start_timer` - Start a timer for a specific task
- `stop_timer` - Stop the currently running timer

### Client Management
- `list_clients` - List all clients
- `get_client` - Get specific client details
- `create_client` - Create a new client
- `update_client` - Update existing client
- `delete_client` - Delete a client

### Expense Management
- `list_expenses` - List expenses with filtering
- `create_expense` - Create a new expense record

### Reporting & Analytics
- `get_project_report` - Get detailed project time report
- `get_user_report` - Get detailed user time report
- `get_time_summary` - Get time tracking summary with grouping

### Project Structure
- `list_sections` - List sections for a project
- `create_section` - Create a new section in a project
- `list_labels` - List labels for projects
- `create_label` - Create a new label

### Team Management
- `list_teams` - List all teams in the workspace
- `create_team` - Create a new team

## Example Usage

### Testing the Server

Use the test script to verify the server is working:

```bash
npm run test:server
```

This will:
- Perform a health check
- Initialize with your API key
- List all available tools
- Test some basic API calls

### Start a Timer
```json
{
  "tool": "start_timer",
  "arguments": {
    "task": "task_id_here",
    "comment": "Working on feature implementation"
  }
}
```

### Create a Time Record
```json
{
  "tool": "create_time_record",
  "arguments": {
    "task": "task_id_here",
    "time": 7200,
    "date": "2024-01-15",
    "comment": "Code review and testing"
  }
}
```

### List Projects
```json
{
  "tool": "list_projects",
  "arguments": {
    "status": "active",
    "limit": 50
  }
}
```

### Create a Project
```json
{
  "tool": "create_project",
  "arguments": {
    "name": "Website Redesign",
    "client": "client_id_here",
    "type": "board",
    "billing": {
      "type": "project_hourly",
      "rate": 75
    },
    "budget": {
      "type": "time",
      "budget": 144000
    }
  }
}
```

## API Reference

### Authentication

The EverHour MCP server uses API key authentication. The API key can be provided in two ways:

1. **Environment Variable**: Set `EVERHOUR_API_KEY` in your environment
2. **MCP Initialization**: Provide `api_key` parameter during MCP initialization

### Error Handling

The server provides detailed error messages and codes:

- `AUTH_ERROR` - Authentication failed or API key not provided
- `INVALID_PARAMS` - Required parameters missing or invalid
- `HTTP_XXX` - HTTP status code errors from EverHour API
- `NETWORK_ERROR` - Network connectivity issues

### Rate Limiting

The server respects EverHour's API rate limits. If you encounter rate limiting, the server will return appropriate error messages.

## Troubleshooting

### Common Issues

1. **Authentication Errors**
   - Verify your API key is correct
   - Check that the API key has sufficient permissions
   - Ensure you're using a valid, active API key

2. **Network Errors**
   - Check your internet connection
   - Verify EverHour's service status
   - Check for firewall or proxy issues

3. **Permission Errors**
   - Ensure your API key has the necessary permissions
   - Contact your EverHour administrator for access rights

### Debugging

Enable debug logging by setting the `DEBUG` environment variable:

```bash
DEBUG=everhour:* npm run dev
```

### Testing API Key

Use the auth helper to validate your API key:

```bash
npm run auth "your_api_key_here"
```

This will test your API key and display available permissions and accessible data.

### Available NPM Scripts

- `npm run dev` - Start the server in development mode
- `npm run build` - Build the TypeScript project
- `npm run start` - Start the built server
- `npm run auth "api_key"` - Test and validate your API key
- `npm run test:server` - Test the running server and list tools

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT License. See LICENSE file for details.

## Support

For issues and questions:

1. Check the [EverHour API Documentation](https://everhour.docs.apiary.io/)
2. Review the troubleshooting section above
3. Open an issue in this repository

## Changelog

### v1.0.0
- Initial release with comprehensive EverHour API coverage
- Full CRUD operations for projects, tasks, time records
- Timer management and time tracking
- Expense tracking and client management
- Reporting and analytics tools
- Team and user management features