SecondBrain MCP

Safe MCP-сервер для Obsidian vault. Даёт AI-ассистентам (Claude, ChatGPT и др.) семантический доступ к заметкам, проектам, решениям и задачам, а также безопасные операции создания и подтверждённого редактирования.

Что умеет

Вместо сырого доступа к файлам предоставляет структурированные инструменты:

Related MCP server: knowledgebased

Safe-write контракт

MCP v0.3 поддерживает запись, но не даёт агенту тихо перезаписывать vault.

1. Клиент получает hash через list_notes или get_note_metadata.

2. Клиент вызывает propose_note_update и показывает пользователю diff.

3. Пользователь подтверждает изменение в UI.

4. Клиент вызывает apply_note_update с confirmed: true и тем же expected_hash.

5. Если файл изменился между шагами, MCP вернёт ошибку hash mismatch.

Все операции записи проходят validate_vault_path. Запрещены абсолютные пути, выход за пределы vault, запись не-.md файлов и доступ к исключённым папкам.

Память агента хранится в:

00_Meta/AI-System/
  role.md
  rules.md
  style.md
  projects.md
  mistakes.md
  examples.md

Для second-brain-vault действует соглашение: новые заметки должны иметь YAML-frontmatter, поля type, status, created, updated, tags, aliases, related, а related должен ссылаться хотя бы на один MOC.

Поиск v0.3

search_knowledge теперь использует ранжирование по нескольким полям:

• title и имя файла;

• aliases;

• tags;

• related;

• markdown content.

Запрос нормализуется по пробелам, дефисам, /, _ и wikilink-синтаксису, поэтому AI Sprint может находить AI-Sprint, ai/sprint и [[AI Sprint]]. В ответе есть score, matches и snippet, чтобы UI мог показать, почему заметка попала в выдачу.

Рекомендуемый flow для приложения:

search_knowledge
→ read_notes_batch top-K
→ find_related / get_note_metadata при необходимости
→ LLM context builder

Установка

git clone <repo-url> && cd sb-mcp
npm install
npm run build
npm test

Запуск

Stdio (локально, один клиент)

OBSIDIAN_VAULT_PATH=/path/to/vault node dist/index.js

HTTP (удалённо, несколько клиентов)

OBSIDIAN_VAULT_PATH=/path/to/vault \
MCP_AUTH_TOKEN=your-secret-token \
MCP_PORT=3100 \
node dist/index.js --http

Аутентификация

В HTTP-режиме задайте переменную MCP_AUTH_TOKEN для защиты доступа. Токен можно передать двумя способами:

1. Заголовок Authorization — для клиентов с поддержкой кастомных заголовков (Claude Code, API-клиенты):

Authorization: Bearer your-secret-token

2. Query-параметр — для клиентов без поддержки заголовков (Claude.ai, ChatGPT):

https://your-server/mcp?token=your-secret-token

Если MCP_AUTH_TOKEN не задан, сервер работает без аутентификации (не рекомендуется для публичных сетей).

Сгенерировать токен:

openssl rand -hex 32

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

Настройка клиентов

Claude Code (.mcp.json)

Stdio (локально):

{
  "mcpServers": {
    "secondbrain": {
      "command": "node",
      "args": ["/path/to/sb-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/vault"
      }
    }
  }
}

HTTP (удалённо):

{
  "mcpServers": {
    "secondbrain": {
      "type": "url",
      "url": "https://your-server/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-token"
      }
    }
  }
}

Claude.ai / ChatGPT

Используйте URL с токеном в query-параметре:

https://your-server/mcp?token=your-secret-token

systemd (деплой на сервер)

# /etc/systemd/system/secondbrain-mcp.service
[Unit]
Description=SecondBrain MCP Server
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/node /path/to/sb-mcp/dist/index.js --http
Environment=OBSIDIAN_VAULT_PATH=/path/to/vault
Environment=MCP_AUTH_TOKEN=your-secret-token
Environment=MCP_PORT=3100
Restart=on-failure

[Install]
WantedBy=multi-user.target

Контракт данных

• Исключённые папки: .git, .obsidian, node_modules, 99_Private, _attachments, mcp

• Типы заметок: project, area, resource, person, daily, moc, decision, inbox, about

• Статусы: active, paused, done, someday

• Frontmatter: YAML с полями type, status, created, updated, tags, aliases, related

• Связи: [[wikilinks]] + related: в frontmatter + backlinks + общие теги

• Оптимистическая блокировка: write-операции используют hash, чтобы UI применял только просмотренную пользователем версию файла