pebble-index-mcp

ローカルの Obsidian Vault と Hermes Agent インスタンスを、Pebble Index 01 スマートリングのダブルクリック MCP サンドボックスに公開する MCP ブリッジです。リングからの音声キャプチャは Pebble アプリのクラウドエージェントによってこのサーバーのツールにルーティングされ、回答はスマートフォンへの通知として返ってきます。

Architecture

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

• サーバーは Streamable HTTP 上で MCP を話します (公式 mcp SDK、FastMCP)。

• すべてのリクエストはベアラートークンを必須とし、トークンがないものは 401 になります。

• FastMCP の DNS リバインディング保護は有効です。許可されるホストはループバックと、MCP_ALLOWED_HOSTS に列挙されたものです。

• 外部公開はループバックポートへの cloudflared トンネルで行い、それ以上のクラウドインフラストラクチャは必要ありません。

Related MCP server: mcp-obsidian

Components

Tools

• vault_search(query, max_results=5) — 大文字と小文字を区別しないテキスト検索。path: 抜粋 の行を返します。

• vault_read(note_path, max_chars=1500) — ノートの先頭を読み取ります。

• vault_append(note_path, text) — タイムスタンプ付きの - HH:MM text 行を追記します。必要に応じてノートを作成します。

• ask_hermes(question) — Hermes API サーバーに転送します。60 秒のタイムアウト時は、応答が得られなかったことを誠実に伝えます。

Security

• 認証: 静的なベアラートークン (MCP_BEARER_TOKEN) を定数時間比較で必須確認します。空のトークンはフェイルクローズ (全リクエスト 401) となり、起動時に警告がログされます。

• Transport: TLS はトンネルのエッジで終端され、オリジンはループバックのみで待ち受るします。

• ホスト検証: Host ヘッダーがループバックでも MCP_ALLOWED_HOSTS にも該当しないリクエストは、DNS リバインディング保護が拒否します。

• パスサンドボックス: Vault ツールはすべてのパスを解決し、Vault のルート内に収まることを要求します。シンボリックリンクのエスケープは拒否され、ファイルオープンでは最終コンポーネントに O_NOFOLLOW が使用されます。サンドボックスは偶発的・遠隔からの誤用を防ぎますが、親ディレクトリの差し替えを競合させる悪意のあるローカルプロセスには依然として制まずがあります (文書化された TOCTOU 境界 — Vault は信頼された単一ユーザーディレクトリとみなされます)。

• 設定は import 時に一度だけ読み込みます。ベアラートークンのローテーションや許可ホストの変更はサービス再起動が必要です。

• シークレット: Hermes API キーと MCP トークンは、このリポジトリ外の権限 0600 の env ファイルに置かれます。コード・ログ・コミットに含めることは絶対にありません。

• プライバシー: ダブルクリックサンドボックス経由の録音は、Pebble アプリのクラウドエージェントを通過します。シングルクリックのキャプチャは端末上に留まります。機密に近い思考を扱う操作はシングルクリックで行ってください。

Configuration (env)

HERMES_API_URL は OpenAI 互換の chat completions エンドポイントを任意で受け付けられるため、ask_hermes は OpenRouter 直接、Ollama、その他の互換 API に対しても動作します。Hermes は単なるデフォルトです。

Development

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

ローカルで実行するには、上記の環境変数を設定し、python -m pebble_index_mcp.server を使用します。

Deployment

deploy/ には systemd ユーザーユニットのテンプレートと cloudflared トンネルのテンプレートが含まれています (ホスト名と資格情報はこのリポジトリではなくホスト側で記入します)。docs/ring-checklist.md でスマートフォン側のセットアップとテストマトリックスを確認してください。

License

MIT — LICENSE を参照してください。