npm package: @pulses/hubstaff-mcp
Description: Hubstaff Time Tracking (API v2) and Hubstaff Tasks (API v1) MCP server
Author: Pulses.ai
Latest version: 2.2.0

# Hubstaff MCP Server (TypeScript)

A Model Context Protocol (MCP) server for integrating with Hubstaff Time Tracking (API v2) and Hubstaff Tasks (API v1).

## Setup

### Installation

```bash
npm install
npm run build
```

### Environment Variables

Set one of the following authentication options:

```bash
# Option 1: Direct access token
export HUBSTAFF_ACCESS_TOKEN="your_access_token"

# Option 2: Refresh token (auto-refreshes)
export HUBSTAFF_REFRESH_TOKEN="your_refresh_token"
```

### Running the Server

```bash
npm start
```

Or in development mode:

```bash
npm run dev
```

## Tools

### Users (1 tool)
- `hubstaff_get_current_user` - Get current user information

### Organizations (2 tools)
- `hubstaff_list_organizations` - List all organizations
- `hubstaff_list_org_members` - List organization members with pagination

### Projects (3 tools)
- `hubstaff_list_projects` - List projects with filtering and pagination
- `hubstaff_create_project` - Create a new project
- `hubstaff_update_project` - Update existing project

### Activities (2 tools)
- `hubstaff_list_activities` - List tracked activities with filters
- `hubstaff_list_daily_activities` - List aggregated daily activities

### Screenshots (1 tool)
- `hubstaff_list_screenshots` - List screenshots from tracked time

### Notes (1 tool)
- `hubstaff_list_notes` - List notes from tracked time

### App/URL Usage (2 tools)
- `hubstaff_list_app_usage` - List application usage during tracked time
- `hubstaff_list_url_usage` - List URL usage during tracked time

### Tasks - Time Tracking API v2 (3 tools)
- `hubstaff_list_tasks` - List tasks with filtering
- `hubstaff_get_task` - Get specific task details
- `hubstaff_create_task` - Create a new task

### Reports (1 tool)
- `hubstaff_weekly_report` - Generate weekly activity report

### Board Tasks - Tasks API v1 (8 tools)
- `hubstaff_tasks_list_projects` - List task board projects
- `hubstaff_tasks_list_columns` - List project columns
- `hubstaff_tasks_list_tasks` - List tasks in project
- `hubstaff_tasks_get_task` - Get task details
- `hubstaff_tasks_create_task` - Create board task
- `hubstaff_tasks_update_task` - Update board task
- `hubstaff_tasks_delete_task` - Delete board task
- `hubstaff_tasks_list_sprints` - List project sprints

### Webhooks (2 tools)
- `hubstaff_list_webhooks` - List configured webhooks
- `hubstaff_create_webhook` - Create new webhook

## Features

### Authentication
- Automatic token refresh 60 seconds before expiry
- Support for both access tokens and refresh tokens
- Secure token caching

### Response Formats
All tools support both `json` and `markdown` response formats:
- `response_format: "json"` - Returns structured JSON
- `response_format: "markdown"` - Returns formatted markdown (default)

### Pagination
List tools support pagination with:
- `page_start_id` - ID to start from
- `page_limit` - Number of items (max 100)
- `has_more` - Indicates more results available
- `next_page_start_id` - ID for next page

### Error Handling
- 401: Authentication failed
- 403: Permission denied
- 404: Resource not found
- 429: Rate limit exceeded (1000 req/hr)
- Timeout: 30 second request timeout

## Architecture

```
src/
├── index.ts          # Main server entry with tool registration
├── client.ts         # TokenManager and HTTP client
├── constants.ts      # API URLs and configuration
├── types.ts          # TypeScript interfaces
└── tools/
    ├── users.ts
    ├── organizations.ts
    ├── projects.ts
    ├── activities.ts
    ├── screenshots.ts
    ├── notes.ts
    ├── usage.ts
    ├── tasks.ts
    ├── reports.ts
    ├── board-tasks.ts
    └── webhooks.ts
```

## Development

### TypeScript
- Strict mode enabled
- Full type safety
- ESM modules

### Validation
- Zod schemas with `.strict()` enforcement
- Input validation on all parameters

### Testing

To test locally, you can use the MCP Inspector:

```bash
npm run build
npx @modelcontextprotocol/inspector ./dist/index.js
```

## API References

- Hubstaff Time Tracking API v2: https://api.hubstaff.com/v2
- Hubstaff Tasks API v1: https://api.hubstaff.com/v1
- Auth: https://account.hubstaff.com/access_tokens