@ekho/gitlab-mcp 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Boris Gorbylev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PLAN.md

@@ -0,0 +1,517 @@
+# GitLab MCP — план реализации
+
+## 0. Текущий прогресс
+
+| Фаза | Группа | Статус | Версия |
+|---|---|---|---|
+| 0 | Скелет проекта | ✅ Готово | 0.0.1 |
+| 1 | B — Совместная работа | ✅ Готово | 0.1.0 |
+| 2 | C — CI/CD | ✅ Готово | 0.2.0 |
+| 3 | A — Код и репозиторий | ✅ Готово | 0.3.0 |
+| 4 | D — Релизы и доставка | ✅ Готово | 0.4.0 |
+| 5 | F — Доступ и пользователи | ✅ Готово | 0.5.0 |
+| 6 | E — Безопасность и compliance | ✅ Готово | 0.6.0 |
+| 7 | G — Интеграции и события | ✅ Готово | 0.7.0 |
+| 8 | H — Контент | ✅ Готово | 0.8.0 |
+| 9 | J — Аналитика и админка | ✅ Готово | 0.9.0 |
+| 10 | I — AI / GitLab Duo | ✅ Готово | 1.0.0 |
+
+## 1. Цели
+
+Реализовать MCP-сервер для GitLab, который умеет работать одновременно с **REST API** и **GraphQL** и выбирает оптимальный транспорт под каждую операцию. С первого релиза — **read + write**. Первичная цель — **gitlab.com**, по возможности совместимость с **self-hosted** (EE/CE).
+
+## 2. Стек
+
+- **Язык:** TypeScript (Node 20+)
+- **MCP SDK:** `@modelcontextprotocol/sdk` (stdio-transport)
+- **HTTP:** `undici` (нативный fetch с лучшим контролем connection pool)
+- **GraphQL:** `graphql-request` или сырые POST через тот же HTTP-клиент (легче для batch/типизации схемы)
+- **Валидация:** `zod` для входов/выходов MCP-tools
+- **Тесты:** `vitest` + `nock`/`msw` для HTTP-моков; smoke-тесты против реального gitlab.com через переменные окружения
+
+## 3. Аутентификация и конфигурация
+
+Поддерживаемые типы токенов:
+- Personal Access Token (PAT) — основной для разработки
+- Project / Group Access Token — для скоупа в проде
+- OAuth2 access token — для интеграций пользователя
+- Job Token (CI) — read-only варианты, для запуска MCP внутри пайплайнов
+
+Конфигурация (env / MCP server config):
+- `GITLAB_BASE_URL` (default: `https://gitlab.com`)
+- `GITLAB_TOKEN`
+- `GITLAB_TOKEN_TYPE` (`pat` | `oauth` | `job`) — влияет на заголовок (`PRIVATE-TOKEN` vs `Authorization: Bearer` vs `JOB-TOKEN`)
+- `GITLAB_DEFAULT_PROJECT` (опционально) — чтобы не таскать `project_id` в каждом вызове
+- `GITLAB_DEFAULT_GROUP` (опционально)
+
+## 4. Архитектура
+
+```
+src/
+  index.ts            # MCP entry, регистрация tools
+  config.ts           # парсинг env, валидация
+  http/
+    rest.ts           # REST клиент (pagination, rate limit, error mapping)
+    graphql.ts        # GraphQL клиент
+    errors.ts         # унифицированные ошибки GitLabApiError
+  groups/
+    work_items/       # B: каждая группа — папка с tools.ts + handlers.ts + schemas.ts
+    merge_requests/
+    pipelines/
+    ...
+  shared/
+    pagination.ts     # REST keyset + offset; GraphQL cursor
+    ids.ts            # резолв project/group по id или path
+    markdown.ts       # хелперы для GitLab Flavored Markdown (suggestions, mentions)
+  tools.ts            # сборка манифеста всех tools
+```
+
+Соглашения:
+- Имена MCP-tools: `<resource>_<verb>`, snake_case (`merge_request_list`, `pipeline_retry`, `work_item_create`).
+- Любой tool, делающий запись, принимает `dry_run: boolean` где это осмысленно.
+- Идентификатор проекта/группы — либо числовой `id`, либо URL-encoded `path` (`group%2Fproject`). Хелпер `resolveProjectId()` это маскирует.
+- Пагинация: tools отдают первую страницу + `next_cursor`. Опционально `auto_paginate: true` (с потолком, чтобы не утечь по rate limit).
+- Rate limit: на 429 — экспоненциальный бэкофф с честным `Retry-After`.
+
+## 5. Транспортные правила
+
+| Случай | Выбор |
+|---|---|
+| Work Items, Epics, иерархия parent/children | **GraphQL** (REST не покрывает Work Items полностью) |
+| Большие списки с фильтрами и nested полями | **GraphQL** (меньше round-trips) |
+| Файловые операции, batch commits, raw content | **REST** |
+| CI Catalog, Duo, Security Policies, Custom Roles, Secrets Management | **GraphQL only** |
+| Простой CRUD одной сущности | **REST** (проще, меньше схемы) |
+
+---
+
+# 6. Группы (в порядке реализации)
+
+Приоритет: **B → C → A → D → F → E → G → H → J → I**.
+
+Каждая группа — это отдельная фаза. После каждой фазы — релиз минорной версии и smoke-тесты.
+
+---
+
+## Фаза 1 — Группа B: Совместная работа
+
+> **Статус: ✅ Готово (v0.1.0).** 55+ tools, 32/32 unit-теста зелёные. Отличия от исходного плана: approval rules — только project-level (MR-level overrides отложены); boards — read-only; iterations — только list. Epics через `work_item_*` с `type=Epic` (отдельных epic tools нет).
+
+### B1. Merge Requests (REST + GraphQL)
+- `merge_request_list` — фильтры: state, author, assignee, reviewer, scope, labels, milestone, target_branch, source_branch, search, updated_after
+- `merge_request_get`
+- `merge_request_create` — source/target branch, title, description, assignees, reviewers, labels, milestone, remove_source_branch, squash, draft
+- `merge_request_update` — title, description, assignees, reviewers, labels, milestone, target_branch, state_event, draft
+- `merge_request_merge` — squash, merge_commit_message, sha, should_remove_source_branch
+- `merge_request_rebase`
+- `merge_request_close` / `merge_request_reopen`
+- `merge_request_changes` (diff)
+- `merge_request_commits`
+- `merge_request_pipelines`
+- `merge_request_participants`
+
+### B2. Reviews & Approvals
+- `merge_request_approve` / `merge_request_unapprove`
+- `merge_request_approval_state`
+- `approval_rule_list` / `approval_rule_create` / `approval_rule_update` / `approval_rule_delete`
+
+### B3. Discussions & Notes
+- `discussion_list` (issue/MR/commit)
+- `discussion_create` — general и inline (с position для diff)
+- `discussion_reply`
+- `discussion_resolve` / `discussion_unresolve`
+- `note_update` / `note_delete`
+- `suggestion_create` — обёртка над `note_create` с блоком ```suggestion (только для MR diff)
+
+### B4. Issues / Work Items (преимущественно GraphQL)
+- `work_item_list` — фильтры: state, type (issue/task/incident/epic), assignee, author, labels, milestone, iteration, due_date, confidential, search
+- `work_item_get`
+- `work_item_create` — namespace, type, title, description, assignees, labels, milestone, parent_id, confidential
+- `work_item_update` — title, description, state, assignees, labels, milestone, iteration, due_date, weight, health_status, parent
+- `work_item_delete`
+- `issue_link_list` / `issue_link_create` / `issue_link_delete` (relates_to, blocks, is_blocked_by)
+
+### B5. Epics
+Используем `work_item_*` с `type=EPIC`. Отдельных tools не плодим — иерархия через `parent_id`/`children`. Для legacy-инстансов на старых версиях GitLab — fallback на REST `/groups/:id/epics` (отложено в техдолг).
+
+### B6. Labels
+- `label_list_project` / `label_list_group`
+- `label_create` / `label_update` / `label_delete`
+- `label_subscribe` / `label_unsubscribe`
+- Поддержка scoped labels (`scope::value`) — просто строкой
+
+### B7. Milestones & Iterations
+- `milestone_list_project` / `milestone_list_group`
+- `milestone_create` / `milestone_update` / `milestone_close` / `milestone_delete`
+- `iteration_list_group` / `iteration_create` / `iteration_update`
+
+### B8. Boards
+- `board_list_project` / `board_list_group`
+- `board_get`
+- `board_list_lists` / `board_create_list` / `board_delete_list`
+- (write-операции по drag & drop в MVP не делаем — у боардов сложная семантика позиций)
+
+### B9. Todos & Notifications
+- `todo_list` — state (pending/done), type, project_id
+- `todo_mark_done` / `todo_mark_all_done`
+- `notification_settings_get` / `notification_settings_update`
+
+**DoD фазы 1:** запускается локально, читает свой собственный issue tracker, создаёт MR с разметкой ревьюеров, оставляет inline-комментарий с suggestion, мержит после approve.
+
+---
+
+## Фаза 2 — Группа C: CI/CD
+
+> **Статус: ✅ Готово (v0.2.0).** ~52 tools. Отличия от плана: job artifact download (бинарные данные) пропущен — `job_get` отдаёт метаданные, скачивать удобнее напрямую через URL. Runner `register_runner` не реализован (deprecated в новых версиях).
+
+### C1. Pipelines
+- `pipeline_list` — фильтры: status, ref, sha, source, username, updated_after, name
+- `pipeline_get` / `pipeline_get_latest`
+- `pipeline_create` — ref, variables[]
+- `pipeline_retry` / `pipeline_cancel` / `pipeline_delete`
+- `pipeline_variables`
+- `pipeline_test_report` / `pipeline_test_report_summary`
+
+### C2. Jobs
+- `job_list_pipeline` / `job_list_project`
+- `job_get`
+- `job_log` — trace, с опциональным offset/limit и `tail` режимом
+- `job_retry` / `job_cancel` / `job_play` (manual jobs с variables) / `job_erase`
+- `job_artifacts_list` / `job_artifact_download` / `job_artifacts_keep` / `job_artifacts_delete`
+
+### C3. Pipeline Schedules
+- `schedule_list` / `schedule_get`
+- `schedule_create` / `schedule_update` / `schedule_delete`
+- `schedule_play` / `schedule_take_ownership`
+- `schedule_variable_create` / `schedule_variable_update` / `schedule_variable_delete`
+
+### C4. Pipeline Triggers
+- `trigger_list` / `trigger_create` / `trigger_revoke`
+- `trigger_run_pipeline` — token + ref + variables
+
+### C5. CI/CD Variables
+- `variable_list_project` / `variable_get_project` / `variable_create_project` / `variable_update_project` / `variable_delete_project`
+- Аналогично для `group` и `instance`
+- Поля: key, value, protected, masked, environment_scope, raw, description, variable_type
+
+### C6. Runners
+- `runner_list` (instance/group/project), фильтры: scope, type, status, paused, tag_list
+- `runner_get`
+- `runner_update` / `runner_pause` / `runner_delete`
+- `runner_jobs`
+- `runner_register` (через registration token; флагнуть deprecation в 17+)
+
+### C7. CI Lint / Config
+- `ci_lint` — content (опционально с project_id для контекста include)
+- `ci_config_merged_get` — итоговый YAML с подставленными includes
+
+### C8. CI Catalog (GraphQL)
+- `catalog_resource_list`
+- `catalog_resource_get`
+
+**DoD фазы 2:** через MCP можно перезапустить упавший пайплайн, дочитать лог job-а, поднять переменную окружения для feature-флага.
+
+---
+
+## Фаза 3 — Группа A: Код и репозиторий
+
+> **Статус: ✅ Готово (v0.3.0).** ~57 tools. `code_search`/`commit_search`/`wiki_search` идут через REST `/search?scope=` (на gitlab.com работает с advanced search; на self-hosted без Elasticsearch — degraded). GraphQL `blobSearch` не использовался — REST покрывает кейс с меньшей зависимостью от версии.
+
+### A1. Projects
+- `project_list` — фильтры: membership, owned, starred, archived, search, visibility, with_issues_enabled, etc.
+- `project_get`
+- `project_create` / `project_fork`
+- `project_update` / `project_archive` / `project_unarchive` / `project_delete`
+- `project_statistics`
+- `project_languages`
+
+### A2. Groups
+- `group_list` / `group_get`
+- `group_create` / `group_update` / `group_delete`
+- `group_subgroups` / `group_descendants`
+- `group_projects` / `group_shared_projects`
+- `group_transfer_project`
+
+### A3. Repository files
+- `file_get` — path, ref → base64 content, sha, size, encoding
+- `file_get_raw`
+- `file_create` / `file_update` / `file_delete` (одиночные)
+- `file_blame`
+- `commit_actions` — batch: массив `{action: create|update|delete|move, file_path, content, ...}` в одном коммите
+- `tree_list` — листинг директории, recursive
+
+### A4. Branches
+- `branch_list` / `branch_get`
+- `branch_create` (ref source) / `branch_delete`
+- `protected_branch_list` / `protected_branch_protect` / `protected_branch_unprotect`
+- `protected_branch_update` — allowed_to_push, allowed_to_merge, code_owner_approval_required
+
+### A5. Tags
+- `tag_list` / `tag_get`
+- `tag_create` — message, release_description
+- `tag_delete`
+- `protected_tag_list` / `protected_tag_protect` / `protected_tag_unprotect`
+
+### A6. Commits
+- `commit_list` — ref, since, until, path, author
+- `commit_get` / `commit_diff`
+- `commit_cherry_pick` / `commit_revert`
+- `commit_comment_list` / `commit_comment_create`
+- `commit_status_list` / `commit_status_set` (внешние CI-статусы)
+
+### A7. Compare / Diff
+- `repository_compare` — from, to, straight
+- `repository_merge_base`
+
+### A8. Code search
+- `search_blobs` — global / group / project scope, через GraphQL `blobSearch` где доступно
+- `search_commits` / `search_wiki_blobs`
+
+**DoD фазы 3:** через MCP можно прочитать `README.md`, создать ветку, закоммитить batch-изменение в нескольких файлах, найти все упоминания строки в репозитории.
+
+---
+
+## Фаза 4 — Группа D: Релизы и доставка
+
+> **Статус: ✅ Готово (v0.4.0).** ~45 tools. Скачивание содержимого пакетов (Maven/NPM/PyPI raw protocols) не входит — только метаданные + delete. Dependency Proxy опущен по плану. Container expiration policy — через `project_update` с `container_expiration_policy_attributes` (отдельных tools нет).
+
+### D1. Releases
+- `release_list` / `release_get`
+- `release_create` / `release_update` / `release_delete`
+- `release_link_list` / `release_link_create` / `release_link_delete`
+
+### D2. Environments
+- `environment_list` / `environment_get`
+- `environment_create` / `environment_update` / `environment_delete` / `environment_stop`
+
+### D3. Deployments
+- `deployment_list` / `deployment_get`
+- `deployment_create`
+- `deployment_approve` — для protected environments
+
+### D4. Feature Flags
+- `feature_flag_list` / `feature_flag_get`
+- `feature_flag_create` / `feature_flag_update` / `feature_flag_delete`
+- `feature_flag_user_list_list` / `feature_flag_user_list_create` / ...
+
+### D5. Packages
+- `package_list_project` / `package_list_group`
+- `package_get` / `package_files`
+- `package_delete`
+- (upload/download конкретных форматов — не в MVP, требует отдельных протоколов)
+
+### D6. Container Registry
+- `registry_repository_list_project` / `registry_repository_list_group`
+- `registry_repository_get` / `registry_repository_delete`
+- `registry_tag_list` / `registry_tag_get`
+- `registry_tag_delete` / `registry_tag_bulk_delete` (по name_regex)
+- `registry_cleanup_policy_get` / `registry_cleanup_policy_update`
+
+### D7. Dependency Proxy
+Отложено: чисто instance-настройка, редкий use case.
+
+**DoD фазы 4:** через MCP можно зарелизить тег с changelog'ом, утвердить деплой в production, протухший тег в registry — удалить.
+
+---
+
+## Фаза 5 — Группа F: Доступ и пользователи
+
+> **Статус: ✅ Готово (v0.5.0).** ~45 tools. `user_current` уже в meta — не дублируется. PAT self-creation через `/personal_access_tokens/self` (требует GitLab 16.5+); для старых инстансов или создания за другого пользователя — `pat_create_for_user` (admin). Custom roles — только group-level через GraphQL (instance-level требует admin-only схемы, не реализовано).
+
+### F1. Users
+- `user_list` / `user_get` / `user_current`
+- `user_search` (username/email)
+- `user_create` / `user_update` / `user_delete` (admin)
+- `user_block` / `user_unblock` / `user_activate` / `user_deactivate`
+
+### F2. Members
+- `member_list_project` / `member_list_group` (all / direct)
+- `member_get`
+- `member_add` — user_id, access_level, expires_at, member_role_id
+- `member_update`
+- `member_remove`
+- `billable_member_list_group` (только gitlab.com / paid)
+
+### F3. Access Tokens
+- `pat_list_self` / `pat_create_self` / `pat_revoke`
+- `project_access_token_list` / `project_access_token_create` / `project_access_token_revoke` / `project_access_token_rotate`
+- `group_access_token_list` / `group_access_token_create` / `group_access_token_revoke` / `group_access_token_rotate`
+
+### F4. SSH/GPG/Deploy Keys
+- `ssh_key_list` / `ssh_key_create` / `ssh_key_delete`
+- `gpg_key_list` / `gpg_key_create` / `gpg_key_delete`
+- `deploy_key_list_project` / `deploy_key_add` / `deploy_key_enable` / `deploy_key_delete`
+
+### F5. Custom Roles (GraphQL, premium+)
+- `member_role_list` / `member_role_get`
+- `member_role_create` / `member_role_update` / `member_role_delete`
+
+**DoD фазы 5:** через MCP можно пригласить пользователя в проект с нужной ролью, ротировать project access token.
+
+---
+
+## Фаза 6 — Группа E: Безопасность и compliance
+
+> Большинство фич — Premium/Ultimate. На CE/Free часть tools будет возвращать «not available on this tier» — это нормально, обрабатываем как ожидаемую ошибку.
+
+> **Статус: ✅ Готово (v0.6.0).** ~45 tools. Vulnerability listing — через GraphQL (REST endpoint deprecated); state changes (dismiss/confirm/resolve/revert) — REST. Security policies — read-only (write через policy MR в специальном repo). Secrets Manager: project (17.8+), group (18.9+). Compliance assign-to-project — через GraphQL `projectSetComplianceFramework`. Streaming destinations — пока только HTTP (GCP/AWS назначения не реализованы).
+
+### E1. Vulnerabilities
+- `vulnerability_list_project` / `vulnerability_list_group`
+- `vulnerability_get`
+- `vulnerability_dismiss` / `vulnerability_confirm` / `vulnerability_resolve` / `vulnerability_revert_to_detected`
+- `vulnerability_create_issue`
+
+### E2. Security Reports
+- `security_report_list_pipeline` — SAST, DAST, Dependency Scanning, Secret Detection, Container Scanning
+- `vulnerability_finding_list`
+
+### E3. Security Policies (GraphQL, read-only в MVP)
+- `security_policy_list_project` / `security_policy_list_group`
+- `security_policy_sync_status`
+
+### E4. Compliance Frameworks
+- `compliance_framework_list` / `compliance_framework_get`
+- `compliance_framework_create` / `compliance_framework_update` / `compliance_framework_delete`
+- `compliance_framework_assign_project`
+
+### E5. Audit Events
+- `audit_event_list_project` / `audit_event_list_group` / `audit_event_list_instance`
+- `audit_streaming_destination_list` / `audit_streaming_destination_create` / `audit_streaming_destination_update` / `audit_streaming_destination_delete`
+
+### E6. Secrets Management (GraphQL)
+- `project_secret_list` / `project_secret_get` / `project_secret_create` / `project_secret_update` / `project_secret_delete`
+- Аналогично для `group_secret_*`
+
+### E7. Protected Environments
+- `protected_environment_list` / `protected_environment_protect` / `protected_environment_unprotect`
+- (Protected branches/tags уже в A4/A5)
+
+**DoD фазы 6:** через MCP можно посмотреть свежие уязвимости из пайплайна, дисмиссить ложноположительные, выгрузить audit log за неделю.
+
+---
+
+## Фаза 7 — Группа G: Интеграции и события
+
+> **Статус: ✅ Готово (v0.7.0).** ~25 tools. Для интеграций — общий `integration_set`/`integration_get` плюс shortcut'ы для Slack, Mattermost, Jira, Microsoft Teams. Group `events` REST endpoint не существует — есть только `audit_events` (это в E5).
+
+### G1. Webhooks
+- `hook_list_project` / `hook_list_group` / `hook_list_system`
+- `hook_get` / `hook_create` / `hook_update` / `hook_delete` / `hook_test`
+- События: push, tag_push, issue, MR, note, pipeline, job, deployment, releases, feature_flag
+
+### G2. Integrations
+- `integration_list_project`
+- `integration_get` / `integration_update` / `integration_delete`
+- Отдельные shortcut-tools для популярных: `integration_set_slack`, `integration_set_jira`, `integration_set_mattermost`
+
+### G3. Events
+- `event_list_user` / `event_list_current_user`
+- `event_list_project` / `event_list_group`
+
+**DoD фазы 7:** через MCP можно поставить вебхук на push + MR события, протестировать его доставку.
+
+---
+
+## Фаза 8 — Группа H: Контент
+
+> **Статус: ✅ Готово (v0.8.0).** ~21 tools. `wiki_attachment_upload` пропущен — требует multipart, текущий REST-клиент только JSON. `search` — единый tool с `where: global|group|project` и полным набором scope'ов.
+
+### H1. Wiki
+- `wiki_list` (project / group)
+- `wiki_get` / `wiki_create` / `wiki_update` / `wiki_delete`
+- `wiki_attachment_upload`
+
+### H2. Snippets
+- `snippet_list_personal` / `snippet_list_project`
+- `snippet_get` / `snippet_create` / `snippet_update` / `snippet_delete`
+- `snippet_file_raw`
+
+### H3. Global Search
+- `search_global` — scope: projects, issues, merge_requests, milestones, users, blobs, commits, wiki_blobs, notes
+- `search_group` / `search_project`
+
+**DoD фазы 8:** через MCP можно сделать сниппет с кодом из чата и поделиться ссылкой.
+
+---
+
+## Фаза 9 — Группа J: Аналитика и админка
+
+> **Статус: ✅ Готово (v0.9.0).** ~25 tools. Value stream analytics не реализован — гора endpoint'ов под разные stages, и REST покрытие неполное. Storage breakdown — через `project_get` со `statistics=true` (отдельного REST endpoint нет). Admin-разделы (settings/applications/broadcast/license) работают только при наличии админских прав.
+
+### J1. Analytics
+- `dora_metrics_project` / `dora_metrics_group` — deployment_frequency, lead_time_for_changes, change_failure_rate, time_to_restore_service
+- `value_stream_analytics_get`
+- `contribution_analytics_get`
+- `usage_trends_get` (instance, GraphQL)
+
+### J2. Statistics
+- `storage_breakdown_project`
+- `runner_usage_get` (GraphQL)
+
+### J3. Admin / Instance (только если токен с правами admin)
+- `application_settings_get` / `application_settings_update`
+- `application_list` / `application_create` / `application_delete`
+- `broadcast_message_list` / `broadcast_message_create` / `broadcast_message_update` / `broadcast_message_delete`
+- `license_get` / `license_current`
+- `version_get` / `metadata_get`
+
+**DoD фазы 9:** через MCP можно сводку DORA метрик за квартал положить в чат.
+
+---
+
+## Фаза 10 — Группа I: AI / GitLab Duo (GraphQL only)
+
+> Доступно только на gitlab.com при включённом Duo или self-hosted Duo Enterprise.
+
+> **Статус: ✅ Готово (v1.0.0).** ~7 tools. `ai_chat_send` возвращает `request_id` + `thread_id` — ответ Duo приходит асинхронно, его нужно подтянуть `ai_message_list` с `request_ids=[<id>]`. `aiAction` mutation универсальная (поддерживает explain_code, summarize, etc.); в MVP реализован только `chat` input.
+
+### I1. Duo Chat
+- `ai_message_list` — по conversation thread
+- `ai_thread_list`
+- `ai_chat_send` (mutation) — отправка сообщения в Duo Chat и получение ответа
+- `ai_chat_context_presets`
+
+### I2. AI Catalog
+- `ai_catalog_item_list` / `ai_catalog_item_get`
+- `ai_self_hosted_model_list` (если on-prem с Duo Enterprise)
+
+**DoD фазы 10:** через MCP можно дёрнуть Duo Chat с контекстом из проекта.
+
+---
+
+# 7. Общие задачи (вне фаз)
+
+- **Phase 0 (стартовый sprint) — ✅ Готово:**
+  - Скелет проекта, tsconfig, eslint, prettier
+  - HTTP-клиент с pagination/retry/error mapping
+  - GraphQL-клиент с typed-document подходом (`graphql-codegen` от схемы gitlab.com)
+  - Аутентификация и `resolveProjectId`/`resolveGroupId`
+  - Базовый smoke-тест: `metadata_get` + `user_current`
+  - CI: lint, typecheck, unit tests, build → npm publish
+
+- **Сквозные требования к каждому tool:**
+  - Zod-схема входа и выхода
+  - Описание (для MCP discovery) с примерами
+  - Покрытие unit-тестом с моком HTTP
+  - Один happy-path integration тест против gitlab.com под env-флагом
+
+- **Документация:**
+  - `README.md` — установка, конфигурация, примеры
+  - Авто-генерация списка tools из манифеста в `TOOLS.md`
+
+# 8. Что НЕ делаем в обозримом будущем
+
+- Загрузка/скачивание пакетов конкретных форматов (Maven/NPM/PyPI raw protocol) — слишком много форматов. **Generic package формат реализован в v1.1.**
+- GitLab Pages deployment API — нишево
+- Geo replication endpoints — admin-only, узкий use case
+- Dependency Proxy — instance-настройка
+- Push/pull mirrors — настройка через Git, не через API
+
+# 9. Дополнения после v1.0
+
+## v1.1 — Multipart + Binary
+- REST-клиент расширен `requestMultipart` (FormData) и `downloadBinary` / `uploadBinary` (Buffer).
+- H1 Wiki: `wiki_attachment_upload` — multipart upload, принимает `content_base64` или `local_path`.
+- C2 Jobs: `job_artifacts_download`, `job_artifact_file_download`, `job_artifacts_download_by_ref`, `job_artifact_file_download_by_ref` — все принимают `save_to` (сохранить в файл) или возвращают base64 (с лимитом).
+- D5 Packages: `package_file_download_generic`, `package_file_upload_generic` — Generic protocol.