# Timesheet MCP Server

A Model Context Protocol (MCP) server that provides CRUD operations for timesheet management via REST API endpoints.

> **👤 For End Users:** See [README-USER.md](README-USER.md) for simple installation instructions  
> **👨‍💻 For Developers:** Continue reading below  
> **📦 Publishing:** See [Publishing Guide](../docs/guides/mcp-publishing.md) to distribute your connector

## Features

- **Create** timesheet entries
- **Read** timesheet entries (list and get single)
- **Update** existing entries
- **Delete** timesheet entries
- **List Projects** for reference
- Configurable API base URL
- Support for both Go and Node.js backend APIs

## Prerequisites

- Node.js 18 or higher
- A running instance of the Timesheet Logger backend API
- Claude Desktop (for integration)

## Installation

1. Navigate to the mcp directory:

```bash
cd mcp
```

2. Install dependencies:

```bash
npm install
```

3. Configure environment variables:

```bash
cp .env.example .env
# Edit .env and set TIMESHEET_API_BASE_URL
```

4. Build the project:

```bash
npm run build
```

## Configuration

### Environment Variables

Create a `.env` file or set environment variables:

```bash
TIMESHEET_API_BASE_URL=http://localhost:3000/api
```

### Claude Desktop Integration

Add to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

**For end users (after publishing to npm):**

```json
{
  "mcpServers": {
    "timesheet": {
      "command": "timesheet-mcp",
      "env": {
        "TIMESHEET_API_BASE_URL": "http://localhost:3000/api"
      }
    }
  }
}
```

**For local development:**

```json
{
  "mcpServers": {
    "timesheet": {
      "command": "node",
      "args": ["/absolute/path/to/timesheet_logger/mcp/build/index.js"],
      "env": {
        "TIMESHEET_API_BASE_URL": "http://localhost:3000/api"
      }
    }
  }
}
```

## Usage

### Development Mode

Run in development mode with auto-reload:

```bash
npm run dev
```

### Production Mode

Build and run:

```bash
npm run build
npm start
```

## Available Tools

### 1. create_timesheet_entry

Create a new timesheet entry.

**Parameters:**

- `project_id` (string, required): Project ID
- `date` (string, required): Entry date (YYYY-MM-DD)
- `hours` (number, required): Hours worked
- `description` (string, optional): Entry description
- `billable` (boolean, optional): Whether entry is billable (default: true)

### 2. list_timesheet_entries

List timesheet entries with optional filters.

**Parameters:**

- `start_date` (string, optional): Filter by start date (YYYY-MM-DD)
- `end_date` (string, optional): Filter by end date (YYYY-MM-DD)
- `project_id` (string, optional): Filter by project ID
- `limit` (number, optional): Maximum results (default: 50)
- `offset` (number, optional): Offset for pagination (default: 0)

### 3. get_timesheet_entry

Get a single timesheet entry by ID.

**Parameters:**

- `entry_id` (string, required): Entry ID

### 4. update_timesheet_entry

Update an existing timesheet entry.

**Parameters:**

- `entry_id` (string, required): Entry ID
- `project_id` (string, optional): New project ID
- `date` (string, optional): New date (YYYY-MM-DD)
- `hours` (number, optional): New hours
- `description` (string, optional): New description
- `billable` (boolean, optional): New billable status

### 5. delete_timesheet_entry

Delete a timesheet entry.

**Parameters:**

- `entry_id` (string, required): Entry ID

### 6. list_projects

List available projects.

**Parameters:** None

### 7. create_project

Create a new project. Requires admin or manager role.

**Parameters:**

- `name` (string, required): Project name
- `description` (string, optional): Project description
- `is_active` (boolean, optional): Whether project is active (default: true)

### 8. login

Manually trigger browser-based login. Opens a browser window for authentication.

**Parameters:** None

**Note:** Useful after logout or for manual authentication. If already logged in, will show current user.

### 9. logout

Logout from the current session and clear stored authentication tokens.

**Parameters:** None

**Note:** After logout, you will need to re-authenticate (via browser login) on the next request.

## Testing

### Test with Local Backend

1. Start your backend API:

```bash
# From backend/api-nodejs or backend/api-go
docker-compose up
```

2. Run the MCP server:

```bash
npm run dev
```

3. Test through Claude Desktop or use the MCP Inspector

## Troubleshooting

### Connection Refused

- Ensure the backend API is running
- Verify the `TIMESHEET_API_BASE_URL` is correct
- Check that the port matches your backend configuration

### Authentication Errors

- Verify API key if required by your backend
- Check that the API endpoint supports the operations

### Tool Not Found

- Rebuild the project: `npm run build`
- Restart Claude Desktop
- Verify the path in Claude Desktop config is absolute

## Development

### Project Structure

```
mcp/
├── src/
│   ├── index.ts              # Main MCP server entry point
│   ├── config.ts             # Configuration management
│   ├── types.ts              # TypeScript types
│   ├── api/
│   │   ├── client.ts         # HTTP client wrapper
│   │   └── timesheet.ts      # Timesheet API operations
│   └── tools/
│       ├── create-entry.ts   # Create tool
│       ├── list-entries.ts   # List tool
│       ├── get-entry.ts      # Get tool
│       ├── update-entry.ts   # Update tool
│       └── delete-entry.ts   # Delete tool
├── build/                    # Compiled output
├── package.json
├── tsconfig.json
└── README.md
```

### Adding New Tools

1. Create a new file in `src/tools/`
2. Define the tool schema using Zod
3. Implement the handler function
4. Register the tool in `src/index.ts`

## License

MIT