# gramax-docportal-mcp

MCP-сервер для доступа к порталу документации [Gramax](https://gram.ax). Позволяет искать статьи, получать контент и навигацию через Claude и другие LLM.

## Инструменты

| Инструмент | Описание |
|-----------|----------|
| `gramax_list_catalogs` | Список всех каталогов документации |
| `gramax_get_navigation` | Дерево навигации каталога |
| `gramax_search` | Поиск по статьям (фильтры по свойствам, языку, семантический поиск) |
| `gramax_get_article` | Содержимое статьи в Markdown |

## Установка

```bash
uv tool install gramax-docportal-mcp
```

## Настройка

Добавьте в `.mcp.json`:

```json
{
  "mcpServers": {
    "gramax": {
      "command": "uvx",
      "args": ["gramax-docportal-mcp"],
      "env": {
        "GRAMAX_BASE_URL": "https://your-portal.example.com",
        "GRAMAX_API_TOKEN": "ваш-api-токен"
      }
    }
  }
}
```

### Публичные порталы (без токена)

Если портал публичный (не требует авторизации), `GRAMAX_API_TOKEN` можно не задавать — сервер работает в анонимном режиме:

```json
{
  "mcpServers": {
    "gramax": {
      "command": "uvx",
      "args": ["gramax-docportal-mcp"],
      "env": {
        "GRAMAX_BASE_URL": "https://your-portal.example.com"
      }
    }
  }
}
```

### Получение токена

Если портал защищён, откройте в браузере (будучи залогиненным на портале):

```
https://your-portal.example.com/api/user/token
```

Токен действует 30 дней. Для кастомного срока:

```
https://your-portal.example.com/api/user/token?expiresAt=2026-12-31
```

Без токена или с истёкшим токеном сервер получит 401 при первом запросе и вернёт русскоязычное сообщение об ошибке.

## Переменные окружения

| Переменная | Описание | Обязательно |
|-----------|----------|:-----------:|
| `GRAMAX_BASE_URL` | URL портала документации | Да |
| `GRAMAX_API_TOKEN` | API-токен (Bearer); не нужен для публичных порталов | Нет |
| `GRAMAX_AI_TIMEOUT` | Таймаут AI-поиска в секундах (по умолчанию 120) | Нет |
| `GRAMAX_AI_ARTICLES_LANGUAGE` | Язык статей в индексе для AI-поиска. Значения по умолчанию нет — см. предупреждение ниже | Нет |
| `GRAMAX_AI_RESPONSE_LANGUAGE` | Язык генерируемого ответа AI-поиска (по умолчанию `ru`) | Нет |

> **Не задавайте `GRAMAX_AI_ARTICLES_LANGUAGE` без нужды.** На некоторых порталах
> любое непустое значение этого параметра обнуляет выдачу: AI-поиск отвечает «не нашёл
> информации в предоставленной базе знаний» и не отдаёт ни одного источника, а
> полнотекстовый поиск возвращает ноль результатов вместо десятков. Поэтому с версии
> 0.3.3 значения по умолчанию у переменной нет и параметр не уходит на портал, пока его
> не задали явно. Задавайте его, только если ваш портал действительно требует фильтра по
> языку статей, и проверьте выдачу до и после. `GRAMAX_AI_RESPONSE_LANGUAGE` безвреден.

## Расширенный поиск

`gramax_search` поддерживает дополнительные параметры для точной фильтрации:

| Параметр | Описание |
|----------|----------|
| `catalog_name` | Ограничить поиск одним каталогом |
| `search_type` | `"vector"` — семантический поиск (по умолчанию — полнотекстовый) |
| `language` | Язык статей: `"ru"`, `"en"`, `"de"`, `"zh"` и др. Уходит как `articlesLanguage` — на некоторых порталах обнуляет выдачу, по умолчанию не задавать |
| `resource_filter` | `"without"` — только статьи, `"only"` — только файлы |
| `property_filter` | Фильтр по свойствам статей (Продукт, Сегмент, Отрасль и др.) |

### Примеры property_filter

```json
{"op": "eq", "key": "Продукт", "value": "NSD"}

{"op": "contains", "key": "Сегмент", "list": ["Enterprise", "SMB"]}

{"op": "and", "filters": [
  {"op": "eq", "key": "Тип контента", "value": "Кейс"},
  {"op": "eq", "key": "Отрасль", "value": "Логистика"}
]}
```

В результатах поиска отображаются метаданные статей (🏷️) и рекомендованные результаты (⭐).

## Лицензия

MIT