Auto Knowledge Sync MCP

Локальный MCP-сервер, который превращает технические знания, полученные в ходе LLM-сессий разработки, в завершённые документы и накапливает их как источник знаний для отдельного разработчика или команды. MCP запускается в Docker-контейнере на компьютере пользователя, а единственным источником истины (SSOT) для знаний служит приватный GitHub-репозиторий, указанный пользователем.

Зачем это нужно?

Объяснения, решения и предостережения, которыми вы обмениваетесь с LLM во время разработки, полезны, но легко теряются после завершения сессии. Этот проект встраивает следующий процесс в привычный способ использования MCP.

1. LLM предлагает технические знания, которые стоит сохранить для повторного использования в будущих сессиях.

2. MCP проверяет документ на полноту, наличие личной или внутренней конфиденциальной информации и включение исходного кода.

3. В репозиторий GitHub коммитятся только одобренные предложения.

4. В дальнейшем знания постоянно обновляются через поиск, проверку, оспаривание и реструктуризацию.

Сохраняемые документы — это не просто список ключевых слов, а самостоятельные записи знаний (knowledge entry), объясняющие концепцию, принцип работы, техническую значимость, решаемую проблему, условия применения и ограничения. Если нужны примеры кода, допускаются только новые примеры, а не копии или модификации существующего рабочего кода.

Related MCP server: Internal Documentation Search

Основные возможности

• Удалённый SSOT: знания и история изменений фиксируются в коммитах GitHub. Локально хранятся только воспроизводимый поисковый индекс и временные данные.

• Блокировка конфиденциальной информации: встроенная проверка секретов и PII, а также опциональные правила запрета для конкретной организации; применяется политика fail-closed — при неудачной проверке данные не сохраняются.

• Явное одобрение: режим одобрения по умолчанию — always. При необходимости его можно переключить на on_risk или never; жёсткие проверки безопасности и изменения высокого риска проверяются всегда.

• Жизненный цикл знаний: помимо поиска поддерживаются подача контрпримеров, проверка устаревания и дубликатов, упорядочивание связей, а также предложения по слиянию, разделению, переклассификации и объявлению устаревшими.

• Без серверной части: нет постоянно работающего центрального сервера или операционной базы данных. MCP запускается локально, когда его вызывает MCP-клиент, например Codex или Claude Code.

• Минимальные права: PAT выдаётся только на указанный приватный репозиторий; MCP не требует прав на организации GitHub, Actions или pull request.

Требования

• Docker Desktop или Docker Engine

• приватный GitHub-репозиторий, который будет использоваться как хранилище знаний

• fine-grained PAT, ограниченный только этим репозиторием

  • Metadata: Read-only

  • Contents: Read and write

  • Права на Pull requests, Actions и Administration не выдаются

• Для сборки из исходников — Node.js 24 или новее и Git

Перед сохранением корпоративных материалов проверьте политику организации по использованию внешнего GitHub. При первом запуске рекомендуется проверить подключение на синтетическом техническом содержимом, а не на реальных рабочих материалах.

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

1. Подготовка исходников и локального образа

git clone https://github.com/One-armed-boy/auto-knowledge-sync-mcp.git
cd auto-knowledge-sync-mcp
npm ci
npm run build
docker build --tag auto-knowledge-sync-mcp:local .

2. Создание файла PAT и конфигурации

Не вставляйте PAT напрямую в командную строку или YAML — храните его в файле, доступном только владельцу.

CONFIG_DIR="$HOME/.config/auto-knowledge-sync"
PAT_FILE="$CONFIG_DIR/secrets/github_pat"

mkdir -p "$CONFIG_DIR/secrets"
umask 077
touch "$PAT_FILE"
chmod 600 "$PAT_FILE"
${EDITOR:-nano} "$PAT_FILE"

node dist/cli.js init \
  --repository <GITHUB_OWNER>/<PRIVATE_KNOWLEDGE_REPOSITORY> \
  --token-file "$PAT_FILE"

init создаёт файл конфигурации по умолчанию и загружает манифест знаний в репозиторий. Если использовать конфигурацию по умолчанию, вручную править YAML не нужно. Создаваемые пути по умолчанию:

$HOME/.config/auto-knowledge-sync/config.yaml
$HOME/.config/auto-knowledge-sync/secrets/github_pat

3. Диагностика подключения и регистрация MCP-клиента

doctor проверяет репозиторий, права PAT, совместимость схемы, состояние ветки и кэша, а также выводит команды регистрации для Codex и Claude Code.

CONFIG_FILE="$CONFIG_DIR/config.yaml"

node dist/cli.js doctor \
  --config-file "$CONFIG_FILE" \
  --token-file "$PAT_FILE" \
  --client-commands \
  --image-ref auto-knowledge-sync-mcp:local \
  --host-config-file "$CONFIG_FILE" \
  --host-token-file "$PAT_FILE"

Выполните команду client_commands.codex или client_commands.claude из вывода один раз в соответствующем клиенте. После регистрации подключение можно проверить так:

codex mcp list
codex mcp get auto-knowledge-sync
claude mcp list
claude mcp get auto-knowledge-sync

Если нужна команда клиента, которая запускает результат сборки на хосте напрямую, а не через образ, опустите --image-ref и опции монтирования хоста в doctor --client-commands. О стабильном release-образе и Compose runtime с фиксированным digest см. документацию по установке и эксплуатации.

Основное использование

После подключения LLM работает в следующем порядке.

1. repository_status — проверка состояния удалённого репозитория и схемы.

2. search_knowledge или get_knowledge — чтение существующих знаний.

3. capture_knowledge — предложение новых технических знаний.

4. Проверка результата на конфиденциальность и полноту, затем apply_proposal для коммита.

5. При обнаружении устаревших знаний или контрпримеров — challenge_knowledge или maintain_knowledge.

Доступные инструменты MCP:

Все изменения используют ключ идемпотентности и проверку удалённого HEAD. При конфликте система предлагает заново выполнить поиск текущего состояния и создать новое предложение.

Конфигурация

Значения по умолчанию заданы консервативно.

schema_version: 1
repository:
  slug: owner/private-knowledge
publishing:
  approval_mode: always
privacy:
  fail_closed: true
search:
  lexical: true
  vector:
    enabled: false
maintenance:
  inline_budget_ms: 200
logging:
  content: never

Большинству пользователей достаточно конфигурации, созданной init. Режим одобрения или правила запрета для организации нужны только при использовании init --advanced или --privacy-rules-file. Примеры — в examples/privacy-rules.yaml.

Подробные параметры и правила совместимости — в документации по конфигурации и эксплуатации, схема — в spec/schemas.

Принципы данных и безопасности

• Приватный GitHub-репозиторий — единственный SSOT для знаний; локальный индекс SQLite можно удалить и воссоздать.

• В записи знаний не включаются рабочие исходники, внутренние идентификаторы, учётные данные и приватный исходный код.

• Если нужно описать код — создаётся новый независимый пример, а не копия оригинала.

• PAT не копируется в конфигурацию и передаётся в контейнер через read-only bind mount.

• Конфигурация, PAT, приватные Markdown-файлы и рабочий код не должны попадать в Git working tree или контекст сборки Docker.

• В логи не записываются текст знаний и секреты.

Модель угроз и конвейер конфиденциальности — в документации по безопасности и конфиденциальности, процедура сообщения об уязвимостях — в SECURITY.md.

Формат хранилища знаний

В GitHub-репозитории по канонической схеме хранятся записи знаний, карточки обоснований, рецензии на оспаривание, регрессионные кейсы и сгенерированный INDEX.md. Правила каталогов, frontmatter и связей — в спецификации хранилища знаний, политика поиска и обновления — в документации по поиску и жизненному циклу знаний.

Обновление

Release-образ использует проверенный digest образа, а не изменяемый тег. runtime init создаёт стабильный Compose-дескриптор, поэтому после замены PAT или обновления образа не нужно перерегистрировать MCP-клиент. Сначала проверьте совместимость через upgrade --check, затем выполните runtime update-image --verified-release. Миграции схемы и конфигурации применяются автоматически с файлами миграции по версиям и не перезаписывают исходную конфигурацию произвольно.

Подробные процедуры — в документации по миграциям и документации по установке и эксплуатации.

Разработка

Для участия в разработке в среде Node.js 24+ выполните:

npm ci
npm run check

Команды тестирования и оценки, а также правила изменений — в документации по тестированию и оценке и архитектуре системы.

Дополнительно

• Спецификация продукта и требования

• Исследовательская база

• Архитектура системы

• Спецификация MCP API

• Хранение в GitHub и конкурентность

• Безопасность и конфиденциальность

Лицензия пакета — Apache-2.0.