{
  "markdown": "# LINZA - локальный MCP-сервер для агентской работы с папками знаний\n\n> *Не меняет данные. Меняет взгляд.*\n\nLINZA работает с Obsidian vault, Markdown-папками, документами, статьями, логами и черновиками. Она нужна, когда материалов уже слишком много и вы хотите разобрать базу, выделить в ней основные области и научить агента хорошо ориентироваться в ней.\n\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)\n[![MCP](https://img.shields.io/badge/protocol-MCP_stdio-lightgrey.svg)](https://modelcontextprotocol.io)\n![Local first](https://img.shields.io/badge/storage-local--first-green.svg)\n![Review gated](https://img.shields.io/badge/writes-review--gated-orange.svg)\n\n[English version](README_EN.md)\n\nLINZA читает выбранную папку, строит рядом локальную SQLite-базу `.linza/linza.db` и дает агенту рабочую карту: какие темы есть в материалах, какие форматы повторяются, какие заметки могут быть связаны, где видны цепочки причина/следствие и что может пригодиться в будущих сессиях.\n\nИсходные файлы остаются нетронутыми. LINZA не переписывает заметки при индексации, не превращает сырой лог в правило и не учит агента за вашей спиной. Она превращает гипотезы в короткие предложения: возможные действия с доказательствами. Пользователь решает, агент выполняет.\n\n```text\ndoctor -> index -> map -> review intents -> teach -> grow preview -> explicit apply\n```\n\n---\n\n## Зачем нужна LINZA\n\n\nLINZA собирает несколько конкретных вещей, которые помогают агентам работать с базой:\n\n1. **Карта папки**\n   Сколько заметок найдено, свежий ли индекс, какие области видны и какие материалы ждут вашего ревью.\n\n2. **Области**\n   Крупные смысловые группы. Их названия остаются черновиками, пока вы не примете или не переименуете их.\n\n3. **Форматы материалов**\n   Логи, черновики, спецификации, исследовательские заметки, кейсы, правила и другие повторяющиеся формы, найденные в папке.\n\n4. **Связи**\n   Возможные соседства, иерархия, причина/следствие и маршруты между узлами. LINZA должна показывать не только как связаны документы, но и почему.\n\n5. **Память для будущих агентов**\n   Короткие кандидаты: что помнить, когда вспоминать, что устарело или выглядит сомнительно.\n\n6. **Пакеты контекста**\n   Компактные подборки для агента: выбранный контекст с источниками, связями и границами.\n\n---\n\n## Форматы материалов\n\n“Формат материала” - это пользовательское имя для повторяющейся формы заметок. Например: `лог диагностики`, `решение`, `черновик статьи`, `исследовательская заметка`, `спецификация`.\n\nLINZA сначала видит только структуру: длину, заголовки, списки, ссылки, таблицы, папки, повторяющиеся признаки. Поэтому первый результат может называться нейтрально: `type-001`. Пользователь может сказать: “это логи”. Тогда LINZA сохраняет соответствие `type-001 -> логи` в `.linza`.\n\nВнутри API остаются старые совместимые ключи `material_type`, `type_name` и `role`. Снаружи документация и пользовательский вид говорят “формат”, потому что это ближе к тому, как пользователь реально думает о материалах.\n\nВажная граница:\n\n- принять название формата значит записать решение в `.linza`;\n- записать `role: логи` в YAML можно только отдельным предложением на ревью;\n- текст заметки не меняется.\n\n---\n\n## Как выглядит ревью\n\nLINZA присылает примерно такую информацию:\n\n```text\nLINZA готова\n\nМатериал:\n- 42 заметки проиндексированы\n- 3 входящих артефакта ждут ревью\n- служебная база: .linza/linza.db\n\nСледующий шаг:\n1. Посмотреть найденные области\n2. Принять, переименовать или пропустить 3-5 предложений\n3. Ничего не будет записано без dry-run/apply\n\nПредложение:\nПринять формат материала \"логи диагностики\" по 8 примерам\nПочему: похожая структура, повторяющиеся заголовки, близкие чанки\nЧто изменится: название формата сохранится в .linza; Markdown-заметки не меняются\n```\n\nВнутри каждый интент остается структурой с ID, доказательствами и готовыми данными для проверки и последующего подтверждения и записи. Вам LINZA возвращает готовое пользовательское представление, чтобы агент мог показать понятный ответ вместо JSON.\n\nХороший интент всегда отвечает на главный вопрос: **почему LINZA так думает?** В нем должны быть источники, чанки, тип связи, уверенность и честное описание того, что изменится после применения.\n\n---\n\n## Обучение и рост\n\nМодель автономности такая:\n\n1. `review_next` показывает предложения в понятном пользовательском виде.\n2. Пользователь принимает, переименовывает или пропускает.\n3. `apply_review_items` сначала делает dry-run.\n4. После подтверждения выбранный интент записывается в `.linza` или в компактный YAML, если этот тип записи это поддерживает.\n5. `teach` выбирает хорошие принятые примеры.\n6. `grow` предлагает похожие интенты по этим примерам и объясняет `selected_rules`, почему они попали в партию.\n\nЕсли вы приняли не то, одобрение можно мягко отозвать:\n\n```text\nagent_workspace(action=\"history\")\nagent_workspace(action=\"revoke_approval\", approval_id=17, dry_run=false)\n```\n\nLINZA не удаляет старую запись и не пытается автоматически откатить YAML. Она помечает одобрение как отозванное, перестает использовать его как активный пример и оставляет след в истории.\n\n---\n\n## Установка\n\n### 1. Установить пакет\n\n```powershell\npython -m pip install linza-mcp\n```\n\nЕсли нужно читать PDF прямо через LINZA:\n\n```powershell\npython -m pip install \"linza-mcp[pdf]\"\n```\n\nОбычная установка уже достаточна для Markdown, TXT, JSON, DOCX и XLSX. `[pdf]` добавляет локальный PDF-экстрактор `pypdf`.\n\n### 2. Выбрать папку\n\nLINZA работает с любой Markdown-папкой: Obsidian vault, рабочей папкой проекта или отдельной папкой с документами.\n\nВ примерах ниже замените `/absolute/path/to/workspace-or-vault` на свой путь.\n\n### 3. Подключить MCP-клиент\n\nClaude Desktop, Cursor, OpenCode и другие MCP-клиенты обычно используют такой формат:\n\n```json\n{\n  \"mcpServers\": {\n    \"linza\": {\n      \"command\": \"linza-mcp\",\n      \"env\": {\n        \"LINZA_VAULT\": \"/absolute/path/to/workspace-or-vault\"\n      }\n    }\n  }\n}\n```\n\nVS Code / Copilot MCP использует ключ `servers`:\n\n```json\n{\n  \"servers\": {\n    \"linza\": {\n      \"type\": \"stdio\",\n      \"command\": \"linza-mcp\",\n      \"env\": {\n        \"LINZA_VAULT\": \"/absolute/path/to/workspace-or-vault\"\n      }\n    }\n  }\n}\n```\n\n`LINZA_VAULT` не обязателен для старта: без него сервер использует `./vault`. Но для реальной работы лучше задать явную папку.\n\n### 4. Проверить запуск\n\n```powershell\nlinza-mcp --version\n```\n\nПосле подключения попросите агента:\n\n```text\nПроверь LINZA через agent_workspace(action=\"doctor\").\nПроиндексируй папку и покажи первые 3-5 предложений.\n```\n\n---\n\n## Эмбеддинги\n\nLINZA может запуститься и показать инструменты без embedding-сервера. Эмбеддинги нужны для смыслового поиска, карты тем и предложений связей.\n\nСамый простой локальный путь - LM Studio:\n\n1. Открыть LM Studio.\n2. Скачать embedding-модель, например `text-embedding-granite-embedding-278m-multilingual`, `nomic-embed-text-v1.5` или другую подходящую модель.\n3. Запустить Local Server.\n4. Проверить, что endpoint доступен на `http://127.0.0.1:1234/v1`.\n\nПример переменных для LM Studio:\n\n```powershell\n$env:LINZA_EMBED_PROVIDER=\"lmstudio\"\n$env:LINZA_EMBED_URL=\"http://127.0.0.1:1234/v1\"\n$env:LINZA_EMBED_MODEL=\"your-embedding-model-name\"\n```\n\nПоддерживаются:\n\n- `lmstudio` - рекомендуемый локальный режим;\n- `ollama` - локальный вариант через Ollama;\n- `openai` - любой OpenAI-compatible endpoint с `/embeddings`.\n\nЕсли меняете провайдер, модель или размерность, сделайте полный реиндекс. LINZA проверяет embedding signature и останавливает graph/search workflows, если sidecar устарел или содержит смешанные векторные пространства.\n\n---\n\n## Основные MCP-инструменты\n\nПо умолчанию LINZA показывает только 7 MCP-инструментов. Этого хватает для обычной работы: проверить состояние, проиндексировать папку, искать, читать файл, смотреть счетчики, диагностировать vault и вести агента через `agent_workspace`.\n\n| Инструмент | Зачем |\n| --- | --- |\n| `agent_workspace` | Единый вход для диагностики, карты, импорта, ревью, обучения, роста, связей, памяти и экспорта контекста |\n| `guide_next_steps` | Показать следующий безопасный шаг простым языком |\n| `index_all` | Проиндексировать Markdown-папку в `.linza/linza.db` |\n| `search` | Семантический и лексический поиск |\n| `read_file` | Прочитать точный Markdown-файл |\n| `get_stats` | Быстрые счетчики служебной базы |\n| `scan_vault` | Диагностика папки без записи |\n\nНизкоуровневые инструменты считаются деталями реализации и доступны через `agent_workspace`, поэтому набор из 7 инструментов - это полноценный режим.\n\n### Режимы `agent_workspace`\n\n| Action | Режим |\n| --- | --- |\n| `doctor` | Проверить готовность LINZA и показать, чего не хватает |\n| `map` | Собрать карту рабочей папки без записи |\n| `teach` | Выбрать сильные принятые примеры для обучения |\n| `grow` | Показать или применить рост по принятым примерам; по умолчанию dry-run |\n| `review_next` | Показать следующие предложения на ревью; интенты базы имеют ID `rq-*`, интенты артефактов и рабочей папки - `aw-*` |\n| `apply_review_items` | Показать или применить точные выбранные ID; по умолчанию dry-run |\n| `history` | Показать принятые и отозванные одобрения |\n| `revoke_approval` | Мягко отозвать одобрение, не удаляя историю |\n| `ingest_artifacts` | Сохранить вставленный или извлеченный материал в sidecar |\n| `analyze_inbox` | Найти события, кандидаты памяти и фрагменты знания в артефактах |\n| `connect` | Объяснить возможную связь между двумя заметками или узлами |\n| `search_memory` | Искать по подтвержденной памяти и контексту артефактов |\n| `export_context` | Собрать компактный пакет контекста для другого агента |\n| `record_trace` | Сохранить структурированные следы работы агента, не raw chain-of-thought |\n| `analyze_trace` | Разобрать сохраненный trace для ревью |\n| `review_calibr` | Проверить уроки калибровки, полученные из traces |\n\nДля разработки и аудита остается отдельный низкоуровневый режим. Полное описание инструментов: [Tool Catalog](LINZA_TOOL_CATALOG.md).\n\n---\n\n## Входящие артефакты\n\nLINZA умеет принимать материал, который еще не стал заметкой:\n\n- вставленный текст;\n- локальные `.md`, `.txt`, `.json`;\n- локальные `.docx`, `.xlsx`;\n- локальные `.pdf`, если установлен `pypdf` или `PyPDF2`.\n\nLINZA сама не ходит в браузер. Агент использует свой браузер, web-fetch или connector, извлекает читаемый текст и передает его в LINZA как артефакт, например `source_kind=\"web_article\"` или `source_kind=\"browser_capture\"`.\n\nИмпортированный текст считается материалом для анализа, не инструкцией для агента. Это граница prompt injection: инструкции внутри статьи, лога, чата или PDF не исполняются. Память, правила и YAML появляются только после ревью.\n\n---\n\n## Модель безопасности\n\nLINZA - локальный review-gated sidecar.\n\n| Действие | Куда пишет | Меняет текст заметок? |\n| --- | --- | --- |\n| Индексация, анализ, поиск | `.linza/linza.db` | Нет |\n| Сырые артефакты | `.linza/linza.db` | Нет |\n| Название формата материала | `.linza/linza.db` | Нет |\n| `domains` или `role` в YAML | Только компактный YAML после ревью | Нет |\n| Иерархия, причинные связи, память, уроки калибровки | `.linza/linza.db` | Нет |\n| Отчеты | `.linza/reports` | Нет |\n| Пакеты контекста | `.linza/context-packs` | Нет |\n| `write_file` | Markdown-файл только при явном запросе | Может создать/заменить файл, dry-run по умолчанию |\n\nДополнительные правила:\n\n- `review_next` ничего не пишет;\n- `apply_review_items` по умолчанию dry-run;\n- видимые YAML-правки компактные и требуют точного выбранного ID;\n- `history` показывает, что было принято и что отозвано;\n- `revoke_approval` мягко отзывает одобрение: история остается, но активное обучение и помощники графа его игнорируют;\n- `map`, `teach`, `grow` и `connect` останавливаются, если исходные файлы изменились после индексации.\n\n\n---\n\n## Инструкции для агентов\n\nВ репозитории есть переносимый операторский skill:\n\n```text\nagent-pack/skills/linza-operator/SKILL.md\nagent-pack/skills/linza-operator/references/workflows.md\nagent-pack/skills/linza-operator/references/safety-policy.md\nagent-pack/skills/linza-operator/references/tool-audience.md\n```\n\nОн объясняет агенту, как начинать с `doctor`, когда показывать предложения на ревью, как работать со страницами через внешний browser/web-fetch инструмент и почему apply actions должны идти сначала через dry-run и только по точным ID.\n\n---\n\n## Стабильность\n\nLINZA пока alpha. Основной контракт безопасности должен оставаться стабильным: индексация, импорт артефактов, поиск, карта и grow preview не переписывают тела исходных заметок. Низкоуровневые advanced-инструменты и внутренние границы кода еще могут меняться, пока сервер полируется.\n\n---\n\n## Проверка\n\nЗапустить полный набор тестов:\n\n```powershell\npython -m unittest discover -s tests\n```\n\n---\n\n## Переменные окружения\n\n| Переменная | Нужна для старта? | Описание |\n|---|---:|---|\n| `LINZA_VAULT` | Нет | Путь к Markdown-папке; по умолчанию `./vault` |\n| `LINZA_EMBED_PROVIDER` | Нет | `lmstudio` для рекомендуемого локального режима; также `openai` и `ollama` |\n| `LINZA_EMBED_URL` | Нет | URL embeddings API; по умолчанию `http://127.0.0.1:1234/v1` |\n| `LINZA_EMBED_MODEL` | Нет | Модель эмбеддингов; задайте перед semantic indexing/search |\n| `LINZA_EMBED_KEY` | Нет | Опциональный ключ для OpenAI-compatible embeddings API |\n| `LINZA_BRIDGE_THRESHOLD` | Нет | Порог semantic bridge; по умолчанию `0.55` |\n| `LINZA_MAX_BRIDGE_PAIRS` | Нет | Максимум пар заметок для пересчета semantic bridges; по умолчанию `1000000`, `0` отключает guard |\n| `LINZA_DEFAULT_PROFILE` | Нет | Имя базового search-профиля; по умолчанию `general` |\n| `LINZA_LANGUAGE` | Нет | Язык подсказок и маршрута ревью в `guide_next_steps`: `auto`, `ru`, `en` |\n\n---\n\n## Ссылки\n\n- [semiotronika.ru](https://semiotronika.ru)\n- [PyPI](https://pypi.org/project/linza-mcp/)\n- [GitHub](https://github.com/Semiotronika/LINZA-MCP)\n\n\nMIT License (c) 2026 Semiotronika\n\n*Косинусы считаются. Синтаксис меняется. Семантика остается.*\n\n<!-- mcp-name: io.github.Semiotronika/LINZA-MCP -->\n",
  "bytes": 13986,
  "sha": "6deda3fb6b9664dca3a2b1f0170ce4f91bd439d78f234de81b28837ed73f4c40",
  "repo_slug": "semiotronika/linza-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_semiotronika_linza_mcp_c0a82259/readme"
}