# task360-mcp

A **Model Context Protocol (MCP)** server and CLI for **Chat360 Task** ([task.chat360.io](https://task.chat360.io)).

Allows AI assistants (Claude Desktop, Gemini Antigravity, Cursor, etc.) to query, create, update, comment on, and manage work items, sprints, and boards directly in Task360.

---

## ⚡ Quick Start

### Installation

Install via `uv` or `pip`:

```bash
# Using uv (recommended)
uv tool install git+https://github.com/karangoel59/task360-mcp.git

# Or clone and install locally:
git clone https://github.com/karangoel59/task360-mcp.git
cd task360-mcp
uv tool install .
```

---

## 🔐 Authentication

Task360 uses session-based authentication (`sessionid`). You can authenticate in three ways:

1. **Browser Session Cookie (Easiest)**:
   Copy the `sessionid` cookie from your browser (Open DevTools on `task.chat360.io` ➔ Application ➔ Cookies ➔ `sessionid`).
   ```bash
   task360 --sessionid "<your_sessionid_cookie>"
   ```
   *(Caches the session to `~/.task360_session.json` so you only need to do this once).*

2. **Login Credentials**:
   ```bash
   task360 -i  # Prompts for email & password securely
   ```

3. **Environment Variables**:
   ```bash
   export TASK360_SESSIONID="<sessionid>"
   # OR
   export TASK360_EMAIL="<email>"
   export TASK360_PASSWORD="<password>"
   export TASK360_WORKSPACE="chat360"  # Optional default workspace
   ```

---

## 🤖 MCP Configuration

Add the server to your AI assistant's MCP configuration.

### Claude Desktop (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "task360": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/karangoel59/task360-mcp.git", "task360-mcp"],
      "env": {
        "TASK360_WORKSPACE": "chat360"
      }
    }
  }
}
```

Or if installed locally:
```json
{
  "mcpServers": {
    "task360": {
      "command": "/Users/karangoel59/.local/bin/task360-mcp",
      "args": [],
      "env": {}
    }
  }
}
```

### Gemini Antigravity (`~/.gemini/config/mcp_config.json`)
```json
{
  "mcpServers": {
    "task360": {
      "command": "/Users/karangoel59/.local/bin/task360-mcp",
      "args": [],
      "env": {}
    }
  }
}
```

---

## 🛠️ MCP Tools Reference

| Tool | Description |
| :--- | :--- |
| `list_workspaces()` | List all workspaces accessible to the user. |
| `get_user_profile()` | Get current authenticated user details and ID. |
| `get_my_tickets(workspace?, limit?)` | Fetch tickets assigned to the signed-in user. |
| `search_tickets(query?, assignee_id?, status_id?, project_id?, workspace?, limit?)` | Search tickets with JQL-like queries (e.g. `q="status = in_progress"`). |
| `get_ticket(key, workspace?)` | Retrieve full details of a specific ticket (e.g. `CPD-123`). |
| `create_ticket(project_id, item_type_id, board_id, summary, description?, assignee_id?, extra_fields?, workspace?)` | Create a new work item. |
| `update_ticket(key, summary?, description?, assignee_id?, extra_fields?, workspace?)` | Update fields on a ticket. |
| `get_transitions(key, workspace?)` | Inspect valid status transitions from the ticket's current status. |
| `transition_ticket(key, transition_id, workspace?)` | Move ticket status via workflow engine transition. |
| `add_comment(key, body, workspace?)` | Post a comment on a ticket. |
| `delete_ticket(key, workspace?)` | Permanently delete a ticket. |

---

## 💻 CLI Usage

The package also includes the `task360` CLI command:

```bash
# List your assigned tickets
task360

# Search with JQL query
task360 -q "status = in_progress"

# View specific ticket
task360 --key CPD-123

# Update ticket summary or description
task360 --key CPD-123 --summary "Updated title" --desc "New description"

# Assign ticket
task360 --key CPD-123 --assign me
task360 --key CPD-123 --unassign

# Check workflow transitions & transition status
task360 --key CPD-123 --transitions
task360 --key CPD-123 --transition "In Progress"

# Add a comment
task360 --key CPD-123 --comment "Deployed to stage server."

# Delete ticket
task360 --key CPD-123 --delete

# Export tickets
task360 --json > my_tickets.json
task360 --csv > my_tickets.csv
```

---

## 📄 License

MIT License. Copyright (c) 2026 Karan Goel.