# Cleantify MCP

MCP-сервер [Cleantify](https://cleantify.ru): поиск Яндекса и чтение любой
страницы в чистый Markdown для агентов — Claude Code, Codex, Cursor, VS Code,
Gemini CLI и других клиентов [Agent Plugins](https://agent-plugins.org/).

| Инструмент | Что делает |
| --- | --- |
| `web_search` | Ищет и сразу читает найденные страницы (3 по умолчанию, до 5) |
| `web_fetch` | Читает одну страницу по URL в Markdown |
| `web_results` | Только ссылки, заголовки и сниппеты (до 10 на страницу выдачи) |
| `image_search` | Поиск картинок: URL изображения, источник, миниатюра |

Репозиторий содержит открытый MCP-слой: описания инструментов, stdio-сервер
поверх [API Cleantify](https://cleantify.ru/docs), манифесты плагинов и
skill с правилами поиска. Сам поиск и чтение выполняет сервис Cleantify.

## Ключ

Ключ создаётся в [кабинете](https://cleantify.ru/cabinet), начинается с
`ct_` и действует 90 дней. Храните его только в хранилище секретов клиента,
в переменной окружения или в файле ключа — не в файлах проекта и не в git.

Два способа подключения:

- **Хостируемый сервер** `https://cleantify.ru/mcp` (Streamable HTTP) с
  заголовком `Authorization: Bearer <ключ>`. Ничего ставить не нужно.
- **Локальный stdio-сервер** `npx -y cleantify-mcp`. Ключ — из
  `CLEANTIFY_API_KEY` или из файла `~/.config/cleantify/api-key`.

Файл ключа нужен клиентам, которые не передают серверу переменные окружения
(так устроено большинство клиентов Agent Plugins):

```sh
mkdir -p ~/.config/cleantify
printf 'Cleantify key: '; stty -echo; read -r key; stty echo; echo
( umask 077; printf '%s\n' "$key" > ~/.config/cleantify/api-key ); unset key
```

Сервер откажется читать файл, доступный другим пользователям (нужно
`chmod 600`), и символическую ссылку.

## Claude Code

Плагин спрашивает ключ при установке и хранит его в защищённом хранилище:

```sh
claude plugin marketplace add valentinavdeev/cleantify-mcp
claude plugin install cleantify@cleantify
```

Без плагина (ключ попадёт в `~/.claude.json` открытым текстом):

```sh
claude mcp add --transport http cleantify https://cleantify.ru/mcp \
  --header "Authorization: Bearer $CLEANTIFY_API_KEY"
```

## Codex

```sh
export CLEANTIFY_API_KEY=ct_...   # лучше — в профиле оболочки
codex mcp add cleantify --url https://cleantify.ru/mcp --bearer-token-env-var CLEANTIFY_API_KEY
```

Как плагин (stdio, ключ из файла ключа):

```sh
codex plugin marketplace add valentinavdeev/cleantify-mcp
codex plugin add cleantify@cleantify
```

## Gemini CLI

Расширение спросит ключ и сохранит его в системном хранилище:

```sh
gemini extensions install https://github.com/valentinavdeev/cleantify-mcp
```

## Cursor

`~/.cursor/mcp.json` (ключ — в переменной окружения `CLEANTIFY_API_KEY`):

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

## Другие клиенты

Клиенты Agent Plugins (VS Code, GitHub Copilot, Kiro, OpenHands и др.) ставят
этот репозиторий как плагин: корневые `plugin.json` и `mcp.json` запускают
`npx -y cleantify-mcp`, ключ берётся из файла ключа.

Любой другой MCP-клиент:

```json
{
  "mcpServers": {
    "cleantify": { "command": "npx", "args": ["-y", "cleantify-mcp"] }
  }
}
```

либо хостируемый `https://cleantify.ru/mcp` с заголовком
`Authorization: Bearer <ключ>`, если клиент умеет задавать заголовки.

## Переменные stdio-сервера

| Переменная | Значение |
| --- | --- |
| `CLEANTIFY_API_KEY` | Ключ `ct_…`; важнее файла ключа |
| `CLEANTIFY_API_URL` | Адрес сервиса, по умолчанию `https://cleantify.ru` |

Ответ инструмента — JSON со `status` (`succeeded`, `partial`, `failed`),
данными и расходом квоты. Коды ошибок и правила повтора — в
[skills/cleantify-search/SKILL.md](skills/cleantify-search/SKILL.md).

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

```sh
npm ci
npm run check   # типы, тесты, сборка, тесты собранного пакета
```

Что и как проверяется — [TESTING.md](TESTING.md).

Выпуск новой версии:

1. Описания инструментов в `src/tools.ts` повторяют хостируемый сервер.
   Если они изменились на сервисе — обновите `src/tools.ts` и
   `tests/fixtures/service-tools.json`.
2. Поднимите версию в `package.json`, `src/index.ts` и манифестах
   (`npm test` проверяет, что она везде одна).
3. `npm run check`, затем `npm run check:live` с тестовым ключом
   (`CLEANTIFY_KEY_FILE=…`): сравнивает `tools/list` с продом и читает одну
   страницу, без платного поиска.
4. `npm publish --access public` (нужна 2FA), тег `vX.Y.Z`, push.

## English

Cleantify MCP gives agents Yandex web search and clean Markdown page reading.
Get a key (`ct_…`, valid 90 days) at https://cleantify.ru/cabinet, then either
connect to the hosted server `https://cleantify.ru/mcp` with
`Authorization: Bearer <key>`, or run `npx -y cleantify-mcp` with the key in
`CLEANTIFY_API_KEY` or in `~/.config/cleantify/api-key` (mode 600).
Claude Code: `claude plugin marketplace add valentinavdeev/cleantify-mcp` and
`claude plugin install cleantify@cleantify`. The repository is an
[Agent Plugins](https://agent-plugins.org/) package for other clients.

## Лицензия

MIT — [LICENSE](LICENSE).