Twining MCP Server

Проблема

Вы тратите два часа с Claude Code на принятие архитектурных решений. Вы выбираете PostgreSQL вместо MongoDB. Вы останавливаетесь на JWT для аутентификации. Вы отмечаете состояние гонки (race condition) в платежном модуле. Затем сессия заканчивается.

Завтра вы начинаете новую сессию. Claude понятия не имеет, что произошло. Решения исчезли. Предупреждения исчезли. Обоснования исчезли. Вы пересказываете всё заново — или, что еще хуже, Claude молча противоречит вчерашним решениям.

Ситуация усугубляется при работе с несколькими агентами. Агент А выбирает REST. Агент Б выбирает gRPC для того же сервиса. Ни один из них не знает о существовании другого. Вы узнаете об этом, когда код не компилируется.

Контекстные окна эфемерны. Решения вашего проекта не должны быть такими.

Как Twining решает эту проблему

Twining — это MCP-сервер, который дает вашим ИИ-агентам постоянную память проекта. Решения сохраняются после сброса контекста. Новые сессии начинаются с полной информацией. Работа нескольких агентов остается скоординированной.

# Install in 10 seconds
/plugin marketplace add daveangulo/twining-mcp
/plugin install twining@twining-marketplace

Записывайте, что вы сделали — на естественном языке:

twining_record({
  summary: "Added Redis caching to UserService",
  decisions: ["Chose Redis over Memcached — need persistence across restarts"],
  assumptions: ["Read-heavy workload (10:1 ratio)"],
  scope: "src/services/"
})

Twining анализирует ваши решения, превращая их в структурированные записи — автоматически извлекая обоснования, отклоненные альтернативы и предметную область. Один вызов инструмента, никаких форм.

Начните новую сессию. Получите всю информацию мгновенно:

twining_assemble({ task: "optimize the caching layer", scope: "src/services/" })

Twining оценивает каждое решение, предупреждение и находку по степени релевантности вашей задаче, а затем заполняет бюджет токенов в порядке приоритета. Вы получаете именно тот контекст, который вам нужен — без лишнего потока данных и повторных объяснений.

Спрашивайте, почему всё устроено именно так:

twining_why({ scope: "src/auth/middleware.ts" })

Возвращает полную цепочку решений для любого файла: что было решено, когда, почему, какие альтернативы были отклонены и какой коммит это реализовал.

Почему не использовать просто CLAUDE.md?

CLAUDE.md статичен. Вы пишете его один раз и обновляете вручную. Он не фиксирует решения по мере их принятия, не отслеживает обоснования или альтернативы, не обнаруживает конфликты между агентами и не может выборочно собирать контекст в рамках бюджета токенов.

Twining динамичен. Каждый вызов twining_decide записывает структурированное решение. Каждый twining_post делится находкой или предупреждением. Каждый twining_assemble оценивает релевантность и предоставляет именно то, что нужно для текущей задачи. Директория .twining/ — это живая институциональная память вашего проекта.

Почему не использовать оркестратор?

Оркестраторы (например, рои агентов и иерархические координаторы) распределяют работу, назначая задачи. Twining координирует работу, обмениваясь состоянием. Разница существенна:

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

• «Доска объявлений» Twining сохраняет состояние координации вне окна любого агента, переживая сбросы контекста без потери информации.

Агенты сами выбирают работу, читая «доску объявлений». Никаких центральных узких мест. Никаких ретрансляторов, теряющих контекст. Каждый агент видит решения и предупреждения всех остальных агентов напрямую.

Установка

Установка плагина (рекомендуется)

# Add the marketplace (one-time)
/plugin marketplace add daveangulo/twining-mcp

# Install the plugin
/plugin install twining@twining-marketplace

Включает MCP-сервер, навыки, хуки жизненного цикла и принудительное выполнение перед коммитом. Два шлюза: twining_assemble перед работой, twining_record перед коммитом — хуки обеспечивают выполнение обоих автоматически.

Автоматическая установка для команды

Закоммитьте это в .claude/settings.json вашего репозитория, чтобы каждый член команды получал Twining при клонировании:

{
  "extraKnownMarketplaces": {
    "twining-marketplace": {
      "source": {
        "source": "github",
        "repo": "daveangulo/twining-mcp"
      }
    }
  },
  "enabledPlugins": {
    "twining@twining-marketplace": true
  }
}

Когда члены команды доверяют папке репозитория, Claude Code автоматически устанавливает маркетплейс и плагин.

Установка только MCP

Для клиентов, отличных от Claude Code (Cursor, Windsurf и т.д.):

claude mcp add twining -- npx -y twining-mcp --project .

Или добавьте в .mcp.json:

{
  "mcpServers": {
    "twining": {
      "command": "npx",
      "args": ["-y", "twining-mcp", "--project", "."]
    }
  }
}

Инструкции MCP-сервера автоматически включаются в ответ инициализации.

Обновление с ручной установки

Если вы ранее настраивали Twining вручную, переключитесь на плагин:

1. Удалите ручной MCP-сервер: claude mcp remove twining

2. Установите плагин: /plugin marketplace add daveangulo/twining-mcp затем /plugin install twining@twining-marketplace

3. Очистка: удалите хуки Twining из .claude/settings.json, удалите .claude/agents/twining-aware.md, если он есть, удалите разделы Twining из CLAUDE.md (теперь это обрабатывают навыки)

4. Сохраните: директорию .twining/ (все состояние сохранено)

5. Проверка: /twining:status

Получение максимальной пользы

Плагин автоматически обрабатывает инструкции агента через навыки. Для пути установки только через MCP добавьте инструкции Twining в CLAUDE.md вашего проекта, чтобы агенты использовали его автоматически — см. docs/CLAUDE_TEMPLATE.md для готового шаблона.

Панель управления

Веб-панель управления запускается автоматически по адресу http://localhost:24282 — просматривайте решения, записи на доске, граф знаний и состояние агентов. Настраивается через TWINING_DASHBOARD_PORT.

Что внутри

Основные инструменты (всегда доступны)

Это инструменты, которые агенты используют в каждой сессии:

twining_record принимает решения на естественном языке, такие как "Выбрал Redis вместо Memcached — нужна персистентность", и автоматически анализирует их, превращая в структурированные записи с обоснованием, отклоненными альтернативами и выведенной предметной областью. Он также принимает допущения, ограничения, затронутые файлы и цепочки зависимостей — всё, что нужно хранилищу решений для высокоточной сборки контекста.

Расширенные инструменты (доступны при full_surface: true)

Для продвинутых рабочих процессов — глубокое управление решениями, исследование графа, координация нескольких агентов:

Включите через .twining/config.yml:

tools:
  full_surface: true

Как это работает

Все состояние хранится в .twining/ в виде обычных файлов — JSONL для доски объявлений, JSON для решений, графа, агентов и передач. Всё доступно для запросов jq, поиска grep и сравнения git-diff. Никаких баз данных. Никакого облака. Никаких аккаунтов.

Уровни архитектуры:

• Хранилище — Файловые хранилища с блокировкой для параллельного доступа

• Движок — Отслеживание решений, доска объявлений, обход графа, сборка контекста с бюджетированием токенов, координация агентов

• Эмбеддинги — Локальные all-MiniLM-L6-v2 через @huggingface/transformers, с ленивой загрузкой и резервным поиском по ключевым словам. Сервер никогда не перестает запускаться из-за проблем с эмбеддингами.

• Панель управления — Веб-интерфейс только для чтения с визуализацией графа cytoscape.js и vis-timeline

• Инструменты — Определения инструментов MCP, проверенные с помощью Zod, отображаемые 1:1 на поверхность инструментов

См. TWINING-DESIGN-SPEC.md для полной спецификации.

Часто задаваемые вопросы

Замедляет ли Twining работу Claude Code? Нет. Это локальный MCP-сервер — вызовы инструментов — это локальное чтение/запись файлов. Семантический поиск загружается лениво при первом использовании.

Могу ли я использовать его с Cursor, Windsurf или другими MCP-клиентами? Да. Twining — это стандартный MCP-сервер. Любой MCP-хост может подключиться к нему.

Куда уходят мои данные? Все состояние координации находится локально в .twining/. Метрики вызовов инструментов хранятся локально в .twining/metrics.jsonl (игнорируется git). Можно включить опциональную анонимную телеметрию — см. Аналитика ниже.

Является ли Twining оркестратором агентов? Нет. Это уровень состояния координации. Он фиксирует, что решили агенты и почему, и делает эти знания доступными для будущих агентов. Используйте его вместе с оркестраторами, командами агентов или отдельными сессиями.

Аналитика

Twining включает трехуровневую систему аналитики, которая поможет вам понять ценность, которую он предоставляет.

Вкладка «Аналитика» на панели управления

Веб-панель управления включает вкладку Аналитика, показывающую:

• Метрики ценности — Скорость предотвращения слепых решений, подтверждение предупреждений, покрытие тестами через связи графа tested_by, прослеживаемость коммитов, жизненный цикл решений, статистика графа знаний и метрики координации агентов

• Использование инструментов — Количество вызовов, частота ошибок, средняя/P95 задержка на инструмент

• Разбивка ошибок — Ошибки, сгруппированные по инструменту и коду ошибки

Все метрики ценности вычисляются на основе существующих данных .twining/ — сбор новых данных не требуется.

Метрики вызовов инструментов

Каждый вызов инструмента MCP автоматически инструментируется с отслеживанием времени и успеха/ошибки. Метрики хранятся локально в .twining/metrics.jsonl (игнорируется git — операционные данные, не архитектурные).

Чтобы отключить сбор локальных метрик, установите в .twining/config.yml:

analytics:
  metrics:
    enabled: false

Телеметрия с возможностью отказа (Opt-in)

Анонимные агрегированные данные об использовании могут опционально отправляться в PostHog, чтобы помочь улучшить Twining. По умолчанию отключено. Чтобы включить, добавьте в .twining/config.yml:

analytics:
  telemetry:
    enabled: true

Это всё — ключ проекта PostHog встроен в исходный код. Если вы запускаете свой собственный экземпляр PostHog, вы можете переопределить его с помощью posthog_api_key и posthog_host.

Что отправляется: имена инструментов, длительность вызовов, логические значения успеха/неудачи, версия сервера, ОС, архитектура.

Что никогда не отправляется: пути к файлам, содержание решений, имена агентов, сообщения об ошибках, аргументы инструментов, переменные окружения.

Меры конфиденциальности:

• Переменная окружения DO_NOT_TRACK=1 всегда переопределяет конфигурацию

• CI=true автоматически отключает телеметрию

• Идентификатор — это SHA-256 хэш имени хоста + корня проекта (никогда не передаются полные пути)

• Сетевые сбои игнорируются — повторных попыток нет

• posthog-node является опциональной зависимостью — изящный no-op, если не установлен

Разработка

npm install       # Install dependencies
npm run build     # Build
npm test          # Run tests (800+ tests)
npm run test:watch

Требуется Node.js >= 18.

CI/CD

Два рабочих процесса GitHub Actions автоматизируют проверку сборки и публикацию:

CI (.github/workflows/ci.yml) — запускается при каждом PR и push в main:

• Собирает и тестирует на Node 18, 20 и