# Task Manager MCP Server

MCP (Model Context Protocol) сервер для управления задачами в проектах с AI ассистентами, такими как Claude Code или Gemini CLI.

## Возможности

- **Поддержка нескольких проектов**: Управление задачами для множества проектов из единой корневой директории
- **Структурированное управление**: Задачи организованы в папки активных и завершенных
- **Автоматическая нумерация**: Задачи автоматически нумеруются последовательно
- **Богатые метаданные**: Отслеживание статуса, приоритета, дат и зависимостей
- **Формат Markdown**: Все задачи хранятся в читаемом формате markdown
- **Git-friendly**: Идеально подходит для контроля версий
- **Оптимизация для AI**: Специально разработано для работы с AI ассистентами

## Установка

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

- Node.js >= 16.0.0
- npm или yarn

### Настройка

1. Клонируйте или скачайте этот репозиторий
2. Установите зависимости:

```bash
npm install
```

3. Соберите проект:

```bash
npm run build
```

## Конфигурация

### Интеграция с Claude Desktop

Добавьте это в конфигурационный файл Claude Desktop:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "task-manager": {
      "command": "node",
      "args": ["/абсолютный/путь/к/task-manager-mcp/dist/index.js"],
      "env": {
        "TASK_MANAGER_ROOT": "/путь/к/вашей/корневой/папке/задач"
      }
    }
  }
}
```

**Важно**: Замените `/абсолютный/путь/к/task-manager-mcp` на фактический путь к этому проекту, а `/путь/к/вашей/корневой/папке/задач` на директорию, где вы хотите хранить задачи.

Если `TASK_MANAGER_ROOT` не указан, по умолчанию используется `~/task-manager`.

Для локальной настройки можно использовать шаблон `.env.example` как референс.

### Перезапуск Claude Desktop

После обновления конфигурации перезапустите Claude Desktop, чтобы изменения вступили в силу.

## Использование

### Доступные MCP инструменты

#### 1. `init_project`

Инициализирует новый проект со структурой управления задачами.

**Параметры**:
- `projectName` (string, обязательный): Название проекта

**Пример**:
```
Пожалуйста, инициализируй проект "my-website"
```

#### 2. `create_task`

Создает новую задачу в проекте.

**Параметры**:
- `projectName` (string, обязательный): Название проекта
- `title` (string, обязательный): Название задачи
- `description` (string, опциональный): Подробное описание
- `priority` (enum, опциональный): LOW, MEDIUM (по умолчанию), или HIGH
- `dependencies` (array, опциональный): Список номеров задач, от которых зависит эта

**Пример**:
```
Создай задачу в проекте "my-website":
Название: Реализовать аутентификацию пользователей
Описание: Добавить JWT-аутентификацию с логином и регистрацией
Приоритет: HIGH
```

#### 3. `list_tasks`

Показывает список задач в проекте.

**Параметры**:
- `projectName` (string, обязательный): Название проекта
- `status` (enum, опциональный): ACTIVE (по умолчанию), COMPLETED, или ALL
- `priority` (enum, опциональный): Фильтр по LOW, MEDIUM, или HIGH

**Пример**:
```
Покажи все активные задачи в проекте "my-website"
```

#### 4. `get_task`

Получает полную информацию о конкретной задаче.

**Параметры**:
- `projectName` (string, обязательный): Название проекта
- `taskNumber` (string, обязательный): Номер задачи (например, "001", "042")

**Пример**:
```
Покажи задачу 001 из проекта "my-website"
```

#### 5. `update_task`

Обновляет существующую задачу.

**Параметры**:
- `projectName` (string, обязательный): Название проекта
- `taskNumber` (string, обязательный): Номер задачи
- `status` (enum, опциональный): TODO, IN_PROGRESS, или COMPLETED
- `priority` (enum, опциональный): LOW, MEDIUM, или HIGH
- `technicalSolution` (string, опциональный): Техническое решение
- `implementation` (string, опциональный): Детали реализации
- `testResults` (string, опциональный): Результаты тестирования

**Пример**:
```
Обнови задачу 001 в "my-website":
- Статус: IN_PROGRESS
- Техническое решение: Использование Passport.js с JWT стратегией
```

#### 6. `complete_task`

Отмечает задачу как завершенную и перемещает в папку завершенных.

**Параметры**:
- `projectName` (string, обязательный): Название проекта
- `taskNumber` (string, обязательный): Номер задачи
- `commitMessage` (string, опциональный): Кастомное сообщение коммита (генерируется автоматически, если не указано)

**Пример**:
```
Отметь задачу 001 как завершенную в проекте "my-website"
```

#### 7. `list_projects`

Показывает список всех доступных проектов.

**Пример**:
```
Покажи все проекты
```

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

После инициализации каждый проект имеет следующую структуру:

```
task-manager-root/
└── название-проекта/
    ├── active/
    │   └── task-NNN.md
    ├── completed/
    │   ├── task-NNN.md
    │   └── INDEX.md
    └── PLAN.md
```

- **active/**: Задачи в работе или запланированные
- **completed/**: Завершенные задачи с полной историей
- **PLAN.md**: Обзор всех задач
- **INDEX.md**: Индекс завершенных задач

## Формат файла задачи

Каждая задача - это markdown файл со следующей структурой:

```markdown
# Task-001: Название задачи

## Метаданные
- **Статус**: 📋 TODO / 🔄 IN_PROGRESS / ✅ COMPLETED
- **Приоритет**: LOW / MEDIUM / HIGH
- **Создано**: 2025-01-15
- **Начато**: -
- **Завершено**: -
- **Зависимости**: -

---

## Описание проблемы
[Подробное описание проблемы или функциональности]

## Техническое решение
[Технический подход и архитектура]

## Реализация
[Детали реализации и прогресс]

## Тестирование
### Тест-кейсы
- [ ] Тест-кейс 1
- [ ] Тест-кейс 2

### Результаты
[Результаты тестирования]

## Результат
**Коммит**: -
**Деплой**: -
```

## Рабочий процесс

### Типичный жизненный цикл задачи

1. **Создать** задачу используя `create_task`
2. **Посмотреть** список задач чтобы увидеть что нужно сделать
3. **Получить** детали задачи при начале работы
4. **Обновить** задачу с техническим решением и пометить как IN_PROGRESS
5. **Обновлять** задачу с деталями реализации в процессе работы
6. **Обновить** задачу с результатами тестирования
7. **Завершить** задачу когда закончите - она переместится в completed
8. **Закоммитить** изменения используя предложенное сообщение коммита

### Формат сообщений коммитов

Система генерирует сообщения коммитов в следующем формате:

```
[prefix] task-NNN: описание
```

Префиксы:
- `feat` - Новая функциональность
- `fix` - Исправление бага
- `tune` - Оптимизация или улучшение
- `docs` - Документация
- `refactor` - Рефакторинг кода

## Разработка

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

```
task-manager-mcp/
├── src/
│   ├── index.ts              # Точка входа
│   ├── server.ts             # Реализация MCP сервера
│   ├── types/
│   │   └── index.ts          # TypeScript типы
│   ├── services/
│   │   ├── file-system.ts    # Операции с файлами
│   │   ├── project-manager.ts # Управление проектами
│   │   └── task-manager.ts   # Операции с задачами
│   └── templates/
│       └── task-template.ts  # Шаблоны файлов задач
├── dist/                     # Скомпилированный JavaScript
├── package.json
├── tsconfig.json
└── README.md
```

### Скрипты

- `npm run build` - Сборка TypeScript в JavaScript
- `npm run watch` - Режим наблюдения для разработки
- `npm start` - Запуск сервера напрямую

### Тестирование

Вы можете протестировать сервер вручную:

```bash
# Установите корневую директорию
export TASK_MANAGER_ROOT=/путь/к/вашим/задачам

# Запустите сервер
npm start
```

Сервер запустится и будет слушать MCP команды через stdio.

## Решение проблем

### Сервер не появляется в Claude Desktop

1. Проверьте что путь к конфигурационному файлу корректный
2. Убедитесь что абсолютные пути в конфиге правильные
3. Перезапустите Claude Desktop
4. Проверьте логи Claude Desktop на наличие ошибок

### Задачи не создаются

1. Убедитесь что путь `TASK_MANAGER_ROOT` существует и доступен для записи
2. Проверьте что вы инициализировали проект с помощью `init_project`
3. Проверьте что у вас есть права на запись в директорию

### Ошибки сборки

1. Убедитесь что используете Node.js >= 16.0.0
2. Удалите директории `node_modules` и `dist`
3. Запустите `npm install` снова
4. Запустите `npm run build`

## Вклад в проект

Это персональный проект-шаблон. Не стесняйтесь форкать и адаптировать под свои нужды.

## Лицензия

MIT License - свободно используйте в любых проектах.

## Авторы

Создано для рабочего процесса AI-assisted разработки с Claude Code и Gemini CLI.

---

**Версия**: 1.0.0
**Последнее обновление**: 2025-11-12