# mcp-confluence

MCP-сервер для **Confluence Server / Data Center (Self-Hosted)** с авторизацией по Personal Access Token. Даёт LLM-агенту доступ к поиску, чтению, созданию/редактированию страниц, комментариям, меткам и вложениям.

> Работает с Confluence Server/DC REST API (`/rest/api`). Для Confluence Cloud API отличается — этот сервер ориентирован именно на self-hosted.

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

| Инструмент | Назначение |
| --- | --- |
| `confluence_search` | Поиск по CQL |
| `confluence_get_page` | Страница по ID (тело в storage-формате, версия, метки) |
| `confluence_get_page_by_title` | Страница по пространству + заголовку |
| `confluence_list_spaces` | Список пространств |
| `confluence_get_child_pages` | Дочерние страницы |
| `confluence_create_page` | Создать страницу |
| `confluence_update_page` | Обновить (версия инкрементируется автоматически) |
| `confluence_delete_page` | Удалить страницу |
| `confluence_add_comment` | Добавить комментарий |
| `confluence_get_labels` / `confluence_add_labels` / `confluence_remove_label` | Метки |
| `confluence_list_attachments` | Список вложений |
| `confluence_upload_attachment` | Загрузить файл как вложение |
| `confluence_download_attachment` | Скачать вложение на диск |

## Установка

```bash
npm install
npm run build
```

## Настройка

### Вариант A — веб-панель (проще)

```bash
npm run config
```

Откройте <http://127.0.0.1:4321>. Форма позволяет:

- заполнить все поля (Base URL, PAT либо логин/пароль, TLS);
- **проверить подключение** одной кнопкой (запрос к вашему Confluence);
- сохранить `.env` в корень проекта;
- скопировать готовый JSON-конфиг для Claude.

Панель слушает только `127.0.0.1` и наружу не доступна.

### Вариант B — вручную

Скопируйте `.env.example` в `.env` и заполните, либо задайте переменные окружения:

| Переменная | Обязательна | Описание |
| --- | --- | --- |
| `CONFLUENCE_BASE_URL` | да | URL инстанса, например `https://confluence.company.local` |
| `CONFLUENCE_PAT` | да* | Personal Access Token (рекомендуемый способ) |
| `CONFLUENCE_USERNAME` + `CONFLUENCE_PASSWORD` | да* | Basic Auth (fallback, если PAT не задан) |
| `CONFLUENCE_TLS_REJECT_UNAUTHORIZED` | нет | `false` — не проверять TLS (для self-signed) |

\* Нужен либо `CONFLUENCE_PAT`, либо пара логин/пароль.

**Как получить PAT:** в Confluence → аватар → *Settings* → *Personal Access Tokens* → *Create token*.

## Подключение к Claude Code / Claude Desktop

Добавьте в конфиг MCP-клиента:

```json
{
  "mcpServers": {
    "confluence": {
      "command": "node",
      "args": ["G:/Portfolio/mcp-confluence/dist/index.js"],
      "env": {
        "CONFLUENCE_BASE_URL": "https://confluence.company.local",
        "CONFLUENCE_PAT": "your-personal-access-token"
      }
    }
  }
}
```

Для Claude Code также можно быстрее:

```bash
claude mcp add confluence -- node G:/Portfolio/mcp-confluence/dist/index.js
```

(предварительно задав переменные окружения или прописав их через `-e KEY=value`).

## Docker

Образ собирается multi-stage (сборка TypeScript → лёгкий `node:22-alpine` рантайм, ~260 МБ, запуск от непривилегированного пользователя `node`).

```bash
docker build -t mcp-confluence:latest .
```

**MCP-сервер (stdio)** — MCP-клиент запускает контейнер сам. Пример для Claude Code:

```bash
claude mcp add confluence -- \
  docker run --rm -i \
    -e CONFLUENCE_BASE_URL=https://confluence.company.local \
    -e CONFLUENCE_PAT=your-token \
    mcp-confluence:latest
```

Ключевой флаг — `-i` (interactive): протокол MCP идёт через stdin/stdout.

**Веб-панель настройки** — нужен проброс порта и `CONFIG_UI_HOST=0.0.0.0`:

```bash
docker run --rm -p 4321:4321 -e CONFIG_UI_HOST=0.0.0.0 \
  -v "$(pwd)/.env:/app/.env" \
  mcp-confluence:latest dist/web.js
```

Или через compose:

```bash
docker compose up   # поднимет панель на http://localhost:4321
```

> `.env` внутри контейнера эфемерен — смонтируйте его томом (как выше), чтобы сохранённые настройки не пропали.

## О формате тела страниц

Confluence хранит контент в **storage-формате** (XHTML с макросами). Примеры:

```html
<p>Обычный абзац</p>
<h2>Заголовок</h2>
<ac:structured-macro ac:name="info">
  <ac:rich-text-body><p>Инфо-блок</p></ac:rich-text-body>
</ac:structured-macro>
```

При создании/обновлении страниц передавайте тело именно в этом формате.

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

```bash
npm run dev   # tsc в watch-режиме
```

## Лицензия

MIT