diff --git a/docs/TZ.md b/docs/TZ.md index b647f3b..f4b9ed2 100644 --- a/docs/TZ.md +++ b/docs/TZ.md @@ -4,7 +4,7 @@ | | | |---|---| -| Версия ТЗ | 0.30 | +| Версия ТЗ | 0.31 | | Дата | 2026-09-21 | | Статус | На обсуждении | @@ -187,6 +187,9 @@ диапазоны приоритета); - ошибки подсказывают следующий шаг («call list_projects()», «найдите id через list_tasks(query=...)»); ответ `create_task` без проекта содержит подсказку. +- В «Настройках» — ссылка на страницу-инструкцию по MCP (`/mcp-help`): что реализует, + адрес сервера (совпадает с адресом приложения), токен, примеры подключения + (Claude Code, универсальный JSON). - Аутентификация агентов — через SSO-механизм (токен, выданный централизованной системой; детали после предоставления данных SSO). - Агент действует от имени пользователя; отдельной мультитенантности нет. - Закрытие задачи агентом (`update_task`/`complete_task`) идёт по тому же общему diff --git a/frontend/src/locales/en.ts b/frontend/src/locales/en.ts index 3538d05..79a3ffe 100644 --- a/frontend/src/locales/en.ts +++ b/frontend/src/locales/en.ts @@ -433,6 +433,40 @@ langRu: 'Русский', langEn: 'English', langUk: 'Українська', + mcpHint: 'AI agents (e.g. Claude) can work with your tasks via MCP.', + mcpOpen: 'How to connect', + }, + mcp: { + title: 'MCP for AI agents', + whatTitle: 'What it is', + whatText: + 'The app has a built-in MCP server (Model Context Protocol): AI agents connect to it and manage your tasks on your behalf — creating, finding, updating and closing them. Closing a task via an agent earns the same rewards as in the app: XP, coins, a plant in the garden; the next instance of a recurring task is created automatically.', + toolsTitle: 'Tools', + toolsHint: + 'The server explains the workflow to the agent itself: start with projects, attach tasks to a project, never invent identifiers, and follow the hints in error messages.', + toolListProjects: 'list of projects: notes, status, open task count', + toolGetProject: 'project context: note and open tasks', + toolCreateTask: 'create a task (a title is enough, project recommended)', + toolUpdateTask: 'update task fields; closing is status="done"', + toolCompleteTask: 'complete a task (actual time optional)', + toolListTasks: 'search and filters: project, tag, status, substring', + toolGetTask: 'full task data, including attachments', + toolListTags: 'tag reference', + connectTitle: 'How to connect an agent', + connectText: + 'Transport is Streamable HTTP. The address matches this app’s address. You will need an access token to connect.', + connectUrlLabel: 'Server address', + connectTokenLabel: 'Access token', + connectTokenText: + 'Authorization is a bearer token: the MCP_TOKEN setting in the backend config (environment variable / .env; never committed). One token for all agents — treat it like a password: anyone holding it can manage your tasks.', + connectClaudeLabel: 'Claude Code — one command', + connectJsonLabel: 'Universal JSON (Claude Desktop and other clients)', + copy: 'Copy', + copied: 'Address copied', + copyFailed: 'Failed to copy', + projectTitle: 'Project context', + projectText: + 'The agent sees your projects with their notes and open tasks. The server instructs the agent to start from projects (list_projects → get_project), attach created tasks to a project, and re-read get_project when returning to a conversation after a break — so tasks never lose their project context.', }, md: { bold: 'Bold', diff --git a/frontend/src/locales/ru.ts b/frontend/src/locales/ru.ts index 2a30dfe..7a05081 100644 --- a/frontend/src/locales/ru.ts +++ b/frontend/src/locales/ru.ts @@ -434,6 +434,40 @@ langRu: 'Русский', langEn: 'English', langUk: 'Українська', + mcpHint: 'ИИ-агенты (например, Claude) могут работать с вашими задачами через MCP.', + mcpOpen: 'Как подключить', + }, + mcp: { + title: 'MCP для ИИ-агентов', + whatTitle: 'Что это такое', + whatText: + 'В приложение встроен MCP-сервер (Model Context Protocol): ИИ-агенты подключаются к нему и работают с вашими задачами от вашего имени — создают, ищут, обновляют и закрывают их. Закрытие задачи агентом даёт те же награды, что и в приложении: XP, монеты, растение в саду; у регулярной задачи следующий экземпляр создаётся автоматически.', + toolsTitle: 'Инструменты', + toolsHint: + 'Сервер сам объясняет агенту порядок работы: начинать с проектов, привязывать задачи к проекту, не придумывать идентификаторы и следовать подсказкам в ошибках.', + toolListProjects: 'список проектов: заметки, статус, число открытых задач', + toolGetProject: 'контекст проекта: заметка и открытые задачи', + toolCreateTask: 'создать задачу (достаточно заголовка, желательно с проектом)', + toolUpdateTask: 'обновить поля задачи; закрытие — status="done"', + toolCompleteTask: 'завершить задачу (можно указать фактическое время)', + toolListTasks: 'поиск и фильтры: проект, тег, статус, подстрока', + toolGetTask: 'полные данные задачи, включая вложения', + toolListTags: 'справочник тегов', + connectTitle: 'Как подключить агента', + connectText: + 'Транспорт — Streamable HTTP. Адрес совпадает с адресом этого приложения. Для подключения понадобится токен доступа.', + connectUrlLabel: 'Адрес сервера', + connectTokenLabel: 'Токен доступа', + connectTokenText: + 'Авторизация — bearer-токен: значение настройки MCP_TOKEN в конфиге backend (переменная окружения, в .env; в репозиторий не попадает). Один токен для всех агентов — храните его как пароль: любой, у кого он есть, может управлять задачами.', + connectClaudeLabel: 'Claude Code — одна команда', + connectJsonLabel: 'Универсальный JSON (Claude Desktop и другие клиенты)', + copy: 'Скопировать', + copied: 'Адрес скопирован', + copyFailed: 'Не удалось скопировать', + projectTitle: 'Контекст проекта', + projectText: + 'Агент видит ваши проекты с заметками и их открытые задачи. Сервер инструктирует агента начинать работу с проектов (list_projects → get_project), привязывать создаваемые задачи к проекту и перечитывать get_project, возвращаясь к разговору после перерыва, — так задачи не теряются вне контекста своего проекта.', }, md: { bold: 'Жирный', diff --git a/frontend/src/locales/uk.ts b/frontend/src/locales/uk.ts index f314eef..f60bab3 100644 --- a/frontend/src/locales/uk.ts +++ b/frontend/src/locales/uk.ts @@ -433,6 +433,40 @@ langRu: 'Русский', langEn: 'English', langUk: 'Українська', + mcpHint: "ІІ-агенти (наприклад, Claude) можуть працювати з вашими задачами через MCP.", + mcpOpen: 'Як підключити', + }, + mcp: { + title: 'MCP для ІІ-агентів', + whatTitle: 'Що це таке', + whatText: + 'У застосунок вбудовано MCP-сервер (Model Context Protocol): ІІ-агенти підключаються до нього й працюють з вашими задачами від вашого імені — створюють, шукають, оновлюють і закривають їх. Закриття задачі агентом дає ті самі нагороди, що й у застосунку: XP, монети, рослину в саду; у регулярної задачі наступний екземпляр створюється автоматично.', + toolsTitle: 'Інструменти', + toolsHint: + 'Сервер сам пояснює агенту порядок роботи: починати з проєктів, привʼязувати задачі до проєкту, не вигадувати ідентифікатори та слідувати підказкам у помилках.', + toolListProjects: 'список проєктів: нотатки, статус, кількість відкритих задач', + toolGetProject: 'контекст проєкту: нотатка і відкриті задачі', + toolCreateTask: 'створити задачу (досить заголовка, бажано з проєктом)', + toolUpdateTask: 'оновити поля задачі; закриття — status="done"', + toolCompleteTask: 'завершити задачу (можна вказати фактичний час)', + toolListTasks: 'пошук і фільтри: проєкт, тег, статус, підрядок', + toolGetTask: 'повні дані задачі, включно з вкладеннями', + toolListTags: 'довідник тегів', + connectTitle: 'Як підключити агента', + connectText: + 'Транспорт — Streamable HTTP. Адреса збігається з адресою цього застосунку. Для підключення потрібен токен доступу.', + connectUrlLabel: 'Адреса сервера', + connectTokenLabel: 'Токен доступу', + connectTokenText: + 'Авторизація — bearer-токен: значення налаштування MCP_TOKEN у конфізі backend (змінна середовища, у .env; до репозиторію не потрапляє). Один токен для всіх агентів — зберігайте його як пароль: будь-хто, хто ним володіє, може керувати задачами.', + connectClaudeLabel: 'Claude Code — одна команда', + connectJsonLabel: 'Універсальний JSON (Claude Desktop та інші клієнти)', + copy: 'Копіювати', + copied: 'Адресу скопійовано', + copyFailed: 'Не вдалося скопіювати', + projectTitle: 'Контекст проєкту', + projectText: + 'Агент бачить ваші проєкти з нотатками та їхні відкриті задачі. Сервер інструктує агента починати роботу з проєктів (list_projects → get_project), привʼязувати створювані задачі до проєкту й перечитувати get_project, повертаючись до розмови після перерви, — так задачі не губляться поза контекстом свого проєкту.', }, md: { bold: 'Жирний', diff --git a/frontend/src/main.ts b/frontend/src/main.ts index 6519de0..b3d671b 100644 --- a/frontend/src/main.ts +++ b/frontend/src/main.ts @@ -19,6 +19,7 @@ import SettingsView from './views/SettingsView.vue' import StackView from './views/StackView.vue' import TaskView from './views/TaskView.vue' +import McpView from './views/McpView.vue' const router = createRouter({ history: createWebHistory(), @@ -36,6 +37,9 @@ { path: '/tasks/:id', component: TaskView, meta: { title: 'nav.task' } }, { path: '/options', component: OptionsView, meta: { title: 'nav.options' } }, { path: '/settings', component: SettingsView, meta: { title: 'nav.settings' } }, + // инструкция по MCP для агентов — ссылка из «Настроек» (ТЗ 3.10). + // Путь /mcp занят самим MCP-сервером — страница живёт на /mcp-help + { path: '/mcp-help', component: McpView, meta: { title: 'mcp.title' } }, ], }) diff --git a/frontend/src/views/McpView.vue b/frontend/src/views/McpView.vue new file mode 100644 index 0000000..17646ef --- /dev/null +++ b/frontend/src/views/McpView.vue @@ -0,0 +1,184 @@ + + + + + \ No newline at end of file diff --git a/frontend/src/views/SettingsView.vue b/frontend/src/views/SettingsView.vue index d354083..3298b1a 100644 --- a/frontend/src/views/SettingsView.vue +++ b/frontend/src/views/SettingsView.vue @@ -1,6 +1,7 @@