# Cursor Task Tracker

Система управления задачами для Cursor IDE: MCP‑сервер (FastMCP по HTTP), REST API, веб‑дашборд с канбаном и WebSocket для событий. AI в Cursor создаёт задачи, меняет статусы и пишет комментарии через MCP; в каждом репозитории можно задать своего PM и проект.

---

## Что это за проект

- **MCP‑сервер** — Cursor вызывает инструменты (create_task, update_task_status, add_comment и др.) по HTTP. Один сервер обслуживает все ваши репозитории.
- **Роли:** PM (владелец проектов, например 0dm1n) и агенты (main, frontend-dev, backend-dev, bug-fixer, refactor-agent, test-agent) — отдельные пользователи; комментарии идут от имени агента.
- **Подключение проектов** — в каждом репозитории в `.cursorrules` или в `CURSOR_TASK_TRACKER.md` указываете PM, имя проекта и при необходимости агента. По этим правилам AI передаёт `as_project_owner`, `project_name`, `as_user` в вызовы MCP.
- **Дашборд** — канбан по проектам PM, смена статусов, комментарии, звуки при событиях (если положить MP3 в `dashboard/public/sounds/`).
- **Авторегистрация** — при первом обращении пользователи и проекты создаются автоматически (если включено в `.env`).

---

## Требования

- Python 3.10+
- Node.js 18+
- PostgreSQL 15+

---

## Структура проекта

```
├── main.py              # Точка входа (python main.py / uvicorn src.app:app)
├── src/
│   ├── app.py           # FastAPI приложение, CORS, mount MCP
│   ├── config.py        # Настройки из .env
│   ├── database.py      # PostgreSQL: пользователи, проекты, задачи, история
│   ├── schemas.py       # Pydantic-модели запросов API
│   ├── routes.py        # REST API: auth, projects, tasks, comments, WebSocket
│   ├── mcp_plugin.py    # MCP: инструменты и ресурсы (create_task, get_project_board и др.)
│   └── websocket.py     # Менеджер подключений и emit_event
├── dashboard/           # Vue 3 SPA (канбан)
├── requirements.txt
├── Dockerfile
└── docker-compose.yml
```

---

## Запуск в production (Docker)

Запуск всего стека: приложение, PostgreSQL, дашборд (встроен в контейнер).

1. Создайте `.env` в корне репозитория:

```env
DB_NAME=cursor_tracker
DB_USER=postgres
DB_PASSWORD=ваш_надёжный_пароль

SECRET_KEY=случайная_длинная_строка_32_символа_минимум

MCP_DEFAULT_USERNAME=0dm1n
MCP_SUPERUSER=true
MCP_AUTO_REGISTER=true
MCP_AUTO_REGISTER_PASSWORD=changeme
```

2. Сборка и запуск:

```bash
docker compose up -d --build
```

- **Приложение (API + дашборд):** http://localhost:8000
- **MCP endpoint:** http://localhost:8000/mcp
- **Health:** http://localhost:8000/health

3. Остановка:

```bash
docker compose down
```

Данные PostgreSQL хранятся в volume `pgdata` (сохраняются при `down`). Для полного удаления: `docker compose down -v`.

---

## Как запустить (без Docker)

### 1. PostgreSQL

Запустите БД (Docker или локальный PostgreSQL):

```bash
# Docker
docker run --name cursor-tracker-db -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=cursor_tracker -p 5432:5432 -d postgres:15-alpine
```

Либо создайте БД `cursor_tracker` и пользователя с паролем вручную.

### 2. Backend (обязательно)

```bash
cd Cursor-MCP-server-for-track-ai-agents-works
python -m venv venv
venv\Scripts\activate   # Windows
# source venv/bin/activate   # Linux/macOS
pip install -r requirements.txt
```

Создайте файл `.env` в корне репозитория (скопируйте из примера ниже и подставьте свои значения):

```env
# База
DB_NAME=cursor_tracker
DB_USER=postgres
DB_PASSWORD=ваш_пароль
DB_HOST=localhost
DB_PORT=5432

# Сервер
HOST=0.0.0.0
PORT=8000
DEBUG=true

# MCP: главный пользователь (PM по умолчанию) и дефолтный проект
MCP_DEFAULT_USERNAME=0dm1n
MCP_DEFAULT_PROJECT=My Project

# Суперпользователь — видит все доски и задачи
MCP_SUPERUSER=true

# Авторегистрация пользователей и проектов при первом вызове
MCP_AUTO_REGISTER=true
MCP_AUTO_REGISTER_PASSWORD=changeme

# Агенты (создаются при старте сервера)
MCP_AGENT_USERNAMES=main,frontend-dev,backend-dev,bug-fixer,refactor-agent,test-agent
```

Инициализация БД выполняется при старте приложения. Запуск сервера:

```bash
python main.py
```

Или с uvicorn: `uvicorn src.app:app --reload --host 0.0.0.0 --port 8000`

- Backend: **http://localhost:8000**
- MCP endpoint: **http://localhost:8000/mcp**
- Health: **http://localhost:8000/health**

### 3. Dashboard (опционально)

Канбан‑доска для просмотра проектов и задач, смена статусов, комментарии.

```bash
cd dashboard
npm install
npm run dev
```

Дашборд: **http://localhost:5173**. Вход под пользователями, созданными через MCP или авторегистрацию (пароль из `MCP_AUTO_REGISTER_PASSWORD`).

### 4. MCP в Cursor

В настройках Cursor добавьте MCP‑сервер (глобально или в workspace). Пример `.cursor/mcp.json` в корне workspace или в пользовательских настройках:

```json
{
  "mcpServers": {
    "task-tracker": {
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

**Важно:** сначала запустите `python main.py`, затем перезагрузите Cursor (Ctrl+Shift+P → «Reload Window»). После этого в чате станут доступны MCP‑инструменты task-tracker.

---

## Как подключать проекты (репозитории)

Один и тот же MCP‑сервер обслуживает все ваши репозитории. «Подключить проект» значит: в **этом** репозитории задать правила, по которым AI будет вызывать MCP (какой PM, какой проект, какой агент).

### Шаг 1: Правила в репозитории

В корне репозитория добавьте блок в **`.cursorrules`** или скопируйте **`CURSOR_TASK_TRACKER.md`** из этого репозитория и при необходимости отредактируйте блок контекста в начале файла.

Пример блока для `.cursorrules`:

```
## Task Tracker (MCP)
В этом проекте для task tracker используй:
- PM (владелец проектов): 0dm1n
- Проект: MyApp

При вызовах MCP передавай:
- as_project_owner="0dm1n"
- project_name="MyApp"
- as_user="frontend-dev" (при add_comment — автор комментария)
- assigned_agent="frontend-dev" (при create_task — кто выполняет)
```

Имена PM и проекта могут быть любыми; пользователи и проекты создаются при первом вызове, если включена авторегистрация.

### Шаг 2: Файл‑инструкция для AI (рекомендуется)

Скопируйте **`CURSOR_TASK_TRACKER.md`** из репозитория Cursor-MCP-server-for-track-ai-agents-works в корень вашего проекта. В нём уже описаны инструменты, PM/агенты и правило «на каждый шаг». При необходимости измените в начале файла PM и имя проекта под этот репозиторий.

### Шаг 3: Первый запуск в чате

В Cursor в этом репозитории напишите первое сообщение в чате (например: «инициализируй workspace»). AI должен:

1. Вызвать `initialize_workspace(as_project_owner="0dm1n", default_project="MyApp")` (подставив ваши PM и проект из правил).
2. Дальше создавать задачи, менять статусы и добавлять комментарии, передавая `as_project_owner`, `project_name` и при необходимости `as_user`.

Задачи появятся в проекте PM и будут видны в дашборде (если открыть проект, принадлежащий этому PM).

### Разные репозитории — разные проекты

- Репозиторий A: в правилах `project_name="Frontend"`, `as_project_owner="0dm1n"`.
- Репозиторий B: `project_name="Backend"`, `as_project_owner="0dm1n"`.

Оба подключаются к одному MCP‑серверу; различаются только правила в каждом репо. Итог: у PM 0dm1n два проекта (Frontend и Backend), а в каждом репо AI работает со своим `project_name`.

---

## MCP Tools (кратко)

| Инструмент | Назначение |
|------------|------------|
| `initialize_workspace(as_project_owner?, default_project?)` | Инициализация: PM и проект из правил |
| `create_project(name, as_project_owner?)` | Создать проект (владелец — PM) |
| `create_task(title, project_name?, description?, assigned_agent?, as_project_owner?)` | Создать задачу в проекте PM |
| `update_task_status(task_id, new_status)` | TODO / IN_PROGRESS / TESTING / DONE |
| `add_comment(task_id, content, as_user?)` | Комментарий (автор — агент, если передан as_user) |
| `get_project_board(project_name?, as_project_owner?)` | Доска проекта PM |
| `get_projects_list(as_project_owner?)` | Список проектов PM |
| `get_pending_tasks(as_project_owner?)` | Задачи в TODO |
| `get_testing_tasks(as_project_owner?)` | Задачи в TESTING |

Ресурсы: `setup://roles`, `tasks://pending`, `tasks://testing-queue`, `tasks://recent-changes`, `projects://list`.

Подробное описание и примеры — в **`CURSOR_TASK_TRACKER.md`**.

---

## Дополнительно

### Суперпользователь

В `.env`: `MCP_SUPERUSER=true`. Пользователь с логином `MCP_DEFAULT_USERNAME` получает доступ ко всем доскам и задачам всех пользователей (MCP, REST API и дашборд).

### PM и агенты

- **PM** — владелец проектов (например 0dm1n). В вызовах MCP задаётся как `as_project_owner`.
- **Агенты** — main, frontend-dev, backend-dev, bug-fixer, refactor-agent, test-agent. Создаются при старте сервера; при `add_comment` передаётся `as_user` (имя агента), чтобы комментарий шёл от его имени.

### Звуки в дашборде

Положите MP3 в `dashboard/public/sounds/`:

- `task-created.mp3`
- `status-changed.mp3`
- `comment-added.mp3`
- `task-testing.mp3`

### Регистрация без авторегистрации

Если `MCP_AUTO_REGISTER=false`, пользователей нужно заранее создать через дашборд (http://localhost:5173): регистрация, вход, создание проектов. Для MCP должен существовать пользователь с логином из `MCP_DEFAULT_USERNAME` (или из правил проекта).