LINZA
Local-first MCP sidecar for Markdown artifacts, review intents, and supervised knowledge growth.
Open source Open in the app JSON README (API)
About
Local-first MCP sidecar for Markdown artifacts, review intents, and supervised knowledge growth.
Details
- Kind
- MCP servers
- Topic
- Files & documents
- Publisher
- semiotronika
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.2.2
- Stars
- 4
- Last push
- 2026-08-13T00:35:12Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 03:02:14
- Updated
- 2026-08-29 03:02:14
- Origin id
io.github.Semiotronika/LINZA-MCP
README
# LINZA - локальный MCP-сервер для агентской работы с папками знаний
> *Не меняет данные. Меняет взгляд.*
LINZA работает с Obsidian vault, Markdown-папками, документами, статьями, логами и черновиками. Она нужна, когда материалов уже слишком много и вы хотите разобрать базу, выделить в ней основные области и научить агента хорошо ориентироваться в ней.
[](https://python.org)
[](https://modelcontextprotocol.io)
[English version](README_EN.md)
LINZA читает выбранную папку, строит рядом локальную SQLite-базу `.linza/linza.db` и дает агенту рабочую карту: какие темы есть в материалах, какие форматы повторяются, какие заметки могут быть связаны, где видны цепочки причина/следствие и что может пригодиться в будущих сессиях.
Исходные файлы остаются нетронутыми. LINZA не переписывает заметки при индексации, не превращает сырой лог в правило и не учит агента за вашей спиной. Она превращает гипотезы в короткие предложения: возможные действия с доказательствами. Пользователь решает, агент выполняет.
```text
doctor -> index -> map -> review intents -> teach -> grow preview -> explicit apply
```
---
## Зачем нужна LINZA
LINZA собирает несколько конкретных вещей, которые помогают агентам работать с базой:
1. **Карта папки**
Сколько заметок найдено, свежий ли индекс, какие области видны и какие материалы ждут вашего ревью.
2. **Области**
Крупные смысловые группы. Их названия остаются черновиками, пока вы не примете или не переименуете их.
3. **Форматы материалов**
Логи, черновики, спецификации, исследовательские заметки, кейсы, правила и другие повторяющиеся формы, найденные в папке.
4. **Связи**
Возможные соседства, иерархия, причина/следствие и маршруты между узлами. LINZA должна показывать не только как связаны документы, но и почему.
5. **Память для будущих агентов**
Короткие кандидаты: что помнить, когда вспоминать, что устарело или выглядит сомнительно.
6. **Пакеты контекста**
Компактные подборки для агента: выбранный контекст с источниками, связями и границами.
---
## Форматы материалов
“Формат материала” - это пользовательское имя для повторяющейся формы заметок. Например: `лог диагностики`, `решение`, `черновик статьи`, `исследовательская заметка`, `спецификация`.
LINZA сначала видит только структуру: длину, заголовки, списки, ссылки, таблицы, папки, повторяющиеся признаки. Поэтому первый результат может называться нейтрально: `type-001`. Пользователь может сказать: “это логи”. Тогда LINZA сохраняет соответствие `type-001 -> логи` в `.linza`.
Внутри API остаются старые совместимые ключи `material_type`, `type_name` и `role`. Снаружи документация и пользовательский вид говорят “формат”, потому что это ближе к тому, как пользователь реально думает о материалах.
Важная граница:
- принять название формата значит записать решение в `.linza`;
- записать `role: логи` в YAML можно только отдельным предложением на ревью;
- текст заметки не меняется.
---
## Как выглядит ревью
LINZA присылает примерно такую информацию:
```text
LINZA готова
Материал:
- 42 заметки проиндексированы
- 3 входящих артефакта ждут ревью
- служебная база: .linza/linza.db
Следующий шаг:
1. Посмотреть найденные области
2. Принять, переименовать или пропустить 3-5 предложений
3. Ничего не будет записано без dry-run/apply
Предложение:
Принять формат материала "логи диагностики" по 8 примерам
Почему: похожая структура, повторяющиеся заголовки, близкие чанки
Что изменится: название формата сохранится в .linza; Markdown-заметки не меняются
```
Внутри каждый интент остается структурой с ID, доказательствами и готовыми данными для проверки и последующего подтверждения и записи. Вам LINZA возвращает готовое пользовательское представление, чтобы агент мог показать понятный ответ вместо JSON.
Хороший интент всегда отвечает на главный вопрос: **почему LINZA так думает?** В нем должны быть источники, чанки, тип связи, уверенность и честное описание того, что изменится после применения.
---
## Обучение и рост
Модель автономности такая:
1. `review_next` показывает предложения в понятном пользовательском виде.
2. Пользователь принимает, переименовывает или пропускает.
3. `apply_review_items` сначала делает dry-run.
4. После подтверждения выбранный интент записывается в `.linza` или в компактный YAML, если этот тип записи это поддерживает.
5. `teach` выбирает хорошие принятые примеры.
6. `grow` предлагает похожие интенты по этим примерам и объясняет `selected_rules`, почему они попали в партию.
Если вы приняли не то, одобрение можно мягко отозвать:
```text
agent_workspace(action="history")
agent_workspace(action="revoke_approval", approval_id=17, dry_run=false)
```
LINZA не удаляет старую запись и не пытается автоматически откатить YAML. Она помечает одобрение как отозванное, перестает использовать его как активный пример и оставляет след в истории.
---
## Установка
### 1. Установить пакет
```powershell
python -m pip install linza-mcp
```
Если нужно читать PDF прямо через LINZA:
```powershell
python -m pip install "linza-mcp[pdf]"
```
Обычная установка уже достаточна для Markdown, TXT, JSON, DOCX и XLSX. `[pdf]` добавляет локальный PDF-экстрактор `pypdf`.
### 2. Выбрать папку
LINZA работает с любой Markdown-папкой: Obsidian vault, рабочей папкой проекта или отдельной папкой с документами.
В примерах ниже замените `/absolute/path/to/workspace-or-vault` на свой путь.
### 3. Подключить MCP-клиент
Claude Desktop, Cursor, OpenCode и другие MCP-клиенты обычно используют такой формат:
```json
{
"mcpServers": {
"linza": {
"command": "linza-mcp",
"env": {
"LINZA_VAULT": "/absolute/path/to/workspace-or-vault"
}
}
}
}
```
VS Code / Copilot MCP использует ключ `servers`:
```json
{
"servers": {
"linza": {
"type": "stdio",
"command": "linza-mcp",
"env": {
"LINZA_VAULT": "/absolute/path/to/workspace-or-vault"
}
}
}
}
```
`LINZA_VAULT` не обязателен для старта: без него сервер использует `./vault`. Но для реальной работы лучше задать явную папку.
### 4. Проверить запуск
```powershell
linza-mcp --version
```
После подключения попросите агента:
```text
Проверь LINZA через agent_workspace(action="doctor").
Проиндексируй папку и покажи первые 3-5 предложений.
```
---
## Эмбеддинги
LINZA может запуститься и показать инструменты без embedding-сервера. Эмбеддинги нужны для смыслового поиска, карты тем и предложений связей.
Самый простой локальный путь - LM Studio:
1. Открыть LM Studio.
2. Скачать embedding-модель, например `text-embedding-granite-embedding-278m-multilingual`, `nomic-embed-text-v1.5` или другую подходящую модель.
3. Запустить Local Server.
4. Проверить, что endpoint доступен на `http://127.0.0.1:1234/v1`.
Пример переменных для LM Studio:
```powershell
$env:LINZA_EMBED_PROVIDER="lmstudio"
$env:LINZA_EMBED_URL="http://127.0.0.1:1234/v1"
$env:LINZA_EMBED_MODEL="your-embedding-model-name"
```
Поддерживаются:
- `lmstudio` - рекомендуемый локальный режим;
- `ollama` - локальный вариант через Ollama;
- `openai` - любой OpenAI-compatible endpoint с `/embeddings`.
Если меняете провайдер, модель или размерность, сделайте полный реиндекс. LINZA проверяет embedding signature и останавливает graph/search workflows, если sidecar устарел или содержит смешанные векторные пространства.
---
## Основные MCP-инструменты
По умолчанию LINZA показывает только 7 MCP-инструментов. Этого хватает для обычной работы: проверить состояние, проиндексировать папку, искать, читать файл, смотреть счетчики, диагностировать vault и вести агента через `agent_workspace`.
| Инструмент | Зачем |
| --- | --- |
| `agent_workspace` | Единый вход для диагностики, карты, импорта, ревью, обучения, роста, связей, памяти и экспорта контекста |
| `guide_next_steps` | Показать следующий безопасный шаг простым языком |
| `index_all` | Проиндексировать Markdown-папку в `.linza/linza.db` |
| `search` | Семантический и лексический поиск |
| `read_file` | Прочитать точный Markdown-файл |
| `get_stats` | Быстрые счетчики служебной базы |
| `scan_vault` | Диагностика папки без записи |
Низкоуровневые инструменты считаются деталями реализации и доступны через `agent_workspace`, поэтому набор из 7 инструментов - это полноценный режим.
### Режимы `agent_workspace`
| Action | Режим |
| --- | --- |
| `doctor` | Проверить готовность LINZA и показать, чего не хватает |
| `map` | Собрать карту рабочей папки без записи |
| `teach` | Выбрать сильные принятые примеры для обучения |
| `grow` | Показать или применить рост по принятым примерам; по умолчанию dry-run |
| `review_next` | Показать следующие предложения на ревью; интенты базы имеют ID `rq-*`, интенты артефактов и рабочей папки - `aw-*` |
| `apply_review_items` | Показать или применить точные выбранные ID; по умолчанию dry-run |
| `history` | Показать принятые и отозванные одобрения |
| `revoke_approval` | Мягко отозвать одобрение, не удаляя историю |
| `ingest_artifacts` | Сохранить вставленный или извлеченный материал в sidecar |
| `analyze_inbox` | Найти события, кандидаты памяти и фрагменты знания в артефактах |
| `connect` | Объяснить возможную связь между двумя заметками или узлами |
| `search_memory` | Искать по подтвержденной памяти и контексту артефактов |
| `export_context` | Собрать компактный пакет контекста для другого агента |
| `record_trace` | Сохранить структурированные следы работы агента, не raw chain-of-thought |
| `analyze_trace` | Разобрать сохраненный trace для ревью |
| `review_calibr` | Проверить уроки калибровки, полученные из traces |
Для разработки и аудита остается отдельный низкоуровневый режим. Полное описание инструментов: [Tool Catalog](LINZA_TOOL_CATALOG.md).
---
## Входящие артефакты
LINZA умеет принимать материал, который еще не стал заметкой:
- вставленный текст;
- локальные `.md`, `.txt`, `.json`;
- локальные `.docx`, `.xlsx`;
- локальные `.pdf`, если установлен `pypdf` или `PyPDF2`.
LINZA сама не ходит в браузер. Агент использует свой браузер, web-fetch или connector, извлекает читаемый текст и передает его в LINZA как артефакт, например `source_kind="web_article"` или `source_kind="browser_capture"`.
Импортированный текст считается материалом для анализа, не инструкцией для агента. Это граница prompt injection: инструкции внутри статьи, лога, чата или PDF не исполняются. Память, правила и YAML появляются только после ревью.
---
## Модель безопасности
LINZA - локальный review-gated sidecar.
| Действие | Куда пишет | Меняет текст заметок? |
| --- | --- | --- |
| Индексация, анализ, поиск | `.linza/linza.db` | Нет |
| Сырые артефакты | `.linza/linza.db` | Нет |
| Название формата материала | `.linza/linza.db` | Нет |
| `domains` или `role` в YAML | Только компактный YAML после ревью | Нет |
| Иерархия, причинные связи, память, уроки калибровки | `.linza/linza.db` | Нет |
| Отчеты | `.linza/reports` | Нет |
| Пакеты контекста | `.linza/context-packs` | Нет |
| `write_file` | Markdown-файл только при явном запросе | Может создать/заменить файл, dry-run по умолчанию |
Дополнительные правила:
- `review_next` ничего не пишет;
- `apply_review_items` по умолчанию dry-run;
- видимые YAML-правки компактные и требуют точного выбранного ID;
- `history` показывает, что было принято и что отозвано;
- `revoke_approval` мягко отзывает одобрение: история остается, но активное обучение и помощники графа его игнорируют;
- `map`, `teach`, `grow` и `connect` останавливаются, если исходные файлы изменились после индексации.
---
## Инструкции для агентов
В репозитории есть переносимый операторский skill:
```text
agent-pack/skills/linza-operator/SKILL.md
agent-pack/skills/linza-operator/references/workflows.md
agent-pack/skills/linza-operator/references/safety-policy.md
agent-pack/skills/linza-operator/references/tool-audience.md
```
Он объясняет агенту, как начинать с `doctor`, когда показывать предложения на ревью, как работать со страницами через внешний browser/web-fetch инструмент и почему apply actions должны идти сначала через dry-run и только по точным ID.
---
## Стабильность
LINZA пока alpha. Основной контракт безопасности должен оставаться стабильным: индексация, импорт артефактов, поиск, карта и grow preview не переписывают тела исходных заметок. Низкоуровневые advanced-инструменты и внутренние границы кода еще могут меняться, пока сервер полируется.
---
## Проверка
Запустить полный набор тестов:
```powershell
python -m unittest discover -s tests
```
---
## Переменные окружения
| Переменная | Нужна для старта? | Описание |
|---|---:|---|
| `LINZA_VAULT` | Нет | Путь к Markdown-папке; по умолчанию `./vault` |
| `LINZA_EMBED_PROVIDER` | Нет | `lmstudio` для рекомендуемого локального режима; также `openai` и `ollama` |
| `LINZA_EMBED_URL` | Нет | URL embeddings API; по умолчанию `http://127.0.0.1:1234/v1` |
| `LINZA_EMBED_MODEL` | Нет | Модель эмбеддингов; задайте перед semantic indexing/search |
| `LINZA_EMBED_KEY` | Нет | Опциональный ключ для OpenAI-compatible embeddings API |
| `LINZA_BRIDGE_THRESHOLD` | Нет | Порог semantic bridge; по умолчанию `0.55` |
| `LINZA_MAX_BRIDGE_PAIRS` | Нет | Максимум пар заметок для пересчета semantic bridges; по умолчанию `1000000`, `0` отключает guard |
| `LINZA_DEFAULT_PROFILE` | Нет | Имя базового search-профиля; по умолчанию `general` |
| `LINZA_LANGUAGE` | Нет | Язык подсказок и маршрута ревью в `guide_next_steps`: `auto`, `ru`, `en` |
---
## Ссылки
- [semiotronika.ru](https://semiotronika.ru)
- [PyPI](https://pypi.org/project/linza-mcp/)
- [GitHub](https://github.com/Semiotronika/LINZA-MCP)
MIT License (c) 2026 Semiotronika
*Косинусы считаются. Синтаксис меняется. Семантика остается.*
<!-- mcp-name: io.github.Semiotronika/LINZA-MCP -->