# weeek-mcp-server

MCP (Model Context Protocol) server for the [WEEEK](https://weeek.net) task tracker. Gives AI coding agents (Claude Desktop, Cursor, Cline, and any other MCP client) direct read/write access to WEEEK projects, boards, tasks, comments, assignees, and time tracking — no context switching.

## Features

- **30 tools** — 11 read + 19 write covering projects, boards, columns, tasks, comments, assignees, watchers, subtasks, multi-project locations, timers, time entries, tags, custom fields, and MR links
- **MCP tool annotations** — every tool has a `title` and `readOnlyHint` / `destructiveHint` / `idempotentHint` / `openWorldHint`, so clients can auto-approve reads and gate destructive actions
- **Structured output** — every tool declares an `outputSchema` and returns `structuredContent` (plus a JSON text block for older clients)
- **Current WEEEK Public API** — task `locations` model (multi-project tasks), dedicated complete/un-complete, assignee, and comment endpoints
- **Stdio transport** — zero server infrastructure, runs via `npx`
- **Token auth** — single `WEEEK_API_TOKEN` env var, never logged
- **Safe defaults** — list tools paginate (default 20, max 50) so responses stay under the 25k token MCP limit
- **Structured errors** — API failures return `isError: true` with a human-readable message, the server never crashes

## Installation

No installation needed — configure your MCP client to run it via `npx`.

## Getting a WEEEK API Token

1. Sign in to [WEEEK](https://weeek.net).
2. Open **Workspace settings → API**.
3. Generate a personal API token.
4. Treat it like a password — it grants full read/write access to your workspace. Rotate it if it leaks.

## Configuration

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "weeek": {
      "command": "npx",
      "args": ["-y", "weeek-mcp-server"],
      "env": {
        "WEEEK_API_TOKEN": "your-weeek-token-here"
      }
    }
  }
}
```

Restart Claude Desktop.

### Cursor

Edit `~/.cursor/mcp.json` (or use **Cursor Settings → MCP → Add new MCP server**):

```json
{
  "mcpServers": {
    "weeek": {
      "command": "npx",
      "args": ["-y", "weeek-mcp-server"],
      "env": {
        "WEEEK_API_TOKEN": "your-weeek-token-here"
      }
    }
  }
}
```

### Generic MCP client

Any MCP client that supports stdio transport can launch:

```
command: npx
args: ["-y", "weeek-mcp-server"]
env: { WEEEK_API_TOKEN: "<your token>" }
```

## NVM Workaround (IMPORTANT for nvm users)

If you installed Node via [nvm](https://github.com/nvm-sh/nvm), GUI applications (Claude Desktop, Cursor) do **not** source your shell startup files, so `npx` is not on their `PATH`. You will see `spawn npx ENOENT` in the client logs.

**Fix:** use the absolute path to your nvm npx binary.

1. In your terminal, run:
   ```bash
   which npx
   ```
   Example output: `/Users/you/.nvm/versions/node/v22.0.0/bin/npx`

2. Put that absolute path in your MCP client config as the `command`:

   ```json
   {
     "mcpServers": {
       "weeek": {
         "command": "/Users/you/.nvm/versions/node/v22.0.0/bin/npx",
         "args": ["-y", "weeek-mcp-server"],
         "env": {
           "WEEEK_API_TOKEN": "your-weeek-token-here"
         }
       }
     }
   }
   ```

This is the single most common setup failure across all npx-based MCP servers. If you upgrade Node via nvm, update the path.

## Tools

All tools are prefixed `weeek_`. Read tools are side-effect free (`readOnlyHint: true`) and safe for auto-approve. Write tools mutate WEEEK state; tools marked ⚠️ are destructive (`destructiveHint: true`) and should always require confirmation.

### Read tools

| Tool | Purpose |
|------|---------|
| `weeek_get_current_user` | Profile of the token owner. Use its `id` as `assignee_id` for "my tasks". |
| `weeek_list_workspace_members` | List workspace members (IDs for assignees, watchers, time entries). |
| `weeek_list_projects` | List projects in the workspace. Use FIRST to discover project IDs. |
| `weeek_get_project` | Get a single project's details, including project-level custom fields. |
| `weeek_list_boards` | List boards inside a project. |
| `weeek_list_board_columns` | List columns (statuses) inside a board. Required before moving tasks. |
| `weeek_list_tasks` | List tasks with filters (project, board, column, assignee, completion, type, priority, tags, search, day) and sorting. |
| `weeek_get_task` | Full task details: description, locations, assignees, subtasks, time entries, custom fields. |
| `weeek_list_task_comments` | List comments on a task (Markdown). |
| `weeek_list_tags` | List workspace tags (IDs for task `tags`). |
| `weeek_list_custom_fields` | List global custom fields (IDs for task `custom_fields`). |

### Write tools

| Tool | Purpose |
|------|---------|
| `weeek_create_task` | Create a task in a project (optionally a column), with assignee, parent, type, priority, dates, tags. |
| `weeek_update_task` | Edit title, priority, type, start/due date(time), duration, tags, custom fields. Description can only be set at creation — the WEEEK API ignores it on update. |
| `weeek_move_task` | Place a task in a project/column (status change) or add it to another project. |
| `weeek_remove_task_from_project` ⚠️ | Remove a task from one of its projects. |
| `weeek_complete_task` | Mark a task complete, or reopen it. |
| `weeek_set_task_parent` | Make a task a subtask of another, or detach it. |
| `weeek_add_task_assignees` / `weeek_remove_task_assignees` ⚠️ | Manage task assignees. |
| `weeek_add_task_watchers` / `weeek_remove_task_watchers` ⚠️ | Manage task watchers. |
| `weeek_create_task_comment` | Post a Markdown comment or reply on a task. |
| `weeek_delete_task_comment` ⚠️ | Delete a task comment. |
| `weeek_start_task_timer` / `weeek_stop_task_timer` | Start or stop the time tracker on a task. |
| `weeek_create_time_entry` / `weeek_update_time_entry` | Log or edit time (minutes) on a task. |
| `weeek_delete_time_entry` ⚠️ | Delete a time entry. |
| `weeek_delete_task` ⚠️ | Delete a task. |
| `weeek_set_task_mr_link` | Write a merge/pull request URL into the task project's `МР` custom field (name overridable via `field_name`). `weeek_move_task` and `weeek_complete_task` also accept `mr_url` to do this in the same call. |

## Safety

- **Annotations over groups:** every tool carries MCP annotations. Configure your client to auto-approve `readOnlyHint` tools and always confirm `destructiveHint` tools (⚠️ above).
- **Destructive operations exist since 0.2.0:** deletes and removals are exposed but explicitly marked destructive. If you don't want an agent to have them, deny those tools in your MCP client.
- **Pagination defaults:** list tools default to 20 results (max 50) to stay under the 25,000 token MCP response cap.
- **Token handling:** `WEEEK_API_TOKEN` is read from the `env` block only. It is never logged, echoed, or included in error messages.

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| `spawn npx ENOENT` in client logs | You are using nvm — see the [NVM Workaround](#nvm-workaround-important-for-nvm-users) section above. |
| `WEEEK_API_TOKEN environment variable is required` | The `env` block is missing or empty in your MCP client config. |
| `Invalid WEEEK_API_TOKEN` | Token is wrong, revoked, or expired — regenerate in WEEEK workspace settings. |
| Server disconnects immediately after starting | You are on Node < 20. Upgrade Node (`nvm install 20`) and update your config path. |
| Tool returns "Resource not found (404)" | The ID doesn't exist in the workspace — list the parent resource first (e.g., `weeek_list_projects` before `weeek_get_project`). |

## Development

```bash
git clone <this-repo>
cd weeek-mcp-server
npm install
npm run build
npm test
```

Scripts:
- `npm run build` — compile TypeScript to `dist/`
- `npm run dev` — run from source via `tsx`
- `npm run lint` — ESLint (enforces no-console rule for stdio safety)
- `npm run typecheck` — `tsc --noEmit`
- `npm test` — vitest unit tests

To smoke-test the built binary:

```bash
npm run build
WEEEK_API_TOKEN=test node dist/index.js
# server blocks on stdin — press Ctrl+C to exit
```

Live end-to-end test against the real WEEEK API (drives `dist/index.js` over stdio, creates `[mcp-smoke]` tasks in the given project and deletes them afterwards):

```bash
npm run build
WEEEK_API_TOKEN=<token> node scripts/live-smoke.mjs                              # lists projects to pick an id
WEEEK_API_TOKEN=<token> WEEEK_SMOKE_PROJECT_ID=<test project id> node scripts/live-smoke.mjs
```

Use a dedicated test project with at least one board (2+ columns) and one workspace tag.

## Requirements

- Node.js >= 20.0.0
- A WEEEK account with API access

## License

MIT — see [LICENSE](./LICENSE).