# VTrack MCP Server

MCP (Model Context Protocol) server that exposes the V-Track project management API as tools for AI assistants.

## Setup

### 1. Install dependencies

```bash
npm install
```

### 2. Build

```bash
npm run build
```

### 3. Configure

Set environment variables before starting:

| Variable | Description | Default |
|---|---|---|
| `VTRACK_BASE_URL` | V-Track API base URL | `http://localhost:3000` |
| `VTRACK_ACCESS_TOKEN` | Bearer access token | _(empty)_ |

Or call the `configure` tool at runtime to set them dynamically.

### 4. Run

```bash
npm start
# or for development
npm run dev
```

---

## Connecting to Claude Desktop / Claude Code

Add to your MCP config (e.g. `~/.claude/settings.json` or Claude Desktop config):

```json
{
  "mcpServers": {
    "vtrack": {
      "command": "node",
      "args": ["D:/workspace/vtrack-mcp/dist/index.js"],
      "env": {
        "VTRACK_BASE_URL": "https://your-vtrack-api.example.com",
        "VTRACK_ACCESS_TOKEN": "your-bearer-token"
      }
    }
  }
}
```

---

## Available Tools

### Meta
| Tool | Description |
|---|---|
| `configure` | Set base URL and access token at runtime |

### Auth
| Tool | Description |
|---|---|
| `auth_login` | Login, returns accessToken + refreshToken |
| `auth_refresh` | Refresh access token |
| `auth_logout` | Logout current user |

### Users
| Tool | Description |
|---|---|
| `users_list` | Paginated user list |
| `users_me` | Current user info |
| `users_detail` | User detail by ID |

### Projects
| Tool | Description |
|---|---|
| `projects_list` | Paginated project list |
| `projects_detail` | Project detail by ID |
| `projects_export_members_excel` | Export members as Excel |

### Tasks
| Tool | Description |
|---|---|
| `tasks_list` | Paginated task list with filters |
| `tasks_detail` | Task detail by ID |
| `tasks_kanban_board` | Kanban board grouped by status |

### Backlog
| Tool | Description |
|---|---|
| `backlog_list` | Paginated backlog (feature tasks) |
| `backlog_detail` | Backlog item detail |

### Issues
| Tool | Description |
|---|---|
| `issues_list` | Paginated issues (bug tasks) |
| `issues_detail` | Issue detail by ID |

### Sprints
| Tool | Description |
|---|---|
| `sprints_list` | Paginated sprint list |
| `sprints_list_active` | Active sprints only |
| `sprints_detail` | Sprint detail by ID |
| `sprints_list_for_filter` | Lightweight sprint list for dropdowns |

### Project Members
| Tool | Description |
|---|---|
| `project_members_list` | Members of a project |

### Task Comments
| Tool | Description |
|---|---|
| `task_comments_list` | Comments for a task (cursor-based) |
| `task_comments_detail` | Comment detail by ID |

### Attachments
| Tool | Description |
|---|---|
| `attachments_list` | Attachments for an entity |
| `attachments_detail` | Attachment detail by ID |

### Requests
| Tool | Description |
|---|---|
| `requests_list` | Paginated request list |
| `requests_detail` | Request detail by ID |

### Milestones
| Tool | Description |
|---|---|
| `milestones_list` | Paginated milestone list |
| `milestones_detail` | Milestone detail by ID |

### Reports
| Tool | Description |
|---|---|
| `reports_global` | System-wide metrics |
| `reports_attention` | System-wide alerts |
| `reports_project` | Project-level report |
| `reports_export_data` | Exportable project data |
| `reports_project_attention` | Project-level alerts |

### Workload
| Tool | Description |
|---|---|
| `workload_list` | Workload per team member |

### Lookup Tables
| Tool | Description |
|---|---|
| `lookup_priorities` | All priorities |
| `lookup_roles` | All system roles |
| `lookup_project_roles` | All project roles |
| `lookup_task_types` | Task types (optionally by project) |
| `lookup_request_types` | Request types (optionally by project) |
| `lookup_request_channels` | Request channels |
| `lookup_statuses` | All statuses (no auth required) |

### Notifications
| Tool | Description |
|---|---|
| `notifications_list` | User's notifications |
| `notifications_mark_read` | Mark one notification as read |
| `notifications_mark_all_read` | Mark all notifications as read |

### Meeting Notes
| Tool | Description |
|---|---|
| `meeting_notes_list` | Paginated meeting notes |
| `meeting_notes_detail` | Meeting note detail by ID |

### Service Monitors
| Tool | Description |
|---|---|
| `service_monitors_list` | Paginated monitor list |
| `service_monitors_detail` | Monitor detail |
| `service_monitors_logs` | Monitor logs |
| `service_monitors_incidents` | Incident list |
| `service_monitors_incident_detail` | Incident detail |
| `service_monitors_sla_stats` | SLA statistics |
| `service_monitors_uptime_stats` | Uptime statistics |

### Misc
| Tool | Description |
|---|---|
| `health_check` | API health check |
| `audit_logs` | Paginated audit logs |

---

## Response Format

All V-Track responses follow this envelope:

```json
{
  "code": 0,
  "message": "...",
  "data": {},
  "total": 100,
  "totalPages": 10
}
```

`code: 0` = success. Errors: `-2` bad request, `-3` unauthorized, `-4` not found.