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

Не меняет данные — меняет взгляд.

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

English version

Зачем нужна LINZA

Она помогает агенту понять рабочую ситуацию и выделить главное в документах.

Например, у вас есть:

• Obsidian vault с заметками и черновиками;

• папка проекта с Markdown-документами;

• статьи, PDF, DOCX, XLSX, JSON, чаты и логи;

• правила, которые будущий агент должен помнить, но не должен сам выдумывать.

LINZA читает файлы в папке, строит рядом с ней локальную SQLite-базу .linza/linza.db и показывает агенту что в файлах: какие темы есть в базе, какие материалы повторяются, какие заметки связаны, где есть причинные цепочки, что стоит запомнить для будущих сессий.

Агент не переписывает заметки во время индексации, не превращает сырые заметки в правила и не учится за вашей спиной. LINZA превращает гипотезы в короткие предложения для ревью, агент показывает их вам, и вы решаете что из этого применить именно на ваших данных.

Что появляется после первого запуска

LINZA собирает несколько вещей, которые помогают агенту работать.

1. Карта папки Сколько заметок найдено, свежий ли индекс, какие области видны, какие материалы ждут вашего ревью.

2. Области Крупные смысловые группы. Это черновые названия, пока вы их не подтвердите или не переименуете.

3. Типы материалов Заметка, черновик, спецификация, исследование, кейс, лог, правило и другие формы, которые реально повторяются в вашей папке.

4. Связи Возможные соседства, иерархия, причина/следствие, маршруты между узлами.

5. Память для будущих агентов Что помнить, когда вспоминать, где риск устаревания, какие есть сомнения.

6. Пакет контекста Компактный пакет для агента: выбранный контекст с источниками и границами.

Как выглядит ревью

Внутри каждое предложение для ревью остается структурой с номером, доказательствами и пробным применением. Наружу LINZA отдает готовые строки для человека, чтобы агент мог не пересказывать JSON, а просто написать нормальный ответ.

LINZA готова

Материал:
- 42 заметки проиндексированы
- 3 входящих артефакта ждут ревью
- служебная база: .linza/linza.db

Следующий шаг:
1. Посмотреть найденные области
2. Подтвердить или переименовать 3-5 предложений
3. Ничего не будет записано без подтверждения

Предложение:
Связать "Retrieval Quality Note" и "Source Policy"
Почему: общий словарь, ссылки на ревью, близкие чанки
Что изменится: пока ничего; после подтверждения появится связь

Хорошее предложение всегда отвечает на главный вопрос: почему LINZA так думает? В нем должны быть источники, причины, чанки, тип связи, уверенность и честное описание того, что изменится после применения.

Установка

1. Установить LINZA

python -m pip install linza-mcp

Если нужно читать PDF-файлы прямо через LINZA:

python -m pip install "linza-mcp[pdf]"

Если PDF не нужны, достаточно обычной установки. [pdf] добавляет локальный PDF-экстрактор pypdf.

2. Выбрать папку

LINZA работает с любой папкой Markdown. Это может быть Obsidian vault, рабочая папка проекта или отдельная папка с документами.

В примерах ниже замените /absolute/path/to/workspace-or-vault на свой путь.

3. Настроить эмбеддинги

Для смыслового поиска LINZA нужна модель эмбеддингов. Самый простой локальный путь — 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.

4. Подключить к MCP-клиенту

Claude Desktop, Cursor, OpenCode и другие MCP-клиенты обычно используют такой формат:

{
  "mcpServers": {
    "linza": {
      "command": "linza-mcp",
      "env": {
        "LINZA_VAULT": "/absolute/path/to/workspace-or-vault",
        "LINZA_EMBED_PROVIDER": "lmstudio",
        "LINZA_EMBED_URL": "http://127.0.0.1:1234/v1",
        "LINZA_EMBED_MODEL": "your-embedding-model-name",
        "LINZA_TOOL_SURFACE": "default"
      }
    }
  }
}

VS Code / Copilot MCP использует ключ servers:

{
  "servers": {
    "linza": {
      "type": "stdio",
      "command": "linza-mcp",
      "env": {
        "LINZA_VAULT": "/absolute/path/to/workspace-or-vault",
        "LINZA_EMBED_PROVIDER": "lmstudio",
        "LINZA_EMBED_URL": "http://127.0.0.1:1234/v1",
        "LINZA_EMBED_MODEL": "your-embedding-model-name"
      }
    }
  }
}

Установки через реестры и hosted-каталоги должны брать способ запуска из server.json. LINZA объявляет runtimeHint: "uvx" для PyPI-пакета, чтобы такие раннеры запускали сервер через Python runtime, а не искали глобальный бинарь linza-mcp.

5. Проверить запуск

linza-mcp --version

После подключения попросите агента:

Проверь LINZA через agent_workspace(action="doctor").
Проиндексируй папку и покажи первые 3-5 предложений для ревью.

Опциональный запуск через Docker

Docker не обязателен, но в репозитории есть маленький образ для изолированного stdio-запуска:

docker build -t linza-mcp .
docker run --rm -i `
  -v /absolute/path/to/workspace-or-vault:/data/vault `
  -e LINZA_EMBED_PROVIDER=lmstudio `
  -e LINZA_EMBED_URL=http://host.docker.internal:1234/v1 `
  -e LINZA_EMBED_MODEL=your-embedding-model-name `
  linza-mcp

host.docker.internal подходит, когда embedding-сервер запущен на хосте. Если модель доступна по другому адресу, передайте URL, который виден из контейнера.

Про эмбеддинги

Эмбеддинги — это качество зрения LINZA. Основной сценарий простой: локальная модель в LM Studio и MCP-сервер рядом с папкой.

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

• ollama — локальный вариант через Ollama.

• openai — любой OpenAI-compatible endpoint с /embeddings.

Пример переменных для LM Studio:

$env:LINZA_EMBED_PROVIDER="lmstudio"
$env:LINZA_EMBED_URL="http://127.0.0.1:1234/v1"
$env:LINZA_EMBED_MODEL="your-embedding-model-name"

Если меняете провайдера, модель или размерность, сделайте полный реиндекс. LINZA проверяет сигнатуру и останавливает сценарии, если служебная база с эмбеддингами устарела или в ней смешаны разные векторные пространства.

Входящие артефакты

LINZA умеет принимать материал, который еще не стал заметкой:

• вставленный текст;

• локальные .md, .txt, .json;

• локальные .docx, .xlsx;

• локальные .pdf, если установлен pypdf или PyPDF2.

LINZA сама не ходит в браузер. Агент использует свой браузер или инструмент загрузки страниц, извлекает читаемый текст и передает его в базу как артефакт.

Загруженный текст считается материалом для анализа, а не командой для агента. Это базовая граница промпт-инъекций: инструкции внутри статьи, лога, чата или PDF не исполняются. Память, правила и YAML появляются только после ревью.

Основные инструменты

По умолчанию LINZA показывает только 7 MCP-инструментов. Этого хватает для обычной работы: проверить состояние, проиндексировать папку, найти материал, прочитать файл и попросить LINZA вести агента дальше.

Остальные инструменты никуда не исчезли. Они скрыты из обычной витрины:

• рабочие действия идут через agent_workspace: показать предложения, применить выбранные номера, объяснить связь, собрать пакет контекста;

• низкоуровневые отчеты и отладочные команды доступны в расширенном режиме;

• прямой write_file тоже не показывается по умолчанию, потому что LINZA не должна подталкивать агента к записи текста в заметки.

agent_workspace(action="teach") выбирает сильные примеры для обучения. grow показывает, почему следующие предложения попали в партию. Идея такая: сначала научить на примерах, потом показать пробный рост, потом применять подтвержденными партиями.

Если вы приняли не то, одобрение можно мягко отозвать:

agent_workspace(action="history")
agent_workspace(action="revoke_approval", approval_id=17, dry_run=false)

LINZA не удаляет старую запись и не пытается автоматически откатить YAML. Она помечает одобрение как отозванное, перестает использовать его как активный пример и оставляет след в истории действий.

Расширенный режим для разработки и отладки:

$env:LINZA_TOOL_SURFACE="advanced"

Полное описание каждого инструмента: Tool Catalog.

Безопасность

LINZA проектируется как локальный служебный слой с проверкой человеком:

• индексирование, анализ, поиск и импорт не меняют тела исходных заметок;

• index_all и служебные операции пишут в .linza/linza.db;

• поиск может сохранять историю поиска в служебной базе;

• сырые артефакты хранятся локально в SQLite;

• отчеты пишутся только в .linza/reports;

• пакеты контекста пишутся только в .linza/context-packs;

• видимые YAML-изменения компактные и требуют подтверждения;

• иерархия, причинные связи, память, уроки агента и подтверждения живут в служебной базе, пока вы не попросите экспорт или применение;

• agent_workspace(action="history") показывает, что уже принимали и что отзывали;

• agent_workspace(action="revoke_approval") мягко отзывает одобрение: запись остается в истории, но больше не участвует в росте, карте и обучении;

• LINZA останавливает карту, обучение, рост и объяснение связей, если файлы изменились после индексации.

LINZA не автопилот, который сам переписывает правила, скиллы, память или заметки.

Инструкции для агента

В репозитории есть готовый операторский навык:

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

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

Стабильность

0.1.7 — ранняя версия. Индексация, импорт артефактов, поиск, карта и пробный рост не переписывают тела исходных заметок. Низкоуровневые инструменты и внутренние границы модулей еще могут меняться, пока сервер полируется.

Примеры и тесты

Синтетический пример лежит в:

examples/sample-vault/
examples/artifacts/
examples/expected/

Запустить все тесты:

python -m unittest discover -s tests

Запустить один конкретный тест:

python -m unittest tests.test_agent_workspace.AgentWorkspaceTests.test_examples_sample_pack_runs_end_to_end

Переменные окружения

Ссылки

• semiotronika.ru

• PyPI

• GitHub

MCP Registry ID: io.github.Semiotronika/LINZA-MCP

MIT License © 2026 Semiotronika

Косинусы считаются. Синтаксис меняется. Семантика остаётся.