Metadata-Version: 2.5
Name: nuvo-mcp
Version: 0.1.0
Summary: An MCP server for Nuvo tasks: an agent manages them through the same HTTP API as the app
Project-URL: Homepage, https://github.com/darenwhite79/nuvo-mcp
Project-URL: Repository, https://github.com/darenwhite79/nuvo-mcp
Project-URL: Changelog, https://github.com/darenwhite79/nuvo-mcp/blob/main/CHANGELOG.md
Project-URL: App, https://github.com/darenwhite79/nuvo-task-manager
Project-URL: Issues, https://github.com/darenwhite79/nuvo-mcp/issues
Author: Igor T
License: MIT
License-File: LICENSE
Keywords: gtd,mcp,model-context-protocol,nuvo,tasks,todo
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Scheduling
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=2.1.1
Description-Content-Type: text/markdown

# nuvo-mcp

**Дела [Nuvo](https://github.com/darenwhite79/nuvo-task-manager) — руками помощника.**

[![Проверки](https://github.com/darenwhite79/nuvo-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/darenwhite79/nuvo-mcp/actions/workflows/ci.yml)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-server-8A2BE2)](https://modelcontextprotocol.io/)
[![Лицензия MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

MCP-сервер к [Nuvo](https://github.com/darenwhite79/nuvo-task-manager) — менеджеру
дел, устроенному как область → проект → дело, с чек-листом и тегами. Даёт
помощнику двадцать один инструмент: смотреть «Сегодня», заводить и менять дела,
дописывать заметки, вести чек-лист, вешать теги, создавать проекты и области.

Сервер ходит в то же HTTP-API, что и приложение, — не в базу. Поэтому он
подчиняется правам ключа, всё сделанное видно в приложении сразу и записано в
журнал ключа.

```
Вы:       Что у меня сегодня?
Помощник: → today
          Сегодня три дела:
          • Позвонить в банк · срок 20 октября
          • Забрать посылку
          • Дописать раздел про оплату

Вы:       Дозвонился, привезут в среду. Отметь и запиши.
Помощник: → add_note(3, "Дозвонился, привезут в среду")
          → complete_task(3)
          Готово. В заметке появился абзац с сегодняшней датой.
```

## Запуск за три шага

**1. Поднимите Nuvo** — приложение слушает `http://127.0.0.1:8000`.

**2. Выдайте ключ** — «Настройки → Подключение» → «Выдать ключ». Токен
показывается один раз.

**3. Подключите к своему помощнику.** Пример для Claude Code:

```bash
claude mcp add nuvo -s user \
  -e NUVO_TOKEN=nv_ваш_ключ \
  -e NUVO_URL=http://127.0.0.1:8000 \
  -- uvx --from git+https://github.com/darenwhite79/nuvo-mcp.git nuvo-mcp
```

Спросите: «что у меня сегодня?» — должен ответить списком.

Остальные клиенты — **Claude Desktop, Cursor, VS Code, Windsurf, Zed** — с
готовыми блоками настройки: [docs/clients.md](docs/clients.md).

Нужен [uv](https://docs.astral.sh/uv/): `brew install uv` или
`curl -LsSf https://astral.sh/uv/install.sh | sh`. `uvx` ставит пакет во
временное окружение сам, Python настраивать не надо.

## Настройка

| Переменная   | Обязательна | По умолчанию            | Что это                              |
|--------------|-------------|-------------------------|--------------------------------------|
| `NUVO_TOKEN` | да          | —                       | Ключ доступа, выдаётся в приложении  |
| `NUVO_URL`   | нет         | `http://127.0.0.1:8000` | Адрес, на котором поднято приложение |

Ключ без интерфейса — запросом:

```bash
curl -X POST http://127.0.0.1:8000/api/keys \
  -H 'Content-Type: application/json' \
  -d '{"title":"Мой помощник","scopes":"read,create,edit"}'
```

Права ключа — `read`, `create`, `edit`, `delete` — ограничивают и помощника:
ключ без `edit` не даст ничего изменить, и отказ помощник увидит словами.

## Что умеет

| Смотреть | |
|---|---|
| `list_lists` | Проекты, области, теги и отборы — одними названиями |
| `list_tasks` | Дела с отбором по «когда», проекту или тегу |
| `today` | Что стоит на сегодня и что просрочено |
| `search_tasks` | Поиск по названию и заметке — чтобы не плодить дубли |
| `get_task` | Одно дело целиком: заметка, чек-лист, теги, сроки |

| Заводить и менять | |
|---|---|
| `create_task` | Новое дело: «когда», срок, проект, теги |
| `update_task` | Название, заметка целиком, срок |
| `add_note` | Дописать к заметке абзац с датой — здешняя замена комментариям |
| `move_task` | Перенести в проект или область |
| `create_project`, `create_area` | Завести проект или область |

| Состояние | |
|---|---|
| `schedule_task` | «Сегодня», «Вечером», «В любое время», «Когда-нибудь» или дата |
| `complete_task` | Сделано; повторяющееся само родит следующее |
| `reopen_task` | Вернуть в работу |
| `log_task` | Убрать завершённое в журнал |
| `trash_task`, `restore_task` | В корзину и обратно |

| Чек-лист и теги | |
|---|---|
| `add_checklist_item`, `check_checklist_item` | Пункт внутри дела |
| `tag_task`, `untag_task` | Повесить и снять тег |

**Окончательного удаления у помощника нет намеренно.** Корзину чистит человек.

Полные описания, которые видит модель, — в
[`src/nuvo_mcp/tools.py`](src/nuvo_mcp/tools.py).

## Чтобы помощник вёл дела осмысленно

Сервер сам объясняет клиенту правила: «Сегодня» — обещание сделать сегодня, а
не пометка важности; срок и день выполнения — разные вещи; перед созданием дела
поискать похожее.

Готовые системные подсказки под свои привычки — [docs/prompts.md](docs/prompts.md).

## Устройство

```
src/nuvo_mcp/api.py      клиент к HTTP-API и перевод ошибок на человеческий
src/nuvo_mcp/tools.py    инструменты обычными функциями + их описания
src/nuvo_mcp/server.py   регистрация в MCP и запуск по stdio
```

Зависимости — только `mcp` и `httpx`: пакет самодостаточен и ничего не знает
о приложении, кроме адреса.

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

```bash
uv sync
uv run pytest        # без сети и без бэкенда: HTTP подменён транспортом httpx
uv run ruff check .
uv run ruff format --check .
```

Работу против живого API проверяют тесты приложения —
`backend/tests/test_mcp.py` в [nuvo-task-manager](https://github.com/darenwhite79/nuvo-task-manager).

## Лицензия

[MIT](LICENSE).
