# Semiotronika/LINZA-MCP [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/Semiotronika/LINZA-MCP  
**GitHub Stars:** 4  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/semiotronika-linza-mcp

## Description
Local-first review-gated sidecar for Markdown workspaces. Indexes notes and incoming artifacts into SQLite, proposes domains, links, memory, and growth cards with evidence, and keeps source files unchanged until explicit review. pip install linza-mcp

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "linza-mcp": {
    "command": "uvx",
    "args": ["linza-mcp"],
    "env": {
      "LINZA_VAULT": ""
    }
  }
}
```

**Requires environment variables:** `LINZA_VAULT` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation & README

# LINZA - локальный MCP-сервер для агентской работы с папками знаний

> *Не меняет данные. Меняет взгляд.*

LINZA работает с Obsidian vault, Markdown-папками, документами, статьями, логами и черновиками. Она нужна, когда материалов уже слишком много и вы хотите разобрать базу, выделить в ней основные области и научить агента хорошо ориентироваться в ней.

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
[![MCP](https://img.shields.io/badge/protocol-MCP_stdio-lightgrey.svg)](https://modelcontextprotocol.io)
![Local first](https://img.shields.io/badge/storage-local--first-green.svg)
![Review gated](https://img.shields.io/badge/writes-review--gated-orange.svg)

[English version](https://github.com/Semiotronika/LINZA-MCP/blob/HEAD/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](https://github.com/Semiotronika/LINZA-MCP/blob/HEAD/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 -->