# ConstructionClock MCP Server

A local [Model Context Protocol](https://modelcontextprotocol.io) server that gives Claude Desktop two ConstructionClock time-entry tools. It talks to the ConstructionClock REST API directly with `fetch` — no browser automation.

## Tools

| Tool | Required arguments | Hits |
| --- | --- | --- |
| `cc_add_time` | `employeeId`, `projectId`, `startTime`, `endTime` | `POST /api/punches` |
| `cc_edit_time` | `entryId`, `projectId`, `newStartTime`, `newEndTime` | `PATCH /api/punch/edit/time` |

Times are ISO-8601 **local, with no timezone suffix**, e.g. `2026-08-12T08:00:00`
(that's the format ConstructionClock itself sends). `employeeId` is sent to the
API as `userId`. `cc_edit_time` needs the `projectId` too — the edit endpoint
requires it, not just the entry id.

## Setup

Node.js 18+ is required (`fetch` is built in). Installed on this machine on
2026-08-13 via winget (`OpenJS.NodeJS.LTS`, Node v24.19.0) and dependencies are
already installed. To reinstall deps after a checkout:

```bash
cd "C:\Users\15049\OneDrive\Desktop\Claude\Tools\ConstructionClock-MCP"
npm install
```

The server loads `.env` relative to its own file, so it works no matter what
working directory Claude Desktop launches it from.

Then put your token in `.env` (copy from `.env.example`):

```
CC_API_TOKEN=your-real-token
```

Get the token from the `Authorization` header of a captured ConstructionClock request in DevTools.

## Register with Claude Desktop

Add this to your `claude_desktop_config.json` (`%APPDATA%\Claude\claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "constructionclock": {
      "command": "node",
      "args": ["C:\\Users\\15049\\OneDrive\\Desktop\\Claude\\Tools\\ConstructionClock-MCP\\src\\server.js"]
    }
  }
}
```

Restart Claude Desktop. The two `cc_*` tools should appear.

## Endpoints (verified)

Captured live from `app.constructionclock.com` on 2026-08-12:

```
ADD   POST  /api/punches
      { "punches": [ { userId, projectId, uuid, clockedInAt, clockedOutAt } ] }

EDIT  PATCH /api/punch/edit/time
      { id, projectId, date: { dateFrom, dateTo }, uuid }
```

`uuid` is generated per call by the server. If ConstructionClock ever changes
these, everything you'd need to edit lives in the `CONFIG` block at the top of
`src/server.js`.

## Budget guardrail

See [`BUDGET_GUARDRAILS.md`](./BUDGET_GUARDRAILS.md) — a standing instruction for Claude Desktop sessions to check JobTread budgeted-vs-actual hours before adding or editing time.