# BCS MCP GitLab

Форк [@zereight/mcp-gitlab](https://github.com/zereight/gitlab-mcp) (upstream v2.1.38): MCP-сервер для GitLab BCS.

Оригинальный README: [README.upstream.md](README.upstream.md).

## Что это

Интеграция GitLab (`gitlab.gitlab.bcs.ru`) с MCP-клиентами (Cursor, Claude и др.) для CI, репозиториев, merge requests и issues.

## Что добавлено в форке

- Дефолты BCS: `GITLAB_API_URL`, `GITLAB_TOOLSETS`, `GITLAB_PERMISSION_MODE=modify`, `GITLAB_DENIED_TOOLS_REGEX`, `User-Agent=BCS-MCP-GITLAB` (`GITLAB_BCS_DEFAULTS=true` по умолчанию).
- Маскирование описаний MR/issue и user-полей через `CONTENT_MASK_SERVICE_URL` (mai-ms-masking-it-proxy).
- Публикация npm-пакета `bcs-mcp-gitlab` в Artifactory, CI в `.gitlab-ci.yml`.
- Документация релизов: [docs/RELEASES.md](docs/RELEASES.md), [docs/RELEASE_NOTES.md](docs/RELEASE_NOTES.md).

## Установка и запуск

Требуется Node.js ≥ 18 и PAT GitLab BCS.

### MCP-клиент (stdio)

```json
{
  "mcpServers": {
    "bcs-mcp-gitlab": {
      "command": "npx",
      "args": ["-y", "bcs-mcp-gitlab"],
      "env": {
        "GITLAB_API_URL": "https://gitlab.gitlab.bcs.ru/api/v4",
        "GITLAB_PERSONAL_ACCESS_TOKEN": "<put-your-token-here>",
        "GITLAB_TOOLSETS": "pipelines,repositories,merge_requests,issues",
        "GITLAB_READ_ONLY_MODE": "false",
        "GITLAB_PERMISSION_MODE": "modify",
        "GITLAB_DENIED_TOOLS_REGEX": "(delete_|cancel_pipeline|cancel_pipeline_job)",
        "CONTENT_MASK_SERVICE_URL": "https://apis.tusvc.bcs.ru/mai-ms-masking-it-proxy/mask/chat",
        "GITLAB_CUSTOM_HEADERS": "User-Agent=BCS-MCP-GITLAB"
      }
    }
  }
}
```

Публичный пакет: [bcs-mcp-gitlab на npmjs](https://www.npmjs.com/package/bcs-mcp-gitlab).

```bash
npx -y bcs-mcp-gitlab
```

### Cursor (конфиг проекта)

1. `npm run build`
2. Скопируйте [`.cursor/mcp.json.example`](.cursor/mcp.json.example) → `.cursor/mcp.json`
3. Укажите `GITLAB_PERSONAL_ACCESS_TOKEN` в `env`
4. Перезагрузите MCP в Cursor — появится сервер **`bcs-mcp-gitlab-dev`** (запуск из `${workspaceFolder}/build/index.js`)

### Локальная разработка

```bash
npm ci
npm run build
npm run test:bcs
GITLAB_PERSONAL_ACCESS_TOKEN=... node build/index.js
```

## Content masking

При заданном `CONTENT_MASK_SERVICE_URL` маскируются (перед ответом агенту):

- **MR / issues:** `description`, `title`, `body` в notes/comments;
- **User-поля:** `author`, `assignee`, `merged_by`, reviewers и т.п.

**Не маскируются в 0.2.0:** логи CI (`get_pipeline_job_output`), содержимое файлов, diff MR.

Переменные: `CONTENT_MASK_CHUNK_MAX_CHARS`, `CONTENT_MASK_REQUEST_TIMEOUT_SECONDS`, `CONTENT_MASK_REQUEST_RETRY_COUNT`, `CONTENT_MASK_MAX_CONCURRENCY`, `CONTENT_MASK_CACHE_*` — как в [BCS Atlassian MCP](https://confluence.bcs.ru/spaces/PlatformMSAWS/pages/1493816536).

## Фильтрация tools

| Переменная | Назначение |
| --- | --- |
| `GITLAB_TOOLSETS` | Наборы tools (`pipelines`, `repositories`, `merge_requests`, `issues`, …) |
| `GITLAB_TOOLS` | Отдельные tools поверх toolsets |
| `GITLAB_PERMISSION_MODE` | `modify` (дефолт BCS) — CRU без Delete; `readonly` — только чтение; `full` — все |
| `GITLAB_READ_ONLY_MODE` | Legacy: `true` форсирует `readonly` (только read-tools) |
| `GITLAB_DENIED_TOOLS_REGEX` | Regex-исключение по имени tool (дефолт: `delete_` / cancel pipeline) |
| `GITLAB_BCS_DEFAULTS` | `false` — отключить корпоративные дефолты |

## Репозиторий и релизы

- GitLab: https://gitlab.gitlab.bcs.ru/bcs-mai/mcp/bcs-mcp-gitlab
- Confluence: https://confluence.bcs.ru/spaces/PlatformMSAWS/pages/1507146606
- Релизы: ветка `release/X.Y.Z` → CI publish на npmjs.com (см. [docs/RELEASES.md](docs/RELEASES.md))

## Карта репозитория

| Path | Назначение |
| --- | --- |
| `index.ts` | MCP server, tools, transport |
| `config.ts` | Env / CLI |
| `utils/bcsDefaults.ts` | BCS-дефолты |
| `utils/contentMask.ts` | Маскирование ответов |
| `test/` | Unit и mock-тесты |

## Лицензия

MIT (upstream zereight/gitlab-mcp). См. [LICENSE](LICENSE), [NOTICE](NOTICE).