# gitea-mcp

MCP-сервер (stdio) для [Gitea](https://about.gitea.com): подключается к репозиториям, смотрит и перезапускает пайплайны Gitea Actions, разбирает причины падений, проверяет сборку образов в Gitea Packages и заводит issue для разбора.

Работает с любым MCP-клиентом (Claude Code, Claude Desktop, Cursor и др.). Без внешних зависимостей, кроме MCP SDK и zod.

## Возможности

| Область | Tools |
|---|---|
| Репозитории | `gitea_list_repos`, `gitea_get_repo`, `gitea_get_file` |
| Просмотр пайплайнов | `gitea_list_runs`, `gitea_get_run`, `gitea_list_jobs`, `gitea_get_job_logs` (tail / grep) |
| Диагностика | `gitea_diagnose_run` — упавшие jobs и шаги, блоки ошибок из логов, вероятные причины и способы починки |
| Управление | `gitea_rerun_run`, `gitea_rerun_job`, `gitea_rerun_failed_jobs`, `gitea_cancel_run`, `gitea_dispatch_workflow` |
| Образы и пакеты | `gitea_list_packages`, `gitea_check_image` — есть ли тег, когда собран, digest, свежесть относительно `built_after` |
| Issues | `gitea_list_issues`, `gitea_get_issue`, `gitea_create_issue`, `gitea_comment_issue`, `gitea_create_issue_from_run` |

`gitea_create_issue_from_run` собирает диагностику упавшего run в issue и не создаёт дубликат, если открытый issue по этому run уже есть.

## Требования

- Node.js ≥ 20
- Gitea ≥ 1.24 (REST API для Actions: runs, jobs, logs, rerun)
- Токен доступа (Settings → Applications) со scope: repository (read/write), issue (read/write), package (read)

## Установка

```bash
git clone <url этого репозитория> gitea-mcp
cd gitea-mcp
npm install
npm run build
```

## Настройка

| Переменная | Описание |
|---|---|
| `GITEA_URL` | Адрес инстанса, например `https://gitea.example.com` |
| `GITEA_TOKEN` | Токен доступа |
| `GITEA_READONLY` | `true` — отключить все изменяющие операции (rerun, cancel, dispatch, создание issue и комментариев) |
| `GITEA_TIMEOUT_MS` | Таймаут запроса, по умолчанию `30000` |

### Claude Code

```bash
claude mcp add gitea -s user \
  -e GITEA_URL=https://gitea.example.com \
  -e GITEA_TOKEN=<токен> \
  -- node /абсолютный/путь/к/gitea-mcp/dist/index.js
```

### Другие клиенты (JSON-конфиг)

```json
{
  "mcpServers": {
    "gitea": {
      "command": "node",
      "args": ["/абсолютный/путь/к/gitea-mcp/dist/index.js"],
      "env": {
        "GITEA_URL": "https://gitea.example.com",
        "GITEA_TOKEN": "<токен>"
      }
    }
  }
}
```

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

- Токен берётся только из переменной окружения и никуда не логируется.
- Для работы «только на просмотр» используйте `GITEA_READONLY=true` и токен без write-прав.
- Логи перед выдачей модели и записью в issue проходят маскировку типовых секретов (пароли, токены, Bearer, приватные ключи, пароли в URL). Маскировка работает по шаблонам и может пропустить нестандартный секрет — просматривайте issue перед публикацией в открытых репозиториях.
- Причины падений в `gitea_diagnose_run` — эвристика по тексту лога, а не точный диагноз; рядом всегда приводятся сами блоки ошибок для проверки.

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

```bash
npm run dev     # tsc --watch
npm run build
```

Структура: `src/client.ts` — HTTP-клиент Gitea, `src/diagnose.ts` — анализ и маскировка логов, `src/runs.ts` — общая логика run/job, `src/tools.ts`, `src/packages.ts`, `src/issues.ts` — регистрация tools.

## Лицензия

MIT