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 в корне репозитория:

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. Сборка и запуск:

docker compose up -d --build

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

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

docker compose down

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

---

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

1. PostgreSQL

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

# 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 (обязательно)

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 в корне репозитория (скопируйте из примера ниже и подставьте свои значения):

# База
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

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

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 (опционально)

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

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 или в пользовательских настройках:

{
  "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 (или из правил проекта).