🌐 **Language / 言語**: [English](../../README.md) | [简体中文](README_ZH.md) | [繁體中文](README_TW.md) | [Español](README_ES.md) | [Français](README_FR.md) | [Português](README_PT.md) | [Deutsch](README_DE.md) | [Русский](README_RU.md) | [日本語](README_JA.md) | [한국어](README_KO.md) | [हिन्दी](README_HI.md)

[![Python](https://img.shields.io/badge/python-3.13+-blue?style=flat&logo=python&logoColor=white)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green?style=flat)](../../LICENSE)
[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-blueviolet?style=flat)](https://modelcontextprotocol.io/)
[![GitHub stars](https://img.shields.io/github/stars/rmc8/py-obsidian-tools?style=flat)](https://github.com/rmc8/py-obsidian-tools/stargazers)
[![GitHub issues](https://img.shields.io/github/issues/rmc8/py-obsidian-tools?style=flat)](https://github.com/rmc8/py-obsidian-tools/issues)
[![Last Commit](https://img.shields.io/github/last-commit/rmc8/py-obsidian-tools?style=flat)](https://github.com/rmc8/py-obsidian-tools/commits)

# py-obsidian-tools

MCP-сервер для взаимодействия с Obsidian через плагин сообщества Local REST API.

## Компоненты

### Инструменты

Сервер реализует множество инструментов для взаимодействия с Obsidian:

| Инструмент | Описание |
|------------|----------|
| `list_notes` | Список всех заметок в хранилище или определённой директории |
| `read_note` | Чтение содержимого определённой заметки |
| `search_notes` | Поиск заметок, содержащих определённый текст |
| `create_note` | Создание новой заметки с опциональным frontmatter |
| `update_note` | Обновление (замена) всего содержимого заметки |
| `append_note` | Добавление содержимого в конец заметки |
| `delete_note` | Удаление заметки из хранилища |
| `patch_note` | Обновление определённого раздела (заголовок/блок/frontmatter) |
| `list_commands` | Список всех доступных команд Obsidian |
| `execute_command` | Выполнение команды Obsidian |
| `batch_read_notes` | Чтение нескольких заметок одновременно |
| `complex_search` | Поиск с использованием JsonLogic-запросов для расширенной фильтрации |
| `get_recent_changes` | Получение недавно изменённых файлов (требуется плагин Dataview) |
| `get_periodic_note` | Получение сегодняшней ежедневной/еженедельной/ежемесячной заметки (требуется плагин Periodic Notes) |
| `open_note` | Открытие заметки в интерфейсе Obsidian |
| `get_active_note` | Получение текущей активной заметки |
| `update_active_note` | Обновление содержимого активной заметки |
| `append_active_note` | Добавление содержимого к активной заметке |
| `patch_active_note` | Обновление определённого раздела активной заметки |
| `delete_active_note` | Удаление текущей активной заметки |
| `server_status` | Получение статуса сервера Obsidian Local REST API |
| `dataview_query` | Выполнение Dataview DQL-запросов (требуется плагин Dataview) |
| `vector_search` | Семантический поиск на естественном языке (требуется vector extras) |
| `find_similar_notes` | Поиск заметок, похожих на указанную (требуется vector extras) |
| `vector_status` | Получение статуса индекса векторного поиска (требуется vector extras) |

### Примеры промптов

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

Вы можете использовать промпты вроде этих:
- "Перечисли все заметки в папке 'Daily'"
- "Найди все заметки, упоминающие 'Проект X', и сделай краткое изложение"
- "Создай новую заметку под названием 'Заметки со встречи' с содержанием нашего обсуждения"
- "Добавь 'TODO: Проверить PR' в мою ежедневную заметку"
- "Получи содержимое активной заметки и дай критику"
- "Найди все markdown-файлы в папке Work, используя complex search"
- "Поиск заметок о машинном обучении с помощью семантического поиска"
- "Найди заметки, похожие на мой план проекта"
- "Выполни Dataview-запрос, чтобы перечислить все заметки с тегом #project"
- "Получи сегодняшнюю ежедневную заметку"
- "Обнови раздел 'Задачи' активной заметки"
- "Проверь статус сервера API Obsidian"

## Конфигурация

### Ключ API Obsidian REST

Есть два способа настроить окружение с ключом API Obsidian REST.

1. Добавить в конфигурацию сервера (рекомендуется)

```json
{
  "mcpServers": {
    "obsidian-tools": {
      "command": "uvx",
      "args": ["py-obsidian-tools"],
      "env": {
        "OBSIDIAN_API_KEY": "<your_api_key_here>",
        "OBSIDIAN_HOST": "127.0.0.1",
        "OBSIDIAN_PORT": "27124"
      }
    }
  }
}
```

2. Создать файл `.env` в рабочей директории со следующими обязательными переменными:

```
OBSIDIAN_API_KEY=your_api_key_here
OBSIDIAN_HOST=127.0.0.1
OBSIDIAN_PORT=27124
```

Примечание:
- API-ключ можно найти в настройках плагина Obsidian (Настройки > Local REST API > Безопасность)
- Порт по умолчанию — 27124
- Хост по умолчанию — 127.0.0.1 (localhost)

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

### Установка

#### Obsidian REST API

Вам нужен работающий плагин сообщества Obsidian REST API: https://github.com/coddingtonbear/obsidian-local-rest-api

Установите и включите его в настройках, затем скопируйте API-ключ.

#### Claude Desktop

На MacOS: `~/Library/Application\ Support/Claude/claude_desktop_config.json`

На Windows: `%APPDATA%/Claude/claude_desktop_config.json`

**Рекомендуется: Установка из PyPI (uvx)**

```json
{
  "mcpServers": {
    "obsidian-tools": {
      "command": "uvx",
      "args": ["py-obsidian-tools"],
      "env": {
        "OBSIDIAN_API_KEY": "<your_api_key_here>",
        "OBSIDIAN_HOST": "127.0.0.1",
        "OBSIDIAN_PORT": "27124"
      }
    }
  }
}
```

<details>
  <summary>Конфигурация для разработки/неопубликованных серверов</summary>

```json
{
  "mcpServers": {
    "obsidian-tools": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/py-obsidian-tools",
        "run",
        "py-obsidian-tools"
      ],
      "env": {
        "OBSIDIAN_API_KEY": "<your_api_key_here>"
      }
    }
  }
}
```
</details>

<details>
  <summary>Установка с GitHub (uvx)</summary>

```json
{
  "mcpServers": {
    "obsidian-tools": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/rmc8/py-obsidian-tools",
        "py-obsidian-tools"
      ],
      "env": {
        "OBSIDIAN_API_KEY": "<your_api_key_here>"
      }
    }
  }
}
```
</details>

## Векторный поиск (Опционально)

Функция семантического поиска с использованием ChromaDB. Эта функция позволяет выполнять запросы на естественном языке по всему вашему хранилищу.

### Установка

**Используя uvx (рекомендуется)**:

```bash
# Установка не требуется - запуск напрямую через uvx
uvx --from 'py-obsidian-tools[vector]' pyobsidian-index full --verbose

# С внешними провайдерами эмбеддингов
uvx --from 'py-obsidian-tools[vector-openai]' pyobsidian-index full --verbose
uvx --from 'py-obsidian-tools[vector-google]' pyobsidian-index full --verbose
uvx --from 'py-obsidian-tools[vector-cohere]' pyobsidian-index full --verbose
```

**Используя uv (для разработки)**:

```bash
# Базовая (локальные эмбеддинги - API-ключ не требуется)
uv sync

# С внешними провайдерами эмбеддингов
uv sync --extra vector-openai
uv sync --extra vector-google
uv sync --extra vector-cohere
uv sync --extra vector-all

# Запуск индексатора
uv run pyobsidian-index full --verbose
```

**Используя pip**:

```bash
# Базовая (локальные эмбеддинги - API-ключ не требуется)
pip install "py-obsidian-tools[vector]"

# С внешними провайдерами эмбеддингов
pip install "py-obsidian-tools[vector-openai]"
pip install "py-obsidian-tools[vector-google]"
pip install "py-obsidian-tools[vector-cohere]"
pip install "py-obsidian-tools[vector-all]"
```

### Создание индекса

Перед использованием векторного поиска необходимо создать индекс вашего хранилища:

```bash
# Используя uvx (рекомендуется - установка не требуется)
uvx --from 'py-obsidian-tools[vector]' pyobsidian-index full --verbose

# Используя uv (для разработки)
uv run pyobsidian-index full --verbose

# Или если установлено через pip
pyobsidian-index full --verbose
```

> **Примечание**: Команда `pyobsidian-index` требует extras `[vector]`. При использовании uvx необходимо включить `[vector]` в спецификацию пакета. Выполнение `uvx --from py-obsidian-tools pyobsidian-index` без `[vector]` завершится ошибкой.

### CLI-команды

```bash
# Используя uvx
uvx --from 'py-obsidian-tools[vector]' pyobsidian-index <команда>

# Используя uv (для разработки)
uv run pyobsidian-index <команда>

# Используя установку pip
pyobsidian-index <команда>
```

| Команда | Описание |
|---------|----------|
| `full` | Индексировать все заметки в хранилище |
| `update` | Инкрементальное обновление (только новые/изменённые заметки) |
| `clear` | Очистить весь индекс |
| `status` | Показать статус индекса |

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

```bash
VECTOR_PROVIDER=default          # default, ollama, openai, google, cohere
VECTOR_CHROMA_PATH=~/.obsidian-vector
VECTOR_CHUNK_SIZE=512

# Для Ollama
VECTOR_OLLAMA_HOST=http://localhost:11434
VECTOR_OLLAMA_MODEL=nomic-embed-text

# Для OpenAI
VECTOR_OPENAI_API_KEY=sk-xxx
VECTOR_OPENAI_MODEL=text-embedding-3-small

# Для Google
VECTOR_GOOGLE_API_KEY=xxx
VECTOR_GOOGLE_MODEL=embedding-001

# Для Cohere
VECTOR_COHERE_API_KEY=xxx
VECTOR_COHERE_MODEL=embed-multilingual-v3.0
```

### Провайдеры эмбеддингов

| Провайдер | Модель | Оптимально для |
|-----------|--------|----------------|
| default | all-MiniLM-L6-v2 | Быстрый, бесплатный, полностью локальный |
| ollama | nomic-embed-text | Высокое качество, локальный |
| openai | text-embedding-3-small | Лучшее качество, многоязычный |
| google | embedding-001 | Интеграция с Google AI |
| cohere | embed-multilingual-v3.0 | Специализация на многоязычности |

## Разработка

### Сборка

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

1. Синхронизация зависимостей и обновление файла блокировки:
```bash
uv sync
```

### Отладка

Поскольку MCP-серверы работают через stdio, отладка может быть сложной. Для лучшего опыта отладки настоятельно рекомендуем использовать [MCP Inspector](https://github.com/modelcontextprotocol/inspector).

Вы можете запустить MCP Inspector через `npx` с помощью этой команды:

```bash
npx @modelcontextprotocol/inspector uv --directory /path/to/py-obsidian-tools run py-obsidian-tools
```

После запуска Inspector отобразит URL, который вы можете открыть в браузере для начала отладки.

Вы также можете просматривать логи сервера (если настроены) или использовать стандартное логирование Python.
