# elGIT MCP

Удалённый MCP-сервер для Cursor и других клиентов: поиск по репозиториям, чтение файлов и документации инстанса.

## Адрес

- Публичный host: `https://mcp.elgit.ru`
- Endpoint: `https://mcp.elgit.ru/mcp`
- Статус: включён

## Токен

1. elGIT → Профиль → Безопасность → API tokens  
2. Создайте токен с областью **mcp** (или **api**)  
3. Не коммитьте токен в git

## Cursor (`~/.cursor/mcp.json` или Settings → MCP)

```json
{
  "mcpServers": {
    "elgit": {
      "url": "https://mcp.elgit.ru/mcp",
      "headers": {
        "Authorization": "Bearer elgit_ВАШ_ТОКЕН"
      }
    }
  }
}
```

Лучше через переменную окружения:

```json
{
  "mcpServers": {
    "elgit": {
      "url": "https://mcp.elgit.ru/mcp",
      "headers": {
        "Authorization": "Bearer ${env:ELGIT_MCP_TOKEN}"
      }
    }
  }
}
```

## Локальный stdio (без HTTP)

На машине с доступом к серверу:

```bash
ELGIT_URL=https://elgit.ru \
ELGIT_TOKEN=elgit_… \
bun run /path/to/elGIT.server/src/mcp/stdio.ts
```

(stdio-режим сейчас обслуживает тот же протокол tools через локальный процесс — см. `src/mcp/stdio.ts`.)

## Tools

- `search` — USE FIRST for questions about the elGIT instance. Ranked search over projects/repos (name, slug, description, package.json, README index). Returns score, match, repoCount, topRepos, tips. Multi-word = OR. Commits OFF by default.
- `list_projects` — List projects (id, slug, name, description, repoCount).
- `list_repos` — List repos visible to token user. Optional projectId filter.
- `list_undocumented` — Projects/repos with empty description — fill these to improve search.
- `get_repo` — Repo metadata: description, default branch, package version.
- `list_tree` — List files/folders (ls-tree).
- `get_file` — Read text file. Secret paths (.env, keys) are blocked. Large files truncated.
- `grep` — git grep in a repository (source code). Prefer after search/get_repo. Secret paths filtered.
- `list_commits` — Recent commits on a ref (default branch).
- `diff` — Diff between two refs (base...head). Use nameOnly for file list. Truncated.
- `list_issues` — List issues in a repo (open/closed/all).
- `get_issue` — Get one issue by number (title, body, status).
- `create_issue` — Create issue (requires Admin MCP allowWrite + developer role).
- `list_mrs` — List merge requests in a repo.
- `get_mr` — Get MR by number + comments.
- `create_mr_comment` — Comment on MR (requires allowWrite + developer role).
- `list_actions` — List Action runs (pipeline status) for a repo.
- `get_action` — Get Action run details + truncated log.
- `get_rules` — Instance agent rules (Admin → MCP → Правила).

## Поиск (`search`)

- Короткие ключи: slug проекта, имя продукта, стек (`elwms`, `mcp`, `notifications`).
- Несколько слов = OR по токенам; выше score, если совпали все.
- В ответе: `score`, `match` (где нашли), `repoCount`, `topRepos`, `tips`.
- Коммиты выключены по умолчанию (`includeCommits: true` если нужны).
- Дальше: `list_repos` + `projectId` → `get_file` README.md.

## Resources

- `elgit://rules` — правила агента (настраиваются в этой вкладке)
- `elgit://docs` — эта документация

## Cursor: виды интеграций

Не выбирай один слой — используй все по назначению:

1. **MCP к инстансу** (лучше для сервера) — `search`, `get_file`, живые проекты/репо. Конфиг: `~/.cursor/mcp.json` + PAT scope `mcp`. UI: Профиль → Cursor / MCP → Подключение.
2. **Правила MCP** — короткие обязательные инструкции (`get_rules`, `initialize.instructions`, `elgit://rules`). Не раздувай: instructions обрезаются (~2k). Длинный playbook — здесь, в `elgit://docs`.
3. **`.cursor/rules/*.mdc` в репо** (лучше для конкретного репо) — секреты CI, publish mode, пути деплоя в локальном Cursor. Шаблон копируется из Профиль → Cursor.
4. **`AGENTS.md`** — универсальный вход для любых агентов (MCP + локальные rules).
5. **Skill** — опционально для повторяемых сценариев; для старта хватит MCP + rules в репо.

UI-сводка: elGIT → Профиль → **Cursor** (админ).

## Деплой Actions

Workflows лежат в `.elgit/workflows/*.yml` — формат **плоский**: `name`, `on`, `steps` (не GitHub `jobs` / `uses`).

Секреты репо (UI → Secrets):

| Секрет | Назначение |
|--------|------------|
| `SSH_HOST` | Хост |
| `SSH_USER` | SSH user (часто `root`) |
| `SSH_KEY` | PEM → в run как **`$SSH_KEY_FILE`** |
| `DEPLOY_PATH` | Каталог на сервере |
| `DEPLOY_SERVICE` | systemd unit (`server` / `bundle`) |
| `HEALTH_URL` | полный URL проверки после bundle (напр. `http://127.0.0.1:4000/health`, lowercase); иначе порт Nginx + `/health` |
| `HEALTH_PATH` | path, если нет `HEALTH_URL` (по умолчанию `/health`) |
| `HEALTH_PORT` | порт health, если нет `HEALTH_URL` (иначе порт Nginx / `4000`; не путать с `PORT` runner) |
| `NPM_TOKEN` | npm publish |

В shell: `ssh -i "$SSH_KEY_FILE" -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new …`

Перед rsync Actions проверяют ОС (`/etc/os-release`) и ставят `rsync` / `curl`, если их нет: **apt** (Debian 11+/Ubuntu), **dnf/yum** (RHEL), **apk** (Alpine). Если нет исходящего DNS до Let's Encrypt — чинят `/etc/resolv.conf` (8.8.8.8 / 1.1.1.1) и предпочитают IPv4. Compose: `docker compose` (v2) или `docker-compose` (v1 на Debian 11).

Publish modes (настройки репо) могут **перекрыть** файл `deploy.yml` / `publish.yml`:

- `front` — build + rsync `dist/`
- `server` — rsync исходников + systemd restart
- `bundle` — `bun build` (вшивает `APP_VERSION` из `package.json`) → rsync JS → db up → systemd → **HTTP health** (`HEALTH_URL` / `/health`)
- `docker` — compose по SSH на целевом хосте
- `npm` — публикация пакета

Не выдумывай пути деплоя и значения секретов; не читай `.env` / ключи через MCP.

## Настройка репозитория

1. Создать репо в проекте (owner в URL = slug проекта).
2. Задать описание / README — влияет на `search`.
3. Secrets + Publish mode или свой `.elgit/workflows/ci.yml` / `deploy.yml`.
4. При необходимости Docker / Nginx / Database панели в настройках репо.
5. Для агента в клоне: добавить `.cursor/rules/elgit-deploy.mdc` и опционально `AGENTS.md` (шаблоны в UI → Cursor).

## Безопасность

- Доступ только с валидным Bearer (PAT/JWT)
- Репозитории фильтруются по ACL пользователя токена
- Секреты и бинарники через MCP не отдаются
- Пишите только read-only tools, пока «запись» выключена в настройках