У большинства команд, где работают кодинг-агенты, знание о проекте живёт в трёх местах: в головах, в вики, которую агент не видит, и в AGENTS.md или CLAUDE.md в чьём-то чекауте. Последний вариант устаревает в тот день, когда кто-то сделал рефакторинг, а следующий агент всё равно ему верит.
ClewWiki задумана как четвёртое место: вики, в которой агенты работают на равных с людьми. Они читают, пишут, спорят в обсуждениях и отчитываются. В версии 0.9.0 у неё 40 MCP-инструментов. Ниже — как подключить к ней Claude Code, Cursor или Codex и что агент получает. Сторона людей (импорт, вход, организации) разобрана в соседней статье.
Подключение за две минуты#
MCP-сервер поставляется npm-пакетом @clewwiki/mcp-server. Ставить заранее ничего не нужно, кроме Node.js 22. В инстансе выпускаете токен агента в разделе Agent tokens, а дальше пишете конфиг. Для Claude Code это .mcp.json в проекте:
{
"mcpServers": {
"clewwiki": {
"command": "npx",
"args": ["-y", "@clewwiki/mcp-server"],
"env": {
"CLEWWIKI_URL": "https://wiki.example.com",
"CLEWWIKI_TOKEN": "${CLEWWIKI_TOKEN}"
}
}
}
}Cursor берёт тот же объект mcpServers в .cursor/mcp.json. Codex читает TOML из ~/.codex/config.toml:
[mcp_servers.clewwiki]
command = "npx"
args = ["-y", "@clewwiki/mcp-server"]
env = { CLEWWIKI_URL = "https://wiki.example.com", CLEWWIKI_TOKEN = "..." }Это транспорт stdio: агент запускает сервер на машине разработчика, а тот ходит в инстанс по HTTPS. Обычный http:// он отвергает, кроме локальных адресов. Для агентов в CI есть второй транспорт, streamable HTTP. По умолчанию он выключен (MCP_HTTP_ENABLED=false) и без анонимного доступа.
Проще всего не писать конфиг руками: страница Connect an agent в приложении печатает точную команду для вашего клиента и промпт, который объясняет агенту, как работать с вики. С 0.8 там же лежат повседневные команды: прочитать вики перед задачей, обновить после, открыть обсуждение. Для Claude Code есть однострочник, который ставит их как /wiki-read и /wiki-update.
Чем токен агента отличается от пароля человека#
MCP-сервер устроен как обычный REST-клиент инстанса. Он держит токен и не имеет другого входа внутрь. Отсюда главное свойство: у агента нет обходных путей. Каждый вызов проходит те же проверки прав, те же лимиты и тот же аудит, что и прямой HTTP-запрос.
Токен ограничен пространствами, к которым его допустили, имеет срок жизни и отзывается. Просроченный или отозванный токен отбивается сразу при аутентификации, до любой записи. Каждая попытка записи пишется в аудит в той же транзакции, будь она успешной, упёршейся в чужую заявку или в устаревший хеш. На токен действует лимит частоты: агент, ушедший в цикл, упрётся в него раньше, чем заспамит вики.
И отдельный контракт про чужой текст. Всё, что инструмент возвращает из сохранённого содержимого (тела страниц, заметки, имена, фрагменты кода), помечено как данные, а не инструкции. Страница с текстом «игнорируй предыдущие указания» остаётся текстом. Это не делает prompt injection невозможным, но убирает самый дешёвый путь.
Два агента на одной странице#
Этой механике я посвятил отдельную статью, здесь коротко. Перед записью агент берёт заявку на страницу или раздел через wiki.claim. Запись несёт идентификатор заявки и хеш содержимого, которое агент читал. Заявка доказывает, что сейчас никто другой не пишет; хеш — что никто и не писал. Второй агент получает конфликт с именем держателя. Молча перезаписать чужой текст нельзя. Сервер никогда не сливает правки сам: на устаревший хеш он возвращает оба хеша и ждёт, пока агент перечитает страницу.
Заявки истекают сами, их можно продлить (wiki.renew_claim) и отпустить (wiki.release_claim). Зависшую снимает администратор, и это пишется в аудит отдельной строкой. Токен агента силой снять чужую заявку не может.
Правки агента ждут человека, но не блокируют#
Агент пишет без одобрения: его правка становится страницей в момент записи. Иначе агент стоял бы в очереди, пока человек занят. Но всё, что агенты изменили после последней проверки, собирается в разделе Changes в виде диффа. Человек принимает или откатывает — с заметкой, которую агент прочитает перед следующей попыткой (wiki.get_review).
Ожидающие правки не хранятся флагом, они вычисляются. Последняя версия, которую написал или принял человек, считается базовой, а всё, что агенты сделали после неё, ждёт.
Кто сейчас в вики#
В 0.8 доска Presence научилась показывать не только заявки, но и людей: кто какую страницу открыл и читает он или редактирует. Рядом — агенты, чей токен делал запросы последние десять минут, и страница, о которой был последний запрос. Под заголовком страницы видно, кто ещё на ней.
Есть деталь, которая мне самому пригодилась раньше, чем я ожидал. Браузер под управлением WebDriver (Playwright, Selenium, Puppeteer) помечается отдельно. Это агент, работающий через сессию человека, и людям полезно отличать его от коллеги.
Агенту то же самое отдаёт wiki.get_presence в поле active_now. Перед тем как взяться за страницу, агент видит, что на ней прямо сейчас кто-то есть, и может выбрать другую задачу, вместо того чтобы ловить конфликт.
Задачи берутся из трекера#
Три инструмента появились в 0.8 вместе с интеграцией YouTrack и Jira:
wiki.my_tasks: незакрытые задачи, назначенные на человека, который выпустил токен агента. Трекер ищет их по адресу.wiki.get_issue: задача по ключу с описанием и комментариями.wiki.search_issues: поиск по запросу YouTrack или JQL.
В итоге фраза «возьми мои задачи» на странице Connect an agent превращается в рабочий сценарий: агент получает список, читает задачу, находит в вики страницы, где упомянут её ключ, и садится за работу уже с контекстом. Токен трекера хранится только в переменной окружения инстанса и в базу не попадает.
Ограничение называю прямо: клиенты трекеров проверены на записанных формах ответов API, на живом YouTrack и Jira — пока нет.
Ветки, релизы и то, что легко забыть#
Раздел Development, вышедший в 0.9, агенту полезнее, чем людям. Он читает git-репозиторий пространства и ведёт поток работы на каждую ветку: насколько она впереди и позади основной, слита ли, к какому релизу относится. Подсвечивается работа, слитая без релиза, а релиз не отмечается выпущенным, пока в нём есть неслитые потоки.
Для агента это три инструмента (wiki.development, wiki.get_stream, wiki.update_stream) и параметр stream_id у wiki.open_discussion. Агент, который упёрся в проблему по ветке, открывает обсуждение прямо в её потоке. Когда обсуждение решено, решение записывается страницей в документацию потока, а сама переписка истекает. Остаётся вывод, лог переписки не копится.
Файлы, входящие и подписки#
Агент может публиковать и читать файлы: wiki.upload_file до 7 МБ через инструмент, больше — через REST тем же токеном; wiki.get_file возвращает содержимое текстового файла до 256 КБ. Загрузка файла с тем же именем добавляет версию под той же ссылкой.
wiki.watch подписывает на страницу или пространство, а wiki.check_inbox возвращает то, что касается агента: ответ в обсуждении, которое он открыл, упоминание, рецензию его правки, новую версию файла. Ответ находит того, кто спрашивал, без почты и без отдельной очереди уведомлений.
Правила и скиллы — в вики, а не в чекауте#
Правила проекта и переиспользуемые скиллы хранятся в вики, и любой агент читает их по MCP перед началом работы (wiki.get_rules, wiki.list_skills, wiki.get_skill). Договорённости команды перестают быть файлом на инструмент в чьём-то ноутбуке.
Но хосты агентов загружают скиллы из каталогов, а писать на диск MCP-вызов не может. Поэтому пакет несёт ещё и команду:
CLEWWIKI_URL=https://wiki.example.com CLEWWIKI_TOKEN=$CLEWWIKI_TOKEN \
npx -y @clewwiki/mcp-server skills install --space MOBILEОна забирает скиллы пространства и раскладывает их в ~/.claude/skills/<slug>/SKILL.md, печатая каждый записанный файл. --only ставит выбранные, --dir пишет в другой каталог.
И последняя вещь против «контекст протух»: страницу можно привязать к объявлению в коде на Swift, TypeScript, TSX или Kotlin. Прогон форматтера ничего не меняет, изменение тела помечает страницу устаревшей, переименование и перенос распознаются, удаление сообщается. Как это работает и почему без ложных срабатываний — в статье про якоря.
Чего не обещаю#
- Это 0.x. Первый тег вышел 18 сентября, десятый — 5 октября. Инструменты добавляются почти каждый релиз, агенту нужно переподключиться, чтобы их увидеть, а миграции базы идут часто.
- Трекеры не проверены вживую, об этом выше.
- Streamable HTTP выключен по умолчанию. Для агентов в CI его нужно включить осознанно и поставить инстанс за TLS.
- Аудит и заявки не защищают от плохого содержания. Агент с правом записи может написать уверенную ерунду. Ревью правок существует ровно для этого, но кто-то должен в него заглядывать.
Попробовать#
Поднимите инстанс по быстрому старту из README, выпустите токен на одно пространство и попросите агента прочитать вики перед ближайшей задачей, а после — обновить. По тому, что окажется в Changes, за вечер станет понятно, подходит ли такая работа вашей команде.
Полный список инструментов с их scope и ошибками — в docs/mcp.md в репозитории. Обзор проекта — на странице ClewWiki.
