UVZ Local Library MCP

Локальная база знаний для GigaCode по Jimmer, внутренним библиотекам, приложениям, конфигурации и инженерным стандартам.

Проект индексирует исходники в SQLite FTS5 и подключает их к агенту через локальный stdio MCP. Внешняя сеть и удалённый MCP-сервер не нужны.

Что получает агент

• поиск по Java, Kotlin, frontend-коду, документации и примерам;

• проверенные карточки project-context.yaml с назначением проекта;

• общий system-overview.md для межпроектных потоков и границ системы;

• проверяемый knowledge-glossary.yaml для внутренних терминов, сокращений и русско-английских поисковых aliases;

• golden path примеры из docs/usage/*.md;

• точные Gradle aliases из uvz-platform;

• реальные Gradle consumers внутренних библиотек;

• YAML-конфигурацию из приложений и нескольких наборов uvz-config;

• explainable Spring YAML resolution по application name, ordered profiles и imports с provenance, resolution_complete и SSL bundle inventory;

• source id, repository, commit, path и строки для каждого ответа;

• кликабельные commit-pinned ссылки на source-файлы в GitHub и Bitbucket Server, построенные только из фактического индексированного Git remote;

• Git remote, branch, commit time, sync/provenance status каждого repository;

• русско-английскую нормализацию запросов, проверяемое расширение русских backend/Jimmer-терминов к англоязычной документации, aliases из project-context.yaml и безопасный exact → relaxed fallback;

• отдельное объяснение поиска без выдачи исходного текста: normalized terms, alias/bilingual expansion, exact/relaxed stages, coverage, ranking и provenance;

• измеримый context coverage по каждому Gradle-модулю и автоматически проверяемый retrieval case для каждой curated-карточки и usage-примера.

При поиске приоритет такой:

1. system-overview.md, knowledge-glossary.yaml и project-context.yaml — архитектурная маршрутизация, термины, назначение и границы использования;

2. docs/usage/*.md — рекомендуемый способ подключения;

3. документация и тестовые примеры;

4. исходный код и конфигурация.

Related MCP server: Hoard

Как устроен процесс

Исходные repositories
        ↓
project-context.yaml + docs/usage
        ↓
Индексация и quality gate
        ↓
knowledge-pack-<version>.zip
        ↓
./install.sh у разработчика
        ↓
GigaCode → local-library-mcp → SQLite

Есть две роли:

• Maintainer имеет все repositories, готовит контекст, строит и публикует knowledge pack.

• Developer получает этот проект с готовым pack и запускает только ./install.sh.

Требования

Для maintainer:

• Git;

• Python 3.9 или новее;

• GigaCode;

• доступ к индексируемым repositories.

Для developer достаточно Python 3.9+ и GigaCode. Docker, Node.js, Rust, Cargo и Xcode Command Line Tools не нужны. Runtime MCP использует только стандартную библиотеку Python.

На Windows установку запускай из Git Bash с нативным Python 3.9+. Installer выполняет stdio smoke test, который отдельно проверяет передачу русского текста в UTF-8 и останавливает установку при повреждённой кодировке.

1. Первая установка maintainer

Все индексируемые Git repositories должны находиться внутри одной workspace:

/path/to/projects/
  uvz-local-library-mcp/
  jimmer/
  jimmer-doc/
  jimmer-examples/
  uvz-platform/
  uvz-config/
  schedulex/
  other-projects/

Клонируй MCP-проект:

PROJECTS=/path/to/projects
cd "$PROJECTS"
git clone git@github.com:asimmetria/uvz-local-library-mcp.git
cd uvz-local-library-mcp

Первичная индексация одновременно установит MCP и основной skill:

./install.sh \
  --workspace "$PROJECTS" \
  --sync \
  --configuration-root "$PROJECTS/uvz-config"

Если рабочая ОС использует нестандартные домашнюю папку и Python:

GIGACODE_HOME="/path/to/.gigacode" \
MCP_RUNTIME_HOME="/path/to/projects/.mcp-runtime" \
PYTHON_BIN="/path/to/.gigacode/.venv/bin/python" \
./install.sh \
  --workspace "/path/to/projects" \
  --sync \
  --configuration-root "/path/to/projects/uvz-config"

После установки перезапусти GigaCode.

Чтобы после git pull обновить только MCP runtime и основной skill, не переиндексируя workspace и не устанавливая случайно старый pack из dist, используй:

./install.sh --runtime-only

Режим требует существующую knowledge.db, запускает transport/UTF-8 smoke test и гарантированно не заменяет базу.

Что делает --workspace

• находит каждый Git repository рекурсивно и индексирует его один раз;

• обнаруживает Gradle-модули, в том числе библиотеки внутри приложений;

• отдельно индексирует Jimmer docs/examples;

• для Docusaurus пропускает переводы из i18n, если есть канонические docs;

• сопоставляет каждый Gradle-модуль с context-карточкой или доказанным no_context_required;

• объединяет ручные business cases с автоматически созданными context/usage cases;

• строит новый индекс во временной папке;

• заменяет рабочую базу только после успешных проверок.

--configuration-root не индексирует repository повторно. Он помечает центральный конфигурационный repository и его наборы конфигураций.

Общая архитектура и внутренние термины

Для знаний, которые относятся сразу к нескольким repositories, положи в корень одного индексируемого приватного repository:

system-overview.md
knowledge-glossary.yaml

Первый файл описывает приложения, владельцев данных, основные потоки и платформенные правила. Второй связывает канонические термины из кода с русскими названиями и внутренними сокращениями. Оба валидируются при индексации и получают приоритет context; glossary aliases участвуют в объяснимом расширении поискового запроса.

Не создавай эти файлы в каждом проекте. Для общей системы рекомендуется один reviewed источник, например индексируемый uvz-ai; отдельные bounded contexts могут иметь собственные overview/glossary только при явной необходимости. Шаблоны и полный контракт: workspace knowledge.

2. Подготовка project-context.yaml

Authoring skill устанавливается только maintainer-у:

./scripts/install-project-context-authoring.sh

После установки перезапусти GigaCode. Workspace обрабатывает один основной агент, без субагентов. Shell tool у него отключён, поэтому он не сможет обходить file-editing policy через heredoc или перенаправление вывода.

Последовательная обработка всей workspace

Перед запуском проверь через /mcp, что local-library-mcp подключён и показывает campaign tools project_context_campaign_next, start, finish и report, а также validate_project_context. Затем запусти runner из MCP repository:

cd /path/to/projects/uvz-local-library-mcp
./skills/project-context-authoring/scripts/run-all-project-contexts.sh \
  "/path/to/projects"

Другой разработчик заменяет абсолютные пути на свои.

Runner:

• находит все Git repositories и передаёт их одному основному GigaCode-агенту;

• основной агент обрабатывает repositories строго последовательно и не запускает субагентов;

• включает auto-edit, заранее разрешает read-only MCP tools suggest_dependency, find_library_usages, validate_project_context и отдельно четыре ограниченных campaign-state tools;

• полностью отключает agent/subagent и shell tools;

• не проверяет dirty как условие допуска: незакоммиченные repositories тоже обрабатываются, а существующие изменения запрещено сбрасывать или затирать;

• перед каждой попыткой controller сохраняет fingerprint файлов вне authoring scope; при изменении любого такого файла repository получает terminal failed, а третья попытка запрещена;

• сразу после каждого repository атомарно записывает successful, failed или no_context_required;

• разрешает отдельный итог no_context_required только для repository без build/source signals, с русской причиной и существующим relative evidence;

• делает не больше двух попыток на один repository;

• требует VALIDATION_OK внутри попытки, чтобы агент сразу видел и исправлял точные ошибки schema и paths;

• требует русский summary, сохраняет явные unknowns и независимо проверяет полноту module coverage при finish;

• после agent session повторно запускает deterministic validator для всех успешных карточек;

• создаёт агрегированный review-файл с результатом каждого repository.

State локален и игнорируется Git:

.project-context-authoring-campaign.json
.project-context-authoring-review.json

State содержит имя, локальный путь, status, число попыток, summary, unknowns, coverage и fingerprint релевантных файлов. Review удобен для общего просмотра: в нём есть totals, агрегированное покрытие, failures и доказанные exemptions. Оба файла локальны и игнорируются Git.

После прерывания просто повтори ту же команду. Неизменённые successful и no_context_required не обрабатываются повторно. Controller автоматически возвращает ровно нужный repository в pending, если изменился его source, build descriptor, README/docs, project-context.yaml или docs/usage, либо если deterministic coverage перестал сходиться. Для переоткрытого repository начинаются новые две попытки, а причина записывается в last_invalidation. Для сознательного полного перезапуска используй --restart: старый state копируется в timestamped backup.

Чтобы repository индексировался, но authoring-skill не создавал в нём project-context.yaml и docs/usage/*.md, используй отдельный список:

cp project-context-exclude.example.txt project-context-exclude.txt

По умолчанию шаблон содержит uvz-ai: его документы остаются в индексе, но authoring-кампания его не обрабатывает. index-exclude.txt остаётся общим исключением: перечисленные там repositories не участвуют ни в индексации, ни в authoring.

cd /path/to/projects/uvz-local-library-mcp
./skills/project-context-authoring/scripts/run-all-project-contexts.sh \
  "/path/to/projects" --restart

Восстановление state после старого validator workflow

Версии до MCP 1.4.0 сохраняли только общую ошибку Deterministic validation failed after the agent session, поэтому повторная попытка не знала, что именно исправлять. После обновления один раз верни только такие записи в очередь:

cd /path/to/projects/uvz-local-library-mcp
./skills/project-context-authoring/scripts/run-all-project-contexts.sh \
  "/path/to/projects" \
  --reset-validation-failures

Успешные и ещё не обработанные repositories не сбрасываются. Для возвращённых записей начинается новый лимит из двух попыток уже с validator feedback внутри agent session. В следующих запусках этот флаг не нужен.

Версии до single-active state invariant могли оставить несколько repositories в running, если агент вызвал next/start до finish. После обновления один раз восстанови только такие прерванные записи:

cd /path/to/projects/uvz-local-library-mcp
./skills/project-context-authoring/scripts/run-all-project-contexts.sh \
  "/path/to/projects" \
  --reset-interrupted-failures

Controller сначала переводит stale running в interrupted failed, затем возвращает только их в pending. Успешные repositories и failures с другими причинами не меняются. Новая версия запрещает второй running технически.

Точечное исправление после неуспешной индексации

Не перезапускай authoring для всей workspace. Построй точную очередь из coverage-проблем и failed generated retrieval cases:

cd /path/to/projects/uvz-local-library-mcp
python3 scripts/plan-project-context-repair.py \
  --audit audit-failure.local.json \
  --evaluation evaluation-failure.local.json \
  --output project-context-repair.local.txt

Запусти отдельную resumable repair-кампанию только для этого списка:

PROJECT_CONTEXT_STATE_FILE="$PWD/.project-context-authoring-repair.local.json" \
PROJECT_CONTEXT_REVIEW_FILE="$PWD/.project-context-authoring-repair-review.local.json" \
PROJECT_CONTEXT_OUTPUT_FORMAT=text \
  ./skills/project-context-authoring/scripts/run-all-project-contexts.sh \
  "/path/to/projects" \
  --include-file "$PWD/project-context-repair.local.txt"

Повторный запуск той же команды продолжает очередь. Каждая попытка получает coverage-aware validator feedback: точные missing/invalid Gradle module paths и usage-файлы, которые не находятся по собственному examples.summary.

Одна GigaCode API-сессия может завершиться по серверному лимиту времени. Runner автоматически открывает следующую изолированную сессию с тем же state-файлом и продолжает очередь. Безопасная остановка происходит после двух сессий без прогресса либо после 50 сессий; оба лимита можно изменить через PROJECT_CONTEXT_MAX_EMPTY_SESSIONS и PROJECT_CONTEXT_MAX_SESSIONS. Сразу после обработки repository state-watcher печатает компактную строку [готово/всего] SUCCESS <repository> — <cards>; <modules>; повторные попытки и terminal failures также появляются немедленно.

Если raw live JSON слишком шумный, переключи вывод на обычный текст:

cd /path/to/projects/uvz-local-library-mcp
PROJECT_CONTEXT_OUTPUT_FORMAT=text \
  ./skills/project-context-authoring/scripts/run-all-project-contexts.sh \
  "/path/to/projects"

В text-режиме GigaCode печатает полный ответ только после завершения сессии. Runner раз в 30 секунд выводит heartbeat с прошедшим временем, чтобы длительная обработка большого repository не выглядела зависшей. Интервал можно изменить через PROJECT_CONTEXT_HEARTBEAT_SECONDS.

Один repository можно обработать отдельно. В этом точечном режиме прежняя строгая проверка не разрешает посторонние dirty-изменения:

./skills/project-context-authoring/scripts/run-project-context.sh \
  "/path/to/one-project"

Проверка одного repository без индексации

python3 validate_project_contexts.py /path/to/project

Проверяются schema, русский текст, типы полей, структура suite, обязательные разделы usage, lexical overlap с examples.summary и существование всех относительных evidence paths. Каждый Gradle-модуль должен иметь карточку, быть осмысленно включён в modules другой карточки либо иметь no_context_required с русской причиной и evidence. Module IDs сверяются с полными путями deterministic Gradle discovery.

Перед индексацией просмотри изменения и закоммить карточки в их repositories. Verified-сборка по умолчанию принимает только чистые working trees и отдельно доказывает, что каждая карточка и usage входят в HEAD.

git status --short
git diff -- .

3. Повторная и полная переиндексация

После подготовки карточек повтори maintainer-команду:

cd /path/to/projects/uvz-local-library-mcp

./install.sh \
  --workspace "/path/to/projects" \
  --sync \
  --configuration-root "/path/to/projects/uvz-config"

Успешная сборка создаёт:

• knowledge.db;

• audit-summary.json;

• evaluation-summary.json;

• evaluation-cases.built.json;

• coverage-policy.built.yaml;

• skills/library-knowledge-workflow/generated-catalog.md.

Если хотя бы одна карточка невалидна или quality gate не пройден, предыдущая рабочая база не заменяется.

Обычная сборка выводит только три этапа, heartbeat раз в минуту и краткий итог. Последняя строка самой индексации всегда однозначна: INDEX BUILD SUCCEEDED или INDEX BUILD FAILED. Большие audit/evaluation JSON в терминал не печатаются. При падении quality gate краткие причины остаются в терминале, а полный отчёт сохраняется в ignored-файл evaluation-failure.local.json. Подробности ingestion и списки проблемных repository/module сохраняются в audit-failure.local.json; успешная следующая сборка удаляет оба устаревших failure report.

Повторный запуск по умолчанию инкрементальный. Индексатор использует предыдущую БД как read-only cache только после проверки её schema, SHA-256, audit, успешного evaluation и publishable provenance. Для clean repository с тем же commit, ролью configuration root и версией indexer contract переиспользуются тяжёлые chunks и YAML values. Изменённый repository пересобирается целиком.

Cross-repository metadata всегда строится заново, даже для переиспользованного source: project-context.yaml, usage paths, uvz-platform aliases, Gradle consumers, ownership и coverage. Поэтому изменение только uvz-platform обновляет dependency graph без повторного чтения всех исходников. Dirty source никогда не берётся из verified cache. Повреждённый, устаревший или неполный cache автоматически отбрасывается; сборка продолжает работу холодным способом. Indexer contract учитывает отдельные lexical_normalization.py и configuration_index.py, которые формируют индексные terms и YAML metadata. Runtime-only изменения lexical_search.py и configuration_model.py, включая query expansions, ranking и resolve_config, не обнуляют cache неизменённых repositories.

Сведения reused/rebuilt по каждому repository не засоряют терминал и видны в audit-summary.json → incremental и source_revisions[].cache_status. Время стадий и каждого repository сохраняется отдельно в ignored build-performance.local.json; этот недетерминированный файл не попадает в pack. Он нужен, чтобы решать вопрос о file-level cache по замерам полного workspace, а не по размеру репозиториев. Игнорируемые Git-файлы не индексируются. Для диагностики или после изменения правил индексирования можно явно запретить reuse:

./install.sh \
  --workspace "/path/to/projects" \
  --sync \
  --full-rebuild \
  --configuration-root "/path/to/projects/uvz-config"

Переход с schema version 5 на version 6 всегда делает первый запуск холодным: предыдущая БД автоматически отклоняется как несовместимая. Следующий запуск при тех же commits уже использует incremental cache.

audit-summary.json → context_coverage показывает покрытые, объяснимо исключённые и missing Gradle-модули по каждому repository. Не-Gradle repositories (например jimmer-doc) индексируются, но не входят в denominator. Порог задаётся как thresholds.min_context_coverage в evaluation definition; по умолчанию требуется не менее 0.8. Invalid module claims и broken components всегда блокируют сборку независимо от процента.

Внешние исходники и наборы примеров могут оставаться в поисковом индексе, не притворяясь внутренними компонентами. Для них используется строгий coverage-policy.yaml: точное имя repository, роль reference, русская причина и committed evidence в одном из индексируемых repositories. Wildcard запрещён; отсутствующий, неиндексируемый или незакоммиченный evidence останавливает сборку. Преднастроенные правила покрывают jimmer и jimmer-examples. Для внутренней reference-базы можно передать отдельный файл через --coverage-policy /path/to/coverage-policy.yaml.

evaluation-cases.built.json создаётся автоматически на каждой сборке: ручные cases сохраняются, затем добавляется один positive case на каждую project-context.yaml и каждый объявленный docs/usage/*.md. Этот built-файл, а не исходный шаблон, проверяется и попадает в knowledge pack.

Если рядом с install.sh существует reviewed evaluation-cases.local.json, установщик автоматически использует его вместо базового definition. Явный --evaluation-cases /path/to/cases.json имеет приоритет. Это не позволяет случайно пропустить подготовленные dependency/configuration cases.

После первой сборки schema version 6 создай и вручную проверь три реальные dependency graph cases, затем повтори сборку с локальным definition:

python3 scripts/draft-dependency-cases.py --limit 3

./install.sh \
  --workspace "/path/to/projects" \
  --sync \
  --configuration-root "/path/to/projects/uvz-config" \
  --evaluation-cases evaluation-cases.local.json

По умолчанию генератор выбирает только aliases внутренних библиотек, для которых нашёл владельца в индексируемом workspace. Внешние Spring-зависимости и драйверы не используются как эталонные cases. Генератор не перезаписывает evaluation-cases.local.json; подробный review-flow описан в retrieval evaluation. После проверки каждого consumer поставь dependency_case_draft.review_required: false, иначе quality gate намеренно не пройдёт.

Проверка готовых ответов агента

После успешной сборки можно проверить уже не только retrieval engine, но и реальные финальные ответы GigaCode. Публичные Jimmer cases запускаются так:

python3 scripts/run-agent-evaluation.py \
  --cases agent-evaluation-cases.json \
  --output agent-answers.local.json

python3 scripts/evaluate-agent-answers.py \
  --db knowledge.db \
  --cases agent-evaluation-cases.json \
  --answers agent-answers.local.json

Для полного рабочего индекса сначала создай внутренний draft из проверенных context cards, связанных docs/usage golden paths, dependency graph и Spring configuration:

python3 scripts/draft-agent-evaluation-cases.py \
  --db knowledge.db \
  --base agent-evaluation-cases.json \
  --output agent-evaluation-cases.local.json

По умолчанию выбираются по три cases каждой внутренней категории с приоритетом разных repositories. Usage cases требуют точный source/commit и реальные API/alias/config identifiers из golden path. Configuration cases проверяют не сырой YAML, а effective value после resolve_config с module/configuration set/profiles, source provenance и resolution_complete. Итоговый evaluator отдельно показывает category-level pass rate, поэтому успех на Jimmer-документации не маскирует ошибки использования/подключения внутренних библиотек или разрешения конфигурации.

Просмотри все добавленные cases и поставь agent_case_draft.review_required: false. До явного review runner и evaluator откажутся использовать draft.

Если project-context.yaml или docs/usage были созданы или исправлены после последней сборки, сначала закончи authoring, затем пересобери knowledge.db и только после этого создавай новый draft. Draft хранит SHA-256 базы, поэтому его нельзя использовать с другой индексацией. Во время уже запущенного benchmark не обновляй проект, базу или установленный workflow skill.

Runner создаёт отдельную пустую временную workspace на каждый вопрос, исключает shell/subagent/web search и оставляет в MCP allowlist только read-only tools local-library-mcp. До первой сессии он проверяет schema cases и всё ожидаемое indexed evidence против установленной knowledge.db; stale case не расходует время модели. Evaluator сверяет cited sources/commits, libs aliases и consumer edges с SQLite, требует явный отказ для неподтверждённого API и запрещает прямые versioned Gradle dependencies. Answers version 2 привязаны к точным SHA-256 базы, MCP runtime, workflow skill, runner, cases, модели и версии GigaCode; readiness_check.py не принимает legacy-ответы без этой привязки. Evaluator дополнительно группирует failures по category, стабильной причине и области (context, usage, dependencies, configuration, provenance или agent execution), чтобы следующий цикл улучшений опирался на измеримые провалы. После прерывания повтори runner с --resume: он пропустит только успешные cases при неизменных cases/model/GigaCode/runner/knowledge.db/runtime/skill. Без --resume существующий output никогда не перезаписывается. Технический agent_error или пустой ответ автоматически повторяется один раз; настройка --max-case-attempts N меняет общее число сессий на case в одном запуске. Во время каждого case runner раз в 30 секунд печатает heartbeat, а после него — status и длительность; интервал настраивается через --heartbeat N.

Два summary сравниваются по fingerprint неизменившихся case definitions:

python3 scripts/compare-agent-evaluations.py \
  --baseline agent-evaluation-summary.before.local.json \
  --candidate agent-evaluation-summary.after.local.json \
  --fail-on-regression

Comparator отдельно показывает улучшенные, регрессировавшие и изменённые cases, category deltas и изменение failure codes. Подробности — в agent answer evaluation. Для внутренних вопросов используй ignored agent-evaluation-cases.local.json. Полный формат и review-flow описаны в agent answer evaluation.

Исключение repositories

Скопируй шаблон и укажи точные имена директорий, по одному на строку:

cp index-exclude.example.txt index-exclude.txt

Пример:

old-project
experimental-service

index-exclude.txt не коммитится и автоматически применяется при индексации.

Обновление исходников

Обычный --sync безопасен: dirty repositories и ветки с локальными commits он не обновляет через Git, а причину записывает в audit. Verified-сборка теперь останавливается на любом dirty repository, чтобы path и commit не противоречили друг другу.

Для временной локальной проверки можно явно разрешить стабильный dirty working tree:

./install.sh \
  --workspace "/path/to/projects" \
  --allow-dirty \
  --configuration-root "/path/to/projects/uvz-config"

Такой индекс получает provenance dirty_allowed и работает через MCP, но package_pack.py гарантированно откажется его упаковывать. Перед публикацией закоммить/stash изменения и повтори обычную сборку без флага.

Clean source без sanitised origin URL или с commit, отсутствующим в origin/*, также пригоден для локального MCP, но имеет publishable: false. Перед упаковкой каждый индексируемый SHA должен быть опубликован во внутреннем Git и виден в актуальных remote-tracking refs.

Принудительное обновление всех repositories выполняется отдельно:

./scripts/force-sync-all.sh /path/to/projects
./scripts/force-sync-all.sh /path/to/projects --apply

Первая команда — dry run. Вторая переключает каждый repository на origin/master или origin/main и удаляет локальные tracked-изменения. Она ничего не push-ит и не удаляет untracked-файлы.

4. Создание knowledge pack

После успешной индексации:

python3 package_pack.py --version YYYY.MM.DD

Результат:

dist/knowledge-pack-YYYY.MM.DD.zip

Pack содержит SQLite, catalog, manifest, audit, evaluation, точный набор retrieval cases и exact coverage policy. Упаковка блокируется, если их hashes не согласованы, любой retrieval/dependency/configuration/coverage gate не пройден, хотя бы один source был dirty или curated-файл не подтверждён указанным commit. Version допускает только portable имя без path separators; одинаковые проверенные inputs и version дают побайтно одинаковый knowledge pack.

Локальный индекс, собранный с --allow-dirty, не считается publishable. Для внутренней проверки его можно упаковать только с явным experimental-флагом:

python3 package_pack.py \
  --version YYYY.MM.DD-experimental \
  --allow-experimental-provenance

python3 package_distribution.py \
  --pack dist/knowledge-pack-YYYY.MM.DD-experimental.zip \
  --allow-experimental-provenance

Experimental-статус записывается в оба manifest. Обычная упаковка, проверка и установка продолжают его отклонять. Получатель должен явно выполнить ./install.sh --allow-experimental-provenance; это не превращает dirty evidence в publishable и не скрывает provenance.

Для внутреннего trusted release один раз создай RSA-ключ вне repository и закоммить только public key:

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 \
  -aes-256-cbc -out /secure/path/uvz-rag-signing-private.pem
openssl rsa -in /secure/path/uvz-rag-signing-private.pem \
  -pubout -out trusted-pack-key.pem
git add trusted-pack-key.pem

Приватный ключ никогда не клади в проект. Сборщик developer distribution дополнительно блокирует любой tracked PEM private key. Перед подписанием передай пароль ключа через переменную окружения, не через аргумент командной строки:

read -r -s PACK_SIGNING_KEY_PASSPHRASE
export PACK_SIGNING_KEY_PASSPHRASE

python3 package_pack.py \
  --version YYYY.MM.DD \
  --signing-key /secure/path/uvz-rag-signing-private.pem \
  --signing-key-pass-env PACK_SIGNING_KEY_PASSPHRASE

Signed pack содержит RSA/SHA-256 подпись точных байтов manifest. Public key не берётся из pack: доверенным считается только tracked trusted-pack-key.pem из внутреннего repository. Поэтому подмена одновременно manifest и checksums обнаруживается.

Для обновления уже установленной большой базы можно собрать exact page delta между двумя approved packs:

python3 package_delta.py \
  --base-pack dist/knowledge-pack-YYYY.MM.DD.zip \
  --target-pack dist/knowledge-pack-YYYY.MM.DD-next.zip \
  --output dist

Packager переиспользует совпадающие SQLite pages и сохраняет только изменённые. Если delta не меньше полного target pack, команда завершается ошибкой — в этом случае распространяй обычный pack. Для signed packs передаются те же --trusted-public-key, --require-signature и --openssl.

Для передачи коллегам одним готовым архивом сначала закоммить изменения самого MCP-проекта, затем собери developer distribution:

python3 package_distribution.py \
  --pack dist/knowledge-pack-YYYY.MM.DD.zip

Результат:

dist/uvz-local-library-mcp-YYYY.MM.DD.zip

Сборщик берёт только чистые Git-tracked файлы этого проекта и ровно один проверенный knowledge pack. Локальные БД, campaign state, .gigacode, исходные repositories и другие untracked/ignored файлы в архив не попадают. Knowledge pack и внешний ZIP детерминированы: повторная сборка из тех же verified inputs, version и project commit даёт те же байты. Внутри лежит distribution-manifest.json с SHA-256 каждого файла.

Tracked generated-файлы, которыми управляет pack (audit-summary.json, catalog, evaluation, coverage policy и knowledge.db), не считаются runtime-изменениями и не дублируются во внешнем ZIP: installer атомарно извлекает их из вложенного knowledge pack. Изменённые tracked runtime-файлы по-прежнему блокируют сборку.

Внутренний индекс содержит производные от исходников данные. Публикуй pack только во внутренний Bitbucket/artifact storage. Не добавляй внутренний pack в публичный GitHub repository.

Рекомендуемый способ распространения — developer distribution из предыдущего шага либо versioned knowledge pack в dist/ этого проекта во внутреннем Bitbucket. В обоих вариантах разработчик получает один проект.

5. Установка у разработчика

При передаче developer distribution:

unzip uvz-local-library-mcp-YYYY.MM.DD.zip
cd uvz-local-library-mcp
./install.sh

Альтернатива — внутренний repository уже содержит dist/knowledge-pack-<version>.zip:

git clone <internal-bitbucket>/uvz-local-library-mcp.git
cd uvz-local-library-mcp
./install.sh

Installer автоматически:

1. проверяет distribution manifest, если установка идёт из готового архива;

2. выбирает самый новый bundled pack;

3. для signed pack проверяет RSA/SHA-256 по tracked trusted-pack-key.pem, затем schema, размеры, SHA-256, все quality gates и publishable provenance;

4. атомарно устанавливает SQLite и отчёты;

5. добавляет local-library-mcp в GigaCode settings;

6. устанавливает основной library-knowledge-workflow skill;

7. запускает настоящий stdio MCP smoke test, включая explain_search.

После установки перезапусти GigaCode и проверь /mcp.

При прямой установке signed pack вне developer distribution явно передай ключ:

./install.sh \
  --knowledge-pack /path/to/knowledge-pack-YYYY.MM.DD.zip \
  --trusted-pack-key /path/to/trusted-pack-key.pem \
  --require-pack-signature

Разработчик с точной base-версией может установить меньший delta-архив:

./install.sh \
  --knowledge-delta /path/to/knowledge-delta-OLD--NEW.zip \
  --trusted-pack-key /path/to/trusted-pack-key.pem \
  --require-pack-signature

Delta не применяется «примерно к такой же» базе: проверяется SHA-256 каждого байта base knowledge.db. Installer восстанавливает exact target DB во временной директории, повторно проверяет target signature, hashes, schema и все quality/provenance gates и только затем заменяет metadata и SQLite. Для первой установки по-прежнему нужен полный developer distribution или knowledge pack.

Проверочный промт:

Используя local-library-mcp, найди пример Jimmer Fetcher. Назови repository,
source id, path, commit и кратко объясни, что делает пример. Не отвечай без
ссылки на источник из локальной базы.

Developer не запускает индексацию и не устанавливает authoring skill.

MCP-инструменты

Основные поисковые, source, usage, dependency и configuration-инструменты возвращают source_url, когда Git remote распознан как GitHub или Bitbucket Server. Ссылка всегда привязана к commit из индекса; локальные абсолютные пути в неё не попадают. Для неизвестного Git host MCP не угадывает URL и оставляет только source id, repository-relative path, commit и provenance.

В project-context.yaml не смешиваются внутренние projects.* accessors и внешние libs.* aliases. Первые корректно связывают подмодули одного Gradle build; вторые описывают подключение библиотеки из другого repository через version catalog uvz-platform.

Проверка проекта MCP

python3 -m unittest discover -s tests -v
python3 smoke_test.py

После сборки или установки запусти единый operational readiness check:

python3 readiness_check.py

Он повторно связывает knowledge.db с audit/evaluation/cases/policy, проверяет schema и quality gates, считает repositories/chunks/aliases/usages/configuration, а затем запускает настоящий stdio MCP. Для проверки эффективности рабочего release добавь отчёт grounded-answer benchmark; readiness свяжет его с точной БД и покажет model/GigaCode identity:

python3 readiness_check.py \
  --agent-evaluation agent-evaluation-summary.local.json \
  --require-agent-evaluation

Для maintainer-проверки полного roadmap добавь завершённую authoring campaign и её свежий агрегированный review:

python3 readiness_check.py \
  --campaign-state .project-context-authoring-campaign.json \
  --campaign-review .project-context-authoring-review.json \
  --require-campaign \
  --agent-evaluation agent-evaluation-summary.local.json \
  --require-agent-evaluation

Campaign gate требует, чтобы каждый repository имел итоговый статус, не было failed/pending/running, а каждый discovered module был покрыт карточкой либо доказанным no_context_required. Изменённый или устаревший review отвергается.

В распакованном developer bundle можно также потребовать целостность внешнего distribution manifest:

python3 readiness_check.py --require-distribution

Exit code 0 и первая строка READY означают, что выбранный набор проверок пройден. --json и --output /path/to/readiness.json дают машиночитаемый отчёт без внутренних данных в публичном repository.

Дополнительная документация

• План развития

• Dependency usage graph

• Retrieval и dependency graph evaluation

• Модель project context

• Quality gate

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

• Knowledge packs

• Retrieval evaluation

• Agent answer evaluation

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

• Синхронизация исходников