DevTwin MCP

Дайте ИИ-агентам для написания кода живое, структурированное понимание вашего локального окружения разработки.

DevTwin — это сервер Model Context Protocol (MCP), который отвечает на один центральный вопрос для ИИ-агента, пишущего код: почему окружение этого разработчика отличается, сломано или нездорово?

Он определяет технологию проекта, проверяет установленные версии рантайма на соответствие тому, что проект реально требует, инспектирует состояние зависимостей и lockfile-файлов, находит требуемые локальные сервисы (Postgres, Redis, ...) и проверяет, запущены ли они, проверяет порты и состояние Git, и превращает всё это в структурированную, основанную на фактах диагностику — без отправки вашего окружения в облачный бэкенд и без раскрытия секретных значений модели.

Содержание

• Зачем существует DevTwin

• FAQ: у Claude CLI уже есть shell, так зачем вообще MCP?

• Преимущества

• Стоимость в токенах

• Честные компромиссы

• С DevTwin и без DevTwin: разобранный пример

• Примеры вопросов, которые это открывает

• Примеры по языкам

• Архитектура

• Поддерживаемые экосистемы

• Установка

• Настройка MCP-клиента

• Использование на другом проекте

• Справочник инструментов

• Модель безопасности

• Модель конфиденциальности

• Локальная архитектура

• Разработка

• Вклад в проект

• Дорожная карта

• Лицензия

Зачем существует DevTwin

• ИИ-агенты, пишущие код, хорошо читают код, но слепы к окружению, в котором этот код реально работает.

• «Почему npm test падает на моей машине?» обычно не имеет отношения к коду — это несовпадение версии Node, не запущенный сервис или зависимости, которые никогда не были установлены.

• DevTwin даёт агенту тот же сигнал, который старший инженер собрал бы вручную — node --version, git status, lsof -i :5432, docker ps — в виде структурированных вызовов инструментов, а не догадок.

FAQ: у Claude CLI уже есть shell, так что зачем вообще MCP?

Обычно это первый вопрос, который задаёт разработчик, и он справедлив. В клиенте вроде Claude Code, где уже есть инструмент Bash, можно просто попросить его выполнить node --version, docker ps, lsof -i :5432 и т.д. напрямую — никакой MCP-сервер не нужен. Пробел, который закрывает DevTwin, — не «можно ли это вообще сделать» — а вот что:

Честный ответ конкретно для Claude CLI: поскольку там уже есть Bash, выигрыш DevTwin здесь меньше, чем «возможность, которой у вас не было» — это гарантии безопасности и стабильный структурированный вывод, а не принципиально новый доступ. Именно поэтому он и не бесплатен — см. Стоимость в токенах за то, что подключение реально стоит, и когда оно оправдано.

Ещё несколько вопросов, которые стоит задать перед внедрением:

«Разве это не просто скрипт doctor (make doctor, bin/setup) с лишними шагами?» Концептуально да — во многих зрелых репозиториях уже есть такой самописный скрипт. Отличие DevTwin в том, что в большинстве репозиториев его нет, написать хороший скрипт для каждой экосистемы — это реальная работа, его вывод — это структурированный JSON, с которым агент может рассуждать, а не простой текст для чтения человеком, и одни и те же 10 инструментов работают одинаково в любом репозитории, вместо самодельного скрипта на каждый проект со своими соглашениями и слепыми зонами.

«Это работает только с Claude / Claude Code?» Нет. DevTwin говорит на стандартном протоколе Model Context Protocol — любой MCP-совместимый клиент (Claude Desktop, Cursor, Windsurf и т.д.) может подключиться к нему так же. Ничего в нём не специфично для Claude.

«Безопасно ли на него полагаться — активно ли он поддерживается?» Это статус Alpha и молодой проект — прочитайте код (он короткий), прежде чем доверять ему рабочий процесс, от которого вы зависите, как и любой новой зависимости в инструментах разработки.

«Может ли он предложить что-то неправильное или автоматически выполнить плохую рекомендацию?» Ни один инструмент здесь не выполняет строку recommendations — это просто текст для агента (или вас), чтобы прочитать и решить. dev_check — единственный инструмент, который что-то выполняет, и только те команды, которые он сам распознал из файлов проекта, проверенные по фиксированному списку разрешённых, с shell=False и таймаутом — см. Модель безопасности.

«Отправляет ли он данные домой или телеметрию куда-либо?» Нет. Ноль собственных сетевых вызовов — см. Локальная архитектура.

«Я не хочу, чтобы MCP-сервер выполнял любые команды на моей машине.» 9 из 10 инструментов — чисто read-only (чтение файлов, проверки версий). Только dev_check что-то выполняет, и только те команды, которые DevTwin сам распознал из файлов проекта, проверенные по списку разрешённых, с shell=False и таймаутом — см. Модель безопасности за точное описание того, что это разрешает, а что нет.

Преимущества

• Меньше неверных диагнозов. Без DevTwin агент, отлаживающий сбой, может только читать код и догадываться — он часто предложит исправление кода для того, что на самом деле является несовпадением версии Node или остановленной базой данных. DevTwin даёт ему факты вместо догадок.

• Один вызов вместо многих. Один вызов dev_health объединяет ~10 базовых проверок (версии рантайма, состояние зависимостей, сервисы, порты, Git) в один структурированный результат с оценкой — вместо того, чтобы агент делал дюжину отдельных shell-запросов и каждый раз разбирал сырой вывод CLI.

• Одна и та же проверка каждый раз. Точные проверки для каждой экосистемы (Gradle wrapper vs. системный Gradle, .nvmrc vs. package.json engines, ...) закодированы один раз, поэтому диагноз стабилен между сессиями, а не зависит от того, что агенту пришло в голову выполнить.

• Безопаснее, чем дать агенту shell. Никакого произвольного выполнения команд, никаких разрушительных операций, никогда — см. Модель безопасности.

• Секреты не трогаются. Переменные окружения, которые выглядят как секретные, проверяются только на наличие; значения никогда не читаются и не возвращаются — см. Модель конфиденциальности.

• Работает даже там, где у агента нет shell. MCP-клиенты без инструмента Bash (некоторые IDE-ассистенты, ограниченные агенты) получают эту возможность вообще, а не ноль возможностей.

Стоимость в токенах

Реальные цифры, а не оценка — измерено напрямую из схем инструментов этого сервера (mcp.list_tools()) и реального ответа dev_health(), с использованием стандартного приближения ~4 символа на токен.

Два разных момента тратят токены, и стоят они очень по-разному:

Разбивка схем по инструментам (измерено):

Честный итог: для одноразовой диагностики в сессии, которая в остальном никогда не касается вопросов окружения, raw Bash может оказаться дешевле по суммарным токенам — фиксированный налог в ~1 400 токенов на схемы часто перевешивает экономию от замены нескольких shell-команд одним вызовом. См. сравнение ниже с реальными цифрами по обеим сторонам.

Аргумент в пользу DevTwin становится сильнее, чем больше вопросов об окружении возникает в одной сессии (фиксированный налог платится один раз; каждый следующий вопрос — это ~150 токенов на DevTwin против сотен на raw Bash каждый раз) — а его реальное преимущество не в сыром количестве токенов, а в стабильности, безопасности и работе в MCP-клиентах, где нет инструмента Bash. См. Преимущества и Честные компромиссы.

Практическое следствие: регистрируйте DevTwin по-проектно, а не для всех пользователей, чтобы фиксированный налог платился только в сессиях, где он реально полезен — см. Использование на другом проекте.

Честные компромиссы

DevTwin — не инструмент ежедневного использования для стабильного окружения: никому не нужно перепроверять «запущен ли Postgres» на каждой функции, которую он пишет. Это инструмент для экстренных случаев: высокая ценность в конкретные моменты (свежий клон, загадочно падающая сборка, прямо перед коммитом), и простаивает в остальное время. Это предполагаемый паттерн использования, а не недостаток.

• Налог на токены платится на каждом ходу с момента подключения, используется он или нет — см. Стоимость токенов с реальными замерами.

• Он не всегда выигрывает по токенам для одного разового вопроса; он выигрывает в консистентности, безопасности и доступе к клиентам без оболочки — см. Преимущества.

• Если у агента уже есть полный доступ к оболочке в репозитории, который вы полностью контролируете, и он редко сталкивается с расхождением окружения, DevTwin там может вообще не понадобиться.

• DevTwin больше всего оправдывает себя на: общих/онбординговых репозиториях, менее доверенных или не имеющих оболочки настройках агентов и мультиэкосистемных монорепозиториях, где «что мне вообще проверять» само по себе является сложной задачей.

С DevTwin и без: наглядный пример

Скажем, вы спрашиваете агента: «почему npm test падает?» — а настоящая причина в несоответствии версии Node и незапущенном Postgres.

Без DevTwin (агент использует чистый Bash) — ему приходится угадывать правильную последовательность, по одной команде за раз:

cat package.json                      # spot "engines": {"node": ">=20"}
node --version                        # v16.20.0 -- mismatch found
grep -i "pg\|postgres" package.json   # spot the Postgres dependency
cat .env                              # risk: may print a real secret into context
lsof -i :5432                         # nothing listening
docker ps                             # check if it's in a container instead

Шесть обращений туда-обратно, путь исследования, который агенту пришлось придумать, реальный шанс утечки секрета в разговор на шаге 4 и примерно 400–800 токенов текста команд и вывода (зависит от размеров файлов и количества запущенных Docker-контейнеров).

С DevTwin — один вызов:

dev_health()

{
  "status": "error",
  "summary": "2 issues found: runtime drift, service down",
  "issues": [
    "Node 16.20.0 installed, project requires >=20 (from package.json engines)",
    "Postgres required (found in docker-compose.yml) but not running on 5432"
  ],
  "recommendations": [
    "nvm install 20 && nvm use 20",
    "docker compose up -d postgres"
  ]
}

Тот же вывод, ~150 токенов за ответ — плюс фиксированные ~1400 токенов схемы, которые в любом случае уже оплачены в этом ходе (см. Стоимость токенов). Один вызов вместо шести, никакой возможности утечки секрета и каждый раз одна и та же выверенная проверка вместо импровизированного исследования, которое меняется от сессии к сессии.

Примеры вопросов, которые это открывает

• «Проверь моё окружение разработки».

• «Почему мой Kotlin-проект не собирается?»

• «Соответствует ли моя версия Node этому репозиторию?»

• «Почему моё приложение не может подключиться к Postgres?»

• «Отличается ли моё окружение от того, что ожидает этот репозиторий?»

• «Что мне запустить перед коммитом?»

• «Я только что склонировал репозиторий — что мне нужно сделать, чтобы запустить его?»

Примеры по языкам

По одной строке на поддерживаемую экосистему: вопрос, который вы реально зададите, что DevTwin проверяет для ответа на него и тестовую/сборочную команду, которую он распознаёт для dev_check.

Архитектура

Один MCP-сервер, много адаптеров экосистем — а не отдельный сервер на каждый язык.

MCP server -> core (workspace/detector/health/drift/diagnostics) ->
adapters (python/node/jvm/go/rust/dotnet/swift/ruby/php/generic) ->
system inspection (os/process/ports/env/fs/docker) ->
service detection (postgres/redis/generic)

Подробности в docs/architecture.md. Как добавить новый языковой адаптер: docs/adapters.md.

Поддерживаемые экосистемы

Любой проект, не подходящий ни под один конкретный адаптер, всё равно получит полезный вывод от универсального адаптера — DevTwin никогда не возвращает пустоту для нераспознанного проекта.

Установка

uv pip install devtwin-mcp
# or
pip install devtwin-mcp

Для локальной разработки с клоном этого репозитория см. docs/development.md.

Конфигурация MCP-клиента

Точный синтаксис конфигурации зависит от клиента — обратитесь к документации вашего клиента. В общем случае DevTwin — это stdio MCP-сервер, который вызывается так:

{
  "mcpServers": {
    "devtwin": {
      "command": "devtwin"
    }
  }
}

Для локальной разработки из клона (без установки пакета):

{
  "mcpServers": {
    "devtwin": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/devtwin-mcp", "devtwin"]
    }
  }
}

Проверьте обнаружение инструментов с помощью MCP Inspector:

npx @modelcontextprotocol/inspector uv run devtwin

Использование в другом проекте (для других разработчиков)

DevTwin — это один бинарник: подключайте сколько угодно проектов к одной установке, переустановка для каждого проекта не нужна. Две области действия:

Проектная область — положите .mcp.json в корень проекта:

{
  "mcpServers": {
    "devtwin": {
      "command": "/absolute/path/to/devtwin-mcp/.venv/bin/devtwin"
    }
  }
}

или с помощью Claude Code CLI:

claude mcp add devtwin /absolute/path/to/devtwin-mcp/.venv/bin/devtwin --scope project

Пользовательская область:

claude mcp add devtwin /absolute/path/to/devtwin-mcp/.venv/bin/devtwin --scope user

После добавления перезапустите клиент (или переподключите MCP-сервер), а затем просто задавайте обычные вопросы — см. Примеры вопросов, которые это открывает.

Совет по монорепозиториям: в репозитории со смешанными платформами (например, Android + iOS + бэкенд) адресуйте вопросы к конкретной подпапке, а не к корню репозитория — например, «проверь здоровье приложения android/». dev_detect в корне смешанного репозитория сообщает обо всех найденных экосистемах, что полезно один раз, но избыточно для точечной проверки.

Справочник инструментов

Все инструменты возвращают {status, summary, data, issues, recommendations}. status — одно из значений: ok, warning, error, unknown.

Модель безопасности

• Никакого произвольного выполнения команд. Инструмента execute_shell не существует. dev_check запускает только те команды, которые DevTwin сам распознал в файлах проекта, проверяет их по разрешённому списку, запускает с shell=False и тайм-аутом.

• Никогда никаких разрушающих действий. DevTwin никогда не запускает git reset --hard, rm -rf, kill -9, docker compose down, не удаляет лок-файлы и не изменяет .env.

• dev_prepare только планирует. Он классифицирует каждый предлагаемый шаг (read_only/safe/requires_approval/dangerous) и сам никогда ничего не выполняет.

Подробнее: docs/security.md.

Модель приватности

• Переменные окружения проверяются только на наличие, когда их имя выглядит секретным (PASSWORD, TOKEN, SECRET, API_KEY, PRIVATE_KEY, ACCESS_KEY, AUTH, CREDENTIAL, ...) — значения никогда не возвращаются.

• Файлы .env сканируются только на имена переменных.

• dev_precommit помечает подготовленные имена файлов, выглядящие как секретные, не читая и не сообщая их содержимое.

Локально-ориентированная архитектура

• Нет серверного компонента, нет учётной записи, нет собственных сетевых вызовов, кроме локальных команд, которые он проверяет (git, docker, языковые тулчейны).

• Всё, о чём он сообщает, берётся из файлов и процессов, уже находящихся на машине, на которой он работает.

Разработка

uv sync --all-extras
uv run pytest
uv run ruff check .
uv run mypy src
uv run devtwin

Полный рабочий процесс см. в docs/development.md.

Участие

См. CONTRIBUTING.md. Добавление новой языковой экосистемы — самый частый вид вклада: шаблон — в docs/adapters.md, или src/devtwin/adapters/swift.py, ruby.py и php.py — как настоящие, принятые примеры для создания своего адаптера.

Дорожная карта

• Добавление адаптеров экосистем: Elixir, Dart, Scala, C/C++ (CMake/Bazel/Buck), Nix (о том, как добавить новый, см. docs/adapters.md)

• Дополнительные детекторы сервисов (rip MySQL/MariaDB, MongoDB, Kafka, RabbitMQ)

• Расширенное сравнение отклонений с конфигурацией CI (например, матрицы сред выполнения в GitHub Actions)

• Опциональное локальное кеширование затратных проверок между вызовами инструментов в рамках сессии

Лицензия

Apache-2.0 — см. LICENSE.