# TaskLogger MCP

A [Model Context Protocol](https://modelcontextprotocol.io) server that gives AI agents programmatic access to **TaskLogger.io** tasks — create, update, search, assign, and complete tasks directly from an agent's toolset, no browser automation.

The server talks to the TaskLogger REST API (`https://api.tasklogger.io/api/v1`) over stdio. Tasks are TaskLogger **logs** with `logTypeId = 2`.

## Features

- **Full task lifecycle** — create, update, delete, mark done
- **Rich filtering** — by status, priority, assignee, creator, problem type, category, company, vendor, date ranges, free-text search, and pagination
- **Reference lookups** — statuses, priorities, problem types, categories, sub-types, users, departments, companies
- **Secure auth** — password is read only from a local env file, **never** passed as a tool parameter
- **Token persistence** — access/refresh tokens cached to disk and auto-refreshed across restarts

## Tools

| Tool | Purpose |
|------|---------|
| `login` | Authenticate with credentials from env vars |
| `logout` | Clear saved tokens |
| `status` | Check the authenticated user |
| `list_tasks` | List/filter/search tasks |
| `get_task` | Get one task by ID |
| `create_task` | Create a task (defaults sub-type to **Report Bug**) |
| `update_task` | Update fields on a task |
| `mark_task_done` | Shortcut → Completed + 100% |
| `delete_task` | Delete a task |
| `get_statuses` / `get_priorities` / `get_problem_types` / `get_task_categories` / `get_sub_types` / `get_users` / `get_departments` / `get_companies` | Look up valid IDs |

> **Tasks are identified by their numeric DB `id` in tool calls.** TaskLogger also exposes a human-friendly **transaction number (TN / `trans_num`)** in responses, which is what humans usually quote — report TN to the user, pass the numeric `id` to the tools.

## Requirements

- Node.js **18+** (uses global `fetch`, `FormData`, `crypto.randomUUID`)
- An account on a TaskLogger.io branch

## Setup

```bash
# 1. Clone and install
git clone https://github.com/khodorrrhajjj/TaskLogger-Mcp.git
cd TaskLogger-Mcp
npm install

# 2. Build
npm run build          # outputs dist/index.js
```

### 3. Credentials

Create a local credential file (the server reads it on startup). **It is created in your home directory, deliberately outside the repo, so it is never committed.**

Create `~/.tasklogger-mcp/env`:

```
TASKLOGGER_EMAIL=you@example.com
TASKLOGGER_PASSWORD=yourpassword
TASKLOGGER_BRANCH_ID=74
```

- `TASKLOGGER_PASSWORD` is **required** and never passed as a tool parameter.
- `TASKLOGGER_BRANCH_ID` selects the branch (only needed if you have multiple).

Alternatively, set the same keys as regular environment variables in your shell.

## Connecting to an agent

### OpenCode

Add to `opencode.json` (or your project/global config):

```json
{
  "mcp": {
    "tasklogger": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/Users/<you>/projects/TaskLogger-Mcp/dist/index.js"],
      "env": {}
    }
  }
}
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "tasklogger": {
      "command": "node",
      "args": ["C:/Users/<you>/projects/TaskLogger-Mcp/dist/index.js"]
    }
  }
}
```

### Any other MCP client

Point it at `node /absolute/path/to/tasklogger-mcp/dist/index.js` over the stdio transport.

## Usage examples

```text
# List tasks pending, created by users 214/215
list_tasks  status_id="8" created_by="214,215"

# Search
list_tasks  search="product setup"

# Create a Task Logger bug report
create_task  problem_description="...bug..." problem_type_id="96" category_id="22" assigned_to_id="80"

# Update a task's status (TN 152 → Pending)
get_task  id=24077          # ← confirm the numeric id
update_task  id=24077 status_id="8"
```

Common status IDs: **Pending = 8**, **To be tested = 10**, **Completed = 1**, **On Hold = 16**. Sub-type **Report Bug = 27**. Always `get_statuses` / `get_users` to confirm current IDs.

## How login works

1. On startup the server reads `~/.tasklogger-mcp/env` into the process environment (existing env vars win).
2. On the first authenticated call it POSTs to `/users/login` with email, password, `rememberMe: true`, and `branchId`. It holds the two HttpOnly cookies the API returns:
   - `accessToken` — short-lived (~15 min) bearer
   - `refreshToken` — longer-lived (~7 days)
3. Tokens are persisted to `~/.tasklogger-mcp/auth.json` (chmod `0600`) so a restart doesn't force a re-login.
4. Before every request, if the `accessToken` is expired the server tries to **refresh** it (POST `/users/refresh`, fallback `GET /users/authenticate`), then falls back to a fresh env-file login.
5. The dedicated `login` tool re-authenticates on demand; `logout` clears tokens from disk.

The **password itself never appears in any tool parameter**, MCP log, or conversation — only inside `env`.