pebble-index-mcp

MCP-мост, который открывает локальное хранилище Obsidian и экземпляр Hermes Agent для MCP-песочницы двойного нажатия умного кольца Pebble Index 01. Голосовые записи с кольца маршрутизируются облачным агентом приложения Pebble в инструменты этого сервера, а ответ возвращается в виде уведомления на телефоне.

Архитектура

[Index ring] → [Pebble app] → [Pebble cloud agent] → [this MCP server]
                                                        ├─ vault tools (local files)
                                                        └─ ask_hermes → Hermes API server

• Сервер говорит по MCP через Streamable HTTP (официальный SDK mcp, FastMCP).

• Каждый запрос должен содержать bearer-токен; всё остальное получает 401.

• Защита FastMCP от DNS-rebinding включена: разрешённые хосты — loopback плюс всё, что указано в MCP_ALLOWED_HOSTS.

• Публичный доступ — это туннель cloudflared к порту loopback; никакой облачной инфраструктуры, кроме этого, не требуется.

Related MCP server: mcp-obsidian

Компоненты

Инструменты

• vault_search(query, max_results=5) — текстовый поиск без учёта регистра; возвращает строки path: excerpt.

• vault_read(note_path, max_chars=1500) — читает начало заметки.

• vault_append(note_path, text) — добавляет строку с меткой времени - HH:MM text, создавая заметку при необходимости.

• ask_hermes(question) — пересылает на API-сервер Hermes; таймаут 60 секунд с честным подтверждением при промахе.

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

• Аутентификация: статический bearer-токен (MCP_BEARER_TOKEN), сравнение за постоянное время, требуется для каждого запроса. Пустой токен закрывает доступ (все запросы 401) и логирует предупреждение при запуске.

• Транспорт: TLS завершается на границе туннеля; источник слушает только loopback.

• Проверка хоста: защита от DNS-rebinding отклоняет запросы, у которых заголовок Host не является loopback или не входит в MCP_ALLOWED_HOSTS.

• Песочница путей: инструменты хранилища разрешают все пути и требуют, чтобы они оставались внутри корня хранилища; побег через симлинки отклоняется, а при открытии файлов используется O_NOFOLLOW для последнего компонента. Песочница защищает от случайного и удалённого неправильного использования; враждебный локальный процесс, который гоняется за подменой родительского каталога, всё ещё может выиграть (документированная граница TOCTOU — предполагается, что хранилище является доверенным однопользовательским каталогом).

• Конфигурация читается один раз при импорте: ротация bearer-токена или изменение разрешённых хостов требует перезапуска службы.

• Секреты: ключ API Hermes и MCP-токен хранятся в env-файле с правами 0600 вне этого репозитория, никогда в коде, логах или коммитах.

• Примечание о конфиденциальности: записи, маршрутизируемые через песочницу двойного нажатия, проходят через облачный агент приложения Pebble. Записи одиночного нажатия остаются на устройстве. Чувствительные мысли принадлежат одиночному нажатию.

Конфигурация (env)

HERMES_API_URL принимает любую OpenAI-совместимую конечную точку chat completions, поэтому ask_hermes работает напрямую с OpenRouter, Ollama или любым другим совместимым API — Hermes — это просто значение по умолчанию.

Разработка

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest -v

Локальный запуск: задайте переменные окружения выше и выполните python -m pebble_index_mcp.server.

Развёртывание

deploy/ содержит шаблон пользовательского юнита systemd и шаблон туннеля cloudflared (имя хоста и учётные данные заполняются на хосте, а не в этом репозитории). См. docs/ring-checklist.md для настройки на стороне телефона и матрицы тестов.

Лицензия

MIT — см. LICENSE.