# Clockify MCP Server

A modular Model Context Protocol (MCP) server for integrating with the Clockify time tracking API.

## Installation

### From npm (Recommended)

```bash
npm install -g clockify-mcp-server
```

### From Source

```bash
git clone https://github.com/yourusername/clockify-mcp-server.git
cd clockify-mcp-server
npm install
```

## Features

This MCP server provides three tools:

1. **iam** - Get current user information from Clockify API
2. **getAllProjects** - Get all projects for a specific workspace
3. **logTimeEntry** - Log time entries with flexible time specifications

## Architecture

The server is built with a modular architecture:

- `src/server.js` - Main server class with `registerTool` interface
- `src/api.js` - Shared API utilities for Clockify requests
- `src/tools/` - Individual tool modules with Zod schema validation
- `index.js` - Entry point that registers all tools

## Setup

### 1. Set Environment Variables

Create a `.env` file or set the environment variable with your Clockify API key:

```bash
export CLOCKIFY_API_KEY=your_api_key_here
```

You can get your API key from [Clockify Settings > API](https://clockify.me/user/settings#api).

### 2. Run the Server

If installed globally:
```bash
clockify-mcp-server
```

If running from source:
```bash
npm start
```

Or for development with auto-restart:
```bash
npm run dev
```

## Usage in MCP Clients

After installing, you can configure your MCP client to use this server. For example, in Claude Desktop:

```json
{
  "mcpServers": {
    "clockify": {
      "command": "clockify-mcp-server",
      "env": {
        "CLOCKIFY_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

## Tools

### iam

Get current user information from Clockify API.

**Parameters:** None

**Example:**
```json
{
  "name": "iam"
}
```

### getAllProjects

Get all projects for a specific workspace.

**Parameters:**
- `workspaceId` (string, required): The workspace ID to get projects for

**Example:**
```json
{
  "name": "getAllProjects",
  "arguments": {
    "workspaceId": "60c1beaf8747147d9ac70b4b"
  }
}
```

### logTimeEntry

Log a time entry in Clockify.

**Parameters:**
- `date` (string, required): Date for the time entry in YYYY-MM-DD format
- `description` (string, required): Description of the work performed
- `projectId` (string, required): ID of the project to log time against
- `workspaceId` (string, required): ID of the workspace
- `startTime` (string, optional): Start time in HH:MM format (defaults to "09:00")
- `endTime` (string, optional): End time in HH:MM format (defaults to "17:00")

**Example:**
```json
{
  "name": "logTimeEntry",
  "arguments": {
    "date": "2024-01-15",
    "description": "Working on project documentation",
    "projectId": "662f81c0b682f06d79bff487",
    "workspaceId": "60c1beaf8747147d9ac70b4b",
    "startTime": "09:30",
    "endTime": "12:30"
  }
}
```

## Getting Workspace and Project IDs

1. Use the `iam` tool to get your user information and available workspaces
2. Use the `getAllProjects` tool with a workspace ID to get project IDs
3. Use these IDs in the `logTimeEntry` tool

## Error Handling

The server includes comprehensive error handling for:
- Missing or invalid API keys
- Invalid date/time formats
- Missing required parameters
- API request failures
- Time validation (end time must be after start time)

All errors are returned with descriptive messages to help troubleshoot issues.

## Development

### Adding New Tools

The server uses a clean `registerTool` interface. To add a new tool:

1. Create a new file in `src/tools/` with your tool definition:

```javascript
import { z } from "zod";
import { makeApiRequest } from "../api.js";

export const myNewTool = {
  name: "myNewTool",
  config: {
    title: "My New Tool",
    description: "Description of what the tool does",
    inputSchema: z.object({
      param1: z.string().describe("Description of param1"),
      param2: z.number().optional().describe("Optional param2")
    })
  },
  handler: async ({ param1, param2 }) => {
    // Your tool logic here
    const result = await makeApiRequest("/some-endpoint");
    return {
      content: [{
        type: "text",
        text: JSON.stringify(result, null, 2)
      }]
    };
  }
};
```

2. Export it from `src/tools/index.js`
3. Register it in `index.js`:

```javascript
server.registerTool(
  myNewTool.name,
  myNewTool.config,
  myNewTool.handler
);
```

The server automatically handles:
- Zod schema validation
- JSON schema conversion for MCP
- Error handling and formatting
- Tool registration and discovery

## Publishing

To publish updates to npm:

1. Update the version in `package.json`
2. Run `npm publish`

## License

MIT

## Requirements

- Node.js 18.0.0 or higher
- Clockify API key