Slipbox MCP Server

Дайте вашему ИИ-ассистенту активную роль в управлении вашими знаниями. Slipbox — это MCP-сервер, который превращает любого MCP-совместимого агента в партнера по методу Цеттелькастен: создание атомарных заметок, формирование семантических связей, обнаружение возникающих кластеров и синтез идей из ваших существующих знаний.

Ваши идеи на входе, структурированные знания на выходе. Агент берет на себя форматирование, связывание и интеграцию.

Новичок в методе? Начните с Введения в метод Цеттелькастен — там объясняется, зачем нужны атомарные заметки и связанное мышление. Чтобы узнать, как Slipbox знакомит вашего агента с этим методом, прочитайте инструкции сервера, которые автоматически отправляются при подключении.

Создано и протестировано с Claude. Работает с любым MCP-клиентом (Claude Desktop, Claude Code, OpenCode, Copilot или что-либо, говорящее на MCP).

Простые файлы, нулевая привязка. Заметки — это Markdown с YAML-frontmatter: их можно читать в Obsidian, Foam, Logseq или любом редакторе. База данных SQLite — это индекс, а не источник истины. Удалите её и перестройте из файлов в любой момент.

• 19 MCP-инструментов для заметок, связей, поиска, анализа графа и управления кластерами

• 6 рабочих промптов (плюс соответствующие навыки), кодирующих метод Цеттелькастен, чтобы вам не приходилось переучивать его каждый раз

• Полнотекстовый поиск BM25 по заголовкам и содержимому через SQLite FTS5

• Обнаружение кластеров находит возникающие тематические группы и создает структурные заметки

• Семь типизированных связей (ссылка, расширяет, уточняет, противоречит, задает вопрос, поддерживает, связана)

Python 3.10+ | macOS или Linux

Видеообзор

Related MCP server: vault-master-mcp

Быстрый старт

1. Установка

pipx install slipbox-mcp
# or, with uv:
uv tool install slipbox-mcp

Эта команда помещает лаунчер slipbox-mcp в ваш PATH (в ~/.local/bin). Одна команда — это весь MCP-сервер: никакого клонирования, никакого PYTHONPATH, никакого жестко заданного пути к Python в виртуальном окружении. Всё ниже использует её. Чтобы попробовать без установки, uvx slipbox-mcp запускает сервер в одноразовом окружении.

(Работаете над самим Slipbox? Смотрите Разработка для настройки клона и редактируемой установки.)

2. Выберите каталог данных

Одна переменная, SLIPBOX_BASE_DIR, настраивает всё: заметки сохраняются в <base>/data/notes, а индекс SQLite — в <base>/data/db/zettelkasten.db. Сервер создает их при первом запуске с правами только для владельца (0700).

Укажите SLIPBOX_BASE_DIR (или отдельные пути SLIPBOX_NOTES_DIR / SLIPBOX_DATABASE_PATH ниже) на выделенный каталог данных под вашим контролем, а не на общий или системный каталог. Эти пути используются как есть: сервер управляет деревом заметок и индексом внутри них и считает каталог заметок источником истины при перестроении индекса.

# Example: use any absolute path you like
/Users/yourname/.local/share/mcp/slipbox

Используйте полный абсолютный путь. Начальный ~ не раскрывается в конфигурационных файлах MCP-клиента и создаст буквальный каталог ~.

3. Подключение к вашему MCP-клиенту

Claude Code (одна команда, без редактирования файлов):

claude mcp add slipbox \
  --env SLIPBOX_BASE_DIR=/Users/yourname/.local/share/mcp/slipbox \
  -- slipbox-mcp

Claude Desktop (отредактируйте конфигурационный файл):

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "slipbox": {
      "command": "slipbox-mcp",
      "env": {
        "SLIPBOX_BASE_DIR": "/Users/yourname/.local/share/mcp/slipbox"
      }
    }
  }
}

Предостережение о PATH для Desktop: настольное приложение macOS не всегда наследует ~/.local/bin из своего PATH, поэтому простая команда "slipbox-mcp" может не сработать. Если сервер не запускается, замените "command": "slipbox-mcp" на абсолютный путь, который выводит which slipbox-mcp (обычно /Users/yourname/.local/bin/slipbox-mcp).

Другие MCP-клиенты: зарегистрируйте slipbox-mcp как команду сервера с SLIPBOX_BASE_DIR в его окружении. Команда и окружение одинаковы везде.

Вместо SLIPBOX_BASE_DIR задайте абсолютные пути по отдельности. Необязательный SLIPBOX_LOG_LEVEL может быть одним из DEBUG, INFO, WARNING, ERROR.

"env": {
  "SLIPBOX_NOTES_DIR": "/Users/yourname/.local/share/mcp/slipbox/notes",
  "SLIPBOX_DATABASE_PATH": "/Users/yourname/.local/share/mcp/slipbox/data/db/zettelkasten.db",
  "SLIPBOX_LOG_LEVEL": "INFO"
}

4. Перезапуск и проверка

Перезапустите клиент (Claude Code перезагружается при следующем запуске; закройте и снова откройте Claude Desktop).

Спросите вашего агента:

• "Создай тестовую заметку о чём-нибудь"

• "Поищи в моём slipbox тест"

• "Найди осиротевшие заметки"

В действии

Главная демонстрация выше — это основной цикл. Вот всё остальное, что делает агент.

Проактивное обслуживание

Агент читает ресурс slipbox://maintenance-status в начале сеанса и показывает кластеры, которые нужно организовать.

Полнотекстовый поиск

Поиск с ранжированием BM25 по заметкам через slipbox_search_notes.

Граф знаний: центральные заметки

slipbox_find_central_notes показывает структурные якоря графа — заметки, вокруг которых вращается всё остальное.

Анализ заметки

Промпт analyze_note оценивает атомарность, находит реальные связи в существующем графе, предлагает теги и переписывает для ясности.

Разложение источника

Промпт knowledge_creation разбивает статью на атомарные литературные заметки с правильными цитатами и связями.

Обнаружение кластеров

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

Создание структурной заметки

slipbox_create_structure_from_cluster создает структурную заметку, связывает все заметки-участницы и закрывает кластер.

Осиротевшие заметки

slipbox_find_orphaned_notes показывает неинтегрированные знания — кандидатов на связывание или удаление.

Похожие заметки

slipbox_find_similar_notes вычисляет сходство на основе общих тегов, общих связей и пересечения содержимого.

Обход графа

slipbox_get_linked_notes показывает типизированные связи от узловой заметки, сгруппированные по типу связи.

Синтез знаний

Промпт knowledge_synthesis находит мосты между несвязанными областями и предлагает синтез-заметки из ваших существующих знаний.

Нулевая привязка: простые файлы в Obsidian

Заметки — это обычный Markdown. Откройте хранилище в Obsidian, и всё работает: отображаемое содержимое, обратные ссылки и граф знаний.

Чтобы получить граф, который отображает типизированные связи в цвете (поддерживает, расширяет, уточняет, ...) вместо нетипизированного встроенного графа Obsidian, установите дополнительный плагин Slipbox Semantic Graph — представление с силовым направлением, человекочитаемыми заголовками и цветными семантическими типами связей. Установите его вручную из релиза 0.1.0: скопируйте main.js, manifest.json и styles.css в <vault>/.obsidian/plugins/slipbox-graph/, затем включите в Настройки → Сторонние плагины. (Когда он будет принят в официальный каталог, вы также сможете установить его через Настройки → Сторонние плагины → Обзор → поиск "Slipbox Semantic Graph".) Он читает тот же frontmatter id и раздел ## Links, которые записывает сервер, поэтому дополнительная настройка не требуется. Откройте представление с помощью команды Открыть семантический граф (Палитра команд) или значка-ленты git-fork.

Легенда вверху сопоставляет каждый цвет с типом связи (расширяет, уточняет, поддерживает, противоречит, задаёт вопрос, связана). Сфокусируйтесь на структурной заметке, и её созвездие появится. Здесь Карта знаний контрактного тестирования с заметками-участницами, вращающимися вокруг неё:

Дополнительно: автоматическое обнаружение кластеров

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

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

Установка обнаружения кластеров (macOS)

chmod +x scripts/install-cluster-detection.sh
./scripts/install-cluster-detection.sh

Установщик определяет путь к Python/venv, генерирует plist для LaunchAgent и загружает его.

Ручной тест (файловый наблюдатель)

source .venv/bin/activate
python scripts/detect_clusters.py

Вывод сохраняется в ~/.local/share/mcp/slipbox/cluster-analysis.json.

Удаление обнаружения кластеров

./scripts/install-cluster-detection.sh --uninstall

Дополнительно: файловый наблюдатель macOS для автоиндексации

MCP-сервер поддерживает индекс базы данных для быстрого поиска. Редактирование заметок в Obsidian (или любом редакторе) делает базу данных устаревшей, пока вы не запустите slipbox_rebuild_index.

Файловый наблюдатель работает как фоновый демон, отслеживает ваш каталог заметок и автоматически перестраивает индекс при изменении .md-файлов.

Используйте его, если вы часто редактируете заметки в Obsidian, одновременно используя Claude.

Установка файлового наблюдателя (macOS)

chmod +x scripts/install-file-watcher.sh
./scripts/install-file-watcher.sh

Установщик определяет путь к Python/venv, устанавливает watchdog при необходимости и загружает LaunchAgent. Запускается при входе в систему и перезапускается при сбое.

Ручной тест

source .venv/bin/activate
python scripts/watch_notes.py

Отредактируйте файл заметки. Вы должны увидеть "перестройка индекса..." в выводе наблюдателя.

Проверка статуса

launchctl list | grep slipbox.watcher

# View logs

tail -f ~/.local/share/mcp/slipbox/watcher.log

Удаление файлового наблюдателя

./scripts/install-file-watcher.sh --uninstall

Рекомендуемый системный промпт

Slipbox автоматически предоставляет базовый набор: каждый клиент получает инструкции сервера при подключении, описывающие, как правильно использовать инструменты — типы заметок, семантику связей, стандарты качества и основные рабочие процессы, такие как поиск перед созданием. Вам не нужно добавлять их самостоятельно.

docs/SYSTEM_PROMPT.md — это дополнительный уровень поверх: директивы автономии и инициативы, которые сервер не должен устанавливать самостоятельно. Добавьте его в предпочтения вашего агента или системный промпт, чтобы включить:

• Автоматический захват знаний во время разговоров

• Обнаружение возникновения кластеров в начале разговора

Справочник инструментов

Основные операции с заметками

Связывание

Поиск и обнаружение

Анализ кластеров

Обслуживание

Справочник промптов

MCP-промпты — это переиспользуемые шаблоны рабочих процессов, в которых закодирован метод Zettelkasten, чтобы вам не приходилось объяснять его заново в каждой сессии.

Как вызывать: слеш-команды и скиллы

Каждый рабочий процесс доступен двумя способами:

• MCP-промпты: предоставляются запущенным сервером.

• Скиллы: автономные наборы (skills/<name>/), которые запускают тот же рабочий процесс и добавляют активацию по естественному языку.

Пять из шести скиллов генерируются из тех же шаблонов PROMPT_*, которые использует сервер (src/slipbox_mcp/server/descriptions.py), и CI завершается ошибкой, если закоммиченные skills/ расходятся с этими шаблонами. Шестой, cluster-maintenance, написан непосредственно в scripts/build_skills.py, поскольку его MCP-промпт — это сообщение о состоянии, формируемое во время выполнения, а не переиспользуемый рабочий процесс.

Слеш-команды — надёжный способ. Claude Code показывает MCP-промпты как /mcp__<server>__<prompt>; введите /mcp__slipbox-mcp__, чтобы открыть выбор:

/mcp__slipbox-mcp__knowledge_creation
/mcp__slipbox-mcp__knowledge_exploration
/mcp__slipbox-mcp__knowledge_synthesis
/mcp__slipbox-mcp__knowledge_creation_batch
/mcp__slipbox-mcp__analyze_note
/mcp__slipbox-mcp__cluster_maintenance

(Установленные скиллы также предоставляют собственные слеш-команды по имени директории, например /slipbox-analyze-note.)

Естественный язык работает после установки соответствующего скилла. Просто опишите, что вам нужно:

Analyze this note for my slipbox: [paste note]

Add this to my slipbox: [paste article]

Synthesize my notes on attention and memory.

Активация по прозе зависит от того, установлен ли скилл и совпадает ли ваша формулировка с его описанием; если она не срабатывает, используйте слеш-команду. Просьба к модели «используй промпт analyze_note» по имени не работает. Модель не может вызвать MCP-промпт по имени. Используйте слеш-команду или позвольте скиллу активироваться по естественному языку.

Установка скиллов

Claude Code обнаруживает скиллы в .claude/skills/ (для проекта) или ~/.claude/skills/ (глобально), а не в просто верхнеуровневой папке skills/. Создайте симлинки или скопируйте нужные скиллы в один из путей обнаружения (например, для этого проекта):

mkdir -p .claude/skills
ln -s ../../skills/slipbox-analyze-note .claude/skills/slipbox-analyze-note
# ...or copy the directories, or symlink all six

Claude Desktop требует каждый скилл в виде пакета .skill. Соберите их, затем загрузите:

python scripts/build_skills.py     # writes dist/*.skill

Перейдите в Settings → Skills → Upload skill и выберите нужные пакеты из dist/. Каждый устанавливается и как слеш-команда, и как триггер по естественному языку.

После изменения шаблона промпта в descriptions.py снова запустите сборку, чтобы перегенерировать скиллы.

Типы связей

Типы заметок

Структурная заметка против хаба: Структурная заметка организует кластер постоянных заметок вокруг одной темы. Это курируемая карта, находящаяся на один уровень выше самих заметок. Хаб-заметка работает ещё на один уровень выше: она связывает структурные заметки (а иногда и ключевые постоянные заметки) в рамках целой области знаний. Если структурная заметка отвечает на вопрос «что я знаю об X?», то хаб-заметка отвечает на вопрос «как организованы мои знания об этой области в целом?» Большинству Zettelkasten достаточно всего нескольких хаб-заметок.

Формат файлов

Заметки хранятся в виде Markdown-файлов с YAML-frontmatter:

---
id: "20251217T172432480464000"
title: "Poetry Revision Principles"
type: structure
tags:
  - poetry
  - revision
  - craft
created: "2025-12-17T17:24:32"
updated: "2025-12-17T17:24:32"
---

# Poetry Revision Principles

Content here...

## Links

- reference [[20250728T125429845760000]] Member of structure

Вы можете редактировать эти файлы напрямую в любом текстовом редакторе или Obsidian. Выполните slipbox_rebuild_index после внешних правок.

Обновление

После установки новых версий перезапустите Claude Desktop. Если в примечаниях к выпуску упоминаются изменения базы данных, один раз выполните slipbox_rebuild_index, чтобы привести существующую базу данных в актуальное состояние.

Обновление до полнотекстового поиска FTS5 (любая версия после релиза FTS5): Индекс полнотекстового поиска создаётся автоматически при запуске сервера с новой базой данных. Для существующих баз данных таблица FTS5 будет создана при первом запуске, но останется пустой, пока вы не выполните:

slipbox_rebuild_index

Это заполняет индекс BM25 из ваших существующих заметок. До этого момента результаты поиска не будут ранжироваться по релевантности.

Устранение неполадок

Сервер не загружается в Claude Desktop

1. Убедитесь, что лаунчер находится в PATH: which slipbox-mcp должен вывести путь (обычно ~/.local/bin/slipbox-mcp).

2. Если в терминале команда находится, но Desktop всё равно не может её запустить, значит, GUI-приложение не видит ~/.local/bin в своём PATH. Замените "command": "slipbox-mcp" на абсолютный путь из шага 1.

3. Проверьте журналы Claude Desktop на наличие ошибок.

slipbox-mcp: command not found

Консольный скрипт не был установлен или его нет в PATH. Переустановите с помощью pipx install --editable . --force, затем проверьте командой which slipbox-mcp. Если каталог bin от pipx отсутствует в PATH, выполните pipx ensurepath и перезапустите оболочку.

Каталог заметок указывает на ~/... буквально

Если ваш каталог заметок оказывается в ./~/... относительно CWD, значит, вы использовали ~ в JSON-конфиге. Claude Desktop не раскрывает ~. Замените его на полный абсолютный путь.

Поиск не возвращает результатов

1. Индекс FTS5 может быть не заполнен. Выполните slipbox_rebuild_index один раз, чтобы проиндексировать существующие заметки.

2. Если вы недавно редактировали заметки вне Claude, индекс может быть устаревшим. Выполните slipbox_rebuild_index.

slipbox_list_notes_by_date возвращает пустые результаты

Если start_date позже, чем end_date, ни одна заметка не соответствует условиям, и возвращается пустой результат. Это ожидаемое поведение, а не ошибка.

База данных рассинхронизирована

Если заметки редактировались вне MCP-сервера:

slipbox_rebuild_index

Обнаружение кластеров не запущено

launchctl list | grep slipbox.cluster-detection
# Should show: - 0 com.slipbox.cluster-detection

# Check logs

cat /tmp/slipbox-clusters.log

# Reinstall if needed

./scripts/install-cluster-detection.sh --uninstall
./scripts/install-cluster-detection.sh

Файловый наблюдатель не запущен

launchctl list | grep slipbox.watcher
# Should show: - 0 com.slipbox.watcher

# Check logs

cat ~/.local/share/mcp/slipbox/watcher.log

# Reinstall if needed

./scripts/install-file-watcher.sh --uninstall
./scripts/install-file-watcher.sh

Переход с переменных окружения ZETTELKASTEN_*

Если вы раньше использовали переменные ZETTELKASTEN_NOTES_DIR, ZETTELKASTEN_DATABASE_PATH или другие ZETTELKASTEN_*, они больше не читаются. Переименуйте их в соответствующие SLIPBOX_*:

Сервер записывает предупреждение, если обнаруживает старые имена, но не переносит их автоматически.

Путь к отчёту о кластерах не настраивается

Отчёт об анализе кластеров всегда записывается в ~/.local/share/mcp/slipbox/cluster-analysis.json независимо от SLIPBOX_BASE_DIR или SLIPBOX_NOTES_DIR. Если вы используете нестандартные пути, отчёт о кластерах всё равно будет находиться в расположении по умолчанию.

Скрипты установки предназначены только для macOS

Скрипты scripts/install-cluster-detection.sh и scripts/install-file-watcher.sh используют launchctl и ~/Library/LaunchAgents/, которые существуют только в macOS. В Linux вам придётся вручную создать аналогичные модули systemd или задания cron. Смотрите команды ручного тестирования в соответствующих разделах README, чтобы убедиться, что базовые Python-скрипты работают на вашей платформе.

Пути по умолчанию относительны к рабочей директории

Если SLIPBOX_NOTES_DIR и SLIPBOX_DATABASE_PATH не заданы, сервер по умолчанию использует data/notes и data/db/zettelkasten.db относительно текущей рабочей директории. При запуске через Claude Desktop CWD может оказаться не тем, что вы ожидаете. Чтобы избежать этого, всегда указывайте абсолютные пути в claude_desktop_config.json.

Разработка

Настройка

git clone https://github.com/jamesfishwick/slipbox-mcp.git
cd slipbox-mcp
uv venv && uv pip install -e ".[dev]"

Тестирование

В проекте три уровня тестов:

# Default: runs unit + contract tests (CI runs this)

pytest

# Run everything except LLM evals

pytest tests/ evals/tool_contracts/

# Run LLM evals (requires claude CLI authenticated)

pytest evals/llm/ -v

# Run LLM evals with a specific model

EVAL_MODEL=sonnet pytest evals/llm/ -v

# Lint

ruff check src/ evals/

Модульные тесты покрывают внутреннюю логику — сервисы, репозиторий, модели, парсинг.

Контрактные тесты инструментов проверяют формат вывода MCP-инструментов, который видит LLM: разбираемую структуру, цепочки (create -> search -> get) и понятные сообщения об ошибках. Эти тесты детерминированы и не вызывают LLM.

LLM-оценки отправляют промпты LLM через CLI claude с подключённым MCP-сервером, затем оценивают результаты, проверяя состояние базы данных (созданные заметки, применённые теги). Они проверяют, действительно ли LLM правильно использует инструменты с учётом их описаний.

CI/CD

Защита веток: Прямые пуши в main заблокированы. Все изменения проходят через PR.

Набор LLM-эвалов дорогой (~$3-5, ~10 мин) и работает на self-hosted раннере, поэтому никогда не запускается автоматически. Триггер по путям не может отличить настоящее изменение промпта от косметического переформатирования. Запускайте его намеренно, когда меняете смысл промпта или описаний инструментов:

• Добавьте метку run-llm-evals к PR. Он запустится и будет перезапускаться при каждом пуше, пока метка присутствует.

• Или запустите его вручную со вкладки Actions (workflow_dispatch).

• Или запустите локально без раннера: pytest evals/llm/ -v.

Без метки или ручного запуска задача пропускается (раннер не выделяется, расходов нет).

Настройка эвалов

Если вам не нужен self-hosted раннер: удалите .github/workflows/llm-evals.yml и запускайте pytest evals/llm/ -v локально перед слиянием изменений промптов.

Если вы хотите, чтобы LLM-эвалы запускались на каждом PR автоматически: добавьте триггер pull_request с соответствующим фильтром paths: и уберите проверку метки в if: джобы. Но рассчитывайте на случайные запуски из-за правок только форматирования.

Чтобы сменить модель эвалов по умолчанию: задайте EVAL_MODEL в окружении или в файле воркфлоу. По умолчанию — haiku для скорости и стоимости.

Чтобы настроить self-hosted раннер:

# Get a registration token

gh api repos/OWNER/REPO/actions/runners/registration-token -X POST -q '.token'

# Download and configure

mkdir -p ~/.github-runners/slipbox-mcp && cd ~/.github-runners/slipbox-mcp
curl -sL -o actions-runner.tar.gz https://github.com/actions/runner/releases/latest/download/actions-runner-osx-arm64-2.325.0.tar.gz
tar xzf actions-runner.tar.gz
./config.sh --url https://github.com/OWNER/REPO --token <TOKEN> --unattended
nohup ./run.sh &

Публикация в PyPI

Релизы автоматизированы. Воркфлоу Release (.github/workflows/release.yml) запускает release-please при каждом пуше в main и публикует через Trusted Publishing PyPI (OIDC, поэтому в секретах репозитория не хранится ни один API-токен).

Процесс (вы никогда не правите версию вручную и не пушите тег):

1. Вносите изменения в main с сообщениями в стиле Conventional Commit (feat: → минорная версия, fix: → патч, feat!:/BREAKING CHANGE: → мажорная версия). Коммит-хуки репозитория уже следят за этим форматом.

2. release-please держит открытым постоянный «release PR», накапливая следующее изменение версии (в src/slipbox_mcp/__init__.py) и записи CHANGELOG.md, полученные из этих коммитов.

3. Когда будете готовы выпустить релиз, смёржите release PR. Это создаст тег релиза (v<version>) и в том же запуске воркфлоу соберёт sdist + wheel, выполнит twine check и опубликует в PyPI.

То есть выпуск релиза — один клик: смёржите PR от бота. Больше ничего.

Типы коммитов определяют версию. Поэтому выбирайте их точно. Изменение версии вычисляется механически по префиксам Conventional Commit с момента последнего релиза, а не по размеру изменения. Приберегите feat:/fix: для изменений в публикуемом пакете; для всего остального используйте типы без выпуска релиза:

Набор только из нерелизных коммитов не создаёт вообще никакого release PR. Заголовок squash-merge — это коммит, который читает release-please, поэтому важен именно префикс заголовка PR. Называйте его по тому, что получает пакет, а не по затраченным усилиям.

Разовая настройка (для этого репозитория уже выполнена, описана для форков):

1. На PyPI зарегистрируйте ожидающего доверенного издателя для проекта slipbox-mcp: Владелец: jamesfishwick · Репозиторий: slipbox-mcp · Workflow: release.yml · Окружение: release. Все четыре значения должны совпадать точно.

2. В GitHub создайте окружение с именем release (Settings → Environments). Если вы ограничиваете допустимые refs для деплоя, добавьте правило для тегов v* (правило для веток с таким же именем не совпадёт с тегом).

Версия определяется один раз, в src/slipbox_mcp/__init__.py (release-please увеличивает её; маркер # x-release-please-version указывает, какую строку менять). pyproject.toml (dynamic = ["version"]) и server_version сервера оба читают из неё, так что синхронизировать ничего не нужно; тег, который создаёт release-please, всегда совпадает с версией пакета по построению.

Чтобы отрепетировать сборку без публикации, запустите её вручную: python -m build && twine check dist/* (а для пробной загрузки — twine upload --repository testpypi dist/* с токеном TestPyPI).

Общие константы промптов

Все описания инструментов и шаблоны промптов находятся в src/slipbox_mcp/server/descriptions.py. И MCP-сервер, и тесты эвалов импортируют из этого единого источника истины. Если вы меняете промпт, эвалы проверяют, по-прежнему ли LLM ведёт себя правильно с новой формулировкой.

Отладочное логирование

SLIPBOX_LOG_LEVEL=DEBUG python -c "from slipbox_mcp.main import main; main()"

CLI-инструмент

Команда slipbox предоставляет доступ из терминала для механических операций:

slipbox status          # Overview of notes, tags, orphans, pending clusters
slipbox search <query>  # Find notes by text
slipbox clusters        # Show pending structure note candidates
slipbox orphans         # List unconnected notes
slipbox rebuild         # Rebuild index (add --clusters to refresh cluster analysis)
slipbox export <id>     # Export note markdown to stdout
slipbox tags            # List all tags with usage counts

Установка: pipx install --editable . (добавляет slipbox в ваш PATH)

Экспериментально: Slipbox как память агента

Непроверенная гипотеза, а не рекомендованная настройка. Всё вышеописанное помогает агенту управлять вашим знанием. Здесь всё наоборот: агент использует slipbox как свою собственную постоянную память между сессиями, вместо встроенной памяти или файла с правилами.

У модели нет памяти между сессиями, поэтому slipbox — единственный канал, который одна сессия оставляет следующей. Она пишет брифинги для холодного преемника (сбой и его причина, повторяющееся ограничение, исправление, добытое с трудом знание), помечает их тегом agent-memory и ищет этот тег перед действием. Ставка в том, что связанная память лучше плоского файла правил, потому что она извлекается обходом по связям.

Сначала нужно знать три вещи: изоляция пространства имён — это соглашение по тегам, а не принудительное правило, поэтому используйте отдельный экземпляр slipbox; «память» — неверный термин, поскольку ничто, кроме самих заметок, не сохраняется; а дисциплина роста — как раз непроверенная часть, так что ожидайте разрастания при первом запуске. Полное описание и предостережения: Slipbox as Agent Self-Memory.

Документация

Участие в разработке

См. CONTRIBUTING.md — инструкции по настройке, стандарты кода и порядок отправки изменений.

Дорожная карта

См. ROADMAP.md — запланированные функции и будущее направление.

Поддержка

Если slipbox-mcp вам полезен, рассмотрите возможность спонсировать проект.

Лицензия

MIT