ccc-mcp — Command Claude Code

Локальный MCP-сервер, через который внешний агент Claude ставит задачи вашей установке Claude Code и получает структурированный отчёт — без копирования текста между окнами.

Сервер универсальный: «текст задачи → Claude Code → структурированный отчёт». Никакой логики Архитектора/Вайбкодера и разбора паспорта проекта в нём нет.

⚠️ Прежде чем подключать

Это не песочница. Мост запускает на вашей машине настоящий claude, который правит файлы, исполняет команды и коммитит — от вашего имени и с вашими правами.

• Пооперационные разрешения по умолчанию выключены (hooksEnabled: false): внутри уже одобренного плана мост не перехватывает Bash дочернего процесса.

• write_project_file и run_git меняют состояние вне цикла план→одобрение — это осознанное решение, разобранное в docs/security.md.

• Единственная жёсткая граница — allowedRoots. Не указывайте там домашний каталог целиком: перечисляйте конкретные проекты.

Модель угроз и куда сообщать об уязвимости — SECURITY.md.

Related MCP server: worker-mcp

Что это даёт

Правка кода идёт через обязательный цикл «план → одобрение → выполнение»: дочерний Claude Code сначала показывает, что собирается сделать, и только явно одобренный план разрешено выполнять. Всё, что интеллекта не требует — прочитать файл, положить его обратно, посмотреть git status, закоммитить, — доступно напрямую, без запуска дочерней модели.

• Человеку — пошаговая установка, подключение и разбор проблем: SETUP.md.

• Вызывающему ИИ-агенту — императивный протокол одним файлом: AGENT-PROTOCOL.md.

• Подробности по темам — в docs/, карта ниже в разделе «Документация».

Инструменты

Границы, поведение и обоснования файловых и git-инструментов — docs/tools.md.

Протокол в двух словах

plan_task  →  показать план человеку  →  approve_plan  →  execute_task
 planned                                    approved      executing → executed

• execute_task без одобренного session_id невозможен. Запустить задачу «с нуля», минуя план, нельзя — в этом и смысл моста.

• Повторный plan_task сбрасывает одобрение и меняет plan_digest: одобрить один план и подменить его другим не получится.

• has_open_questions: true блокирует одобрение. Модели не хватило данных — она обязана выписать вопросы, а не угадать; задайте их пользователю и перепланируйте.

• Сбой одобрение не сжигает. После таймаута, отмены или ошибки API сессия остаётся approved, попытку можно повторить.

Таблица состояний, поля ответа и обоснования — docs/protocol.md.

Быстрый старт

Требуется Node.js ≥ 20 и установленный Claude Code (проверено на 2.1.177, 2.1.268 и 2.1.274). CLI должен уметь --output-format stream-json — на нём держится наблюдаемость идущей задачи; если версия его не поддерживает, обход — streamEvents: false в конфиге.

1. Авторизация. Сервер не работает с вашими учётными данными: дочерний claude аутентифицируется сам.

claude auth login

Проверить — должно прийти "is_error":false:

claude -p "hi" --output-format json

2. Сборка.

npm install
npm run build

3. Конфиг. Без белого списка каталогов сервер не стартует.

cp ccc-mcp.config.example.json ccc-mcp.config.json

Впишите в allowedRoots свои каталоги.

4. Подключение.

claude mcp add --scope user ccc-mcp -e CCC_MCP_CONFIG=D:/Projects/ccc-mcp/ccc-mcp.config.json -- node D:/Projects/ccc-mcp/dist/index.js

Имя сервера должно идти до -e — флаг вариадический и иначе заберёт имя себе. Проверить: claude mcp list.

Claude Desktop, Windows, macOS и разбор проблем подключения — в SETUP.md.

Пример: полный цикл

Шаг 1 — план.

{ "name": "plan_task",
  "arguments": { "task_text": "Добавь валидацию email в форму регистрации и покрой её тестами.",
                 "project_dir": "D:\\Projects\\my-project" } }

Ответ (сокращённо):

{ "status": "done", "ok": true,
  "session_id": "b1e41519-93c1-4dc3-8eb2-0669513addf9",
  "session_state": "planned", "plan_digest": "a3f19c4b7e02",
  "result_text": "План: 1) добавить схему валидации…",
  "next_step": "План готов, но не одобрен — выполнение пока запрещено…" }

Шаг 2 — показать план человеку и одобрить. Оба значения берутся из ответа plan_task без изменений.

{ "name": "approve_plan",
  "arguments": { "session_id": "b1e41519-93c1-4dc3-8eb2-0669513addf9",
                 "plan_digest": "a3f19c4b7e02" } }

Приходит session_state: "approved".

Шаг 3 — выполнение. Claude Code продолжит с уже собранным контекстом и вернёт тот же session_id.

{ "name": "execute_task",
  "arguments": { "task_text": "Выполни план.",
                 "project_dir": "D:\\Projects\\my-project",
                 "session_id": "b1e41519-93c1-4dc3-8eb2-0669513addf9",
                 "permission_mode": "acceptEdits", "model": "opus" } }

project_dir должен совпадать с тем, для которого строился план: одобрение действует только для своего проекта.

permission_mode — acceptEdits (по умолчанию, принимать правки файлов) либо bypassPermissions (не спрашивать вообще, включая запуск команд).

model — необязательный, доступен в обоих вызовах: алиас (opus, sonnet, haiku) или полное имя (claude-opus-5). Если не передать, берётся model из конфига, а если и там пусто — модель выбирает сам CLI. Алиас haiku мост передаёт полным именем claude-haiku-4-5: с алиасом Claude Code в режиме плана намеренно планирует на Sonnet.

Если пропустить шаг 2, вызов будет отклонён с текстом «план сессии b1e41519… получен, но не одобрен» и подсказкой, что вызвать дальше.

Долгие задачи и наблюдаемость

MCP-клиенты обычно обрывают вызов инструмента примерно через минуту, а задача может идти полчаса. Поэтому plan_task и execute_task ждут результат не дольше wait_seconds (по умолчанию 20 с). Успели — отдают полный отчёт сразу; не успели — возвращают status: "running" и process_id:

{ "name": "get_task_status", "arguments": { "process_id": "6f0c…", "wait_seconds": 30 } }

wait_seconds при опросе означает «подожди до N секунд, если задача ещё идёт». wait_seconds: 0 в execute_task — сразу уйти в фон, не дожидаясь ничего. Стоимость известна только по завершении: пока задача идёт, total_cost_usd равен null.

Идущая задача не чёрный ящик. В каждом ответе есть объект progress: что вызывалось (tools_used, last_tool_call), последнее видимое сообщение модели, idle_seconds и лента recent_events, — а next_step называет словами то, что происходит прямо сейчас (ждёт разрешения, зависла, выполняет долгий инструмент, ходит по кругу). Поле wait_ended_reason говорит, почему вернулось ожидание: задача закончилась, вышло время или появился запрос на разрешение.

Поля ответа и таблица progress целиком — docs/protocol.md; устройство потока событий и пороги диагностики — docs/internals.md.

Настройка

Сервер ищет конфиг в таком порядке:

1. путь из переменной CCC_MCP_CONFIG;

2. ccc-mcp.config.json рядом с пакетом;

3. ccc-mcp.config.json в текущем каталоге.

Если конфига нет и не задан CCC_ALLOWED_ROOTS — сервер не стартует: без белого списка работать небезопасно. В конфиге разрешены комментарии // и /* … */.

Белый список каталогов. project_dir из вызова проходит realpath (снимаются симлинки и junction'ы, нормализуется регистр) и только потом сверяется с allowedRoots. Отклоняются относительные пути, обход через .., несуществующие каталоги и каталоги-соседи вроде D:\Projects-other.

Наблюдаемостью управляют три ключа: streamEvents (килсвитч разбора потока, по умолчанию true), logProgress и logProgressIntervalMs (сводка живого состояния в лог, по умолчанию выключена).

Переменные окружения перекрывают файл: CCC_ALLOWED_ROOTS (несколько путей через ;), CCC_CLAUDE_BIN, CCC_GIT_BIN, CCC_MODEL, CCC_TIMEOUT_MS, CCC_LOG_FILE, CCC_HOOKS_ENABLED (1/0), CCC_STREAM_EVENTS (1/0), CCC_AUTO_APPROVE_COMMANDS (несколько команд через ;).

Все ключи с умолчаниями и пояснениями — в ccc-mcp.config.example.json и в разделе «Что стоит настроить» SETUP.md.

Безопасность — коротко

• Правка файлов силами Claude Code — только по одобренному плану, привязанному к plan_digest и каталогу.

• write_project_file и run_git — сознательные исключения: тот же результат достижим через обычный цикл, поэтому запрет дал бы не защиту, а неудобство. Каждая операция в логе.

• Ключ родителя не передаётся: все ANTHROPIC_* и CLAUDE_* вычищаются из окружения дочернего процесса.

• Мост не запускается внутри своего же дочернего claude: окружение помечается CCC_MCP_NESTED=1, и вложенный сервер завершается на старте.

• Без shell. spawn с shell: false, текст задачи и аргументы git — отдельными элементами argv, сообщение коммита — через stdin.

• Белый список каталогов проверяется до запуска процесса.

• Таймаут (timeoutMs, 90 минут) снимает зависший процесс вместе с потомками, maxConcurrent не даёт расплодить процессы.

Разбор каждого пункта — docs/security.md.

Документация

Проверка

npm run build
npm run smoke -- --no-live  # только проверки без вызовов Claude Code
npm run smoke               # полный прогон, тратит токены

Скрипт поднимает сервер как настоящий MCP-клиент и проходит весь протокол вместе с отказами, мост разрешений, файловые инструменты, листинг и run_git на реальном временном репозитории. Что именно покрывает каждый блок — docs/internals.md.

Автор

Basil@155 — me@basil155.ru, www.basil155.ru

Код написан в паре с Claude Code (Claude Opus 5).

Лицензия

MIT — см. LICENSE.