pebble-index-mcp

MCP 桥接器，将本地 Obsidian 仓库和 Hermes Agent 实例暴露给 Pebble Index 01 智能戒指的双击 MCP 沙箱。来自戒指的语音捕获由 Pebble 应用的云代理路由到此服务器的工具中，答案以手机通知的形式返回。

架构

[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）。

• 每个请求都必须携带 bearer token；否则返回 401。

• FastMCP 的 DNS 重绑定保护已开启：允许的主机为 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) — 转发到 Hermes API 服务器；60 秒超时，未命中时给出坦诚的确认。

安全

• 认证：静态 bearer token（MCP_BEARER_TOKEN），常量时间比较，每个请求都必须携带。空 token 默认拒绝（所有请求返回 401）并在启动时记录警告。

• 传输：TLS 在隧道边缘终止；源服务仅监听 loopback。

• 主机校验：DNS 重绑定保护会拒绝 Host 头不是 loopback 或不在 MCP_ALLOWED_HOSTS 中的请求。

• 路径沙箱：仓库工具解析所有路径并要求它们保持在仓库根目录内；符号链接逃逸会被拒绝，文件打开时对最终组件使用 O_NOFOLLOW。沙箱可防范意外和远程滥用；但一个恶意的本地进程如果与父目录替换进行竞态，仍可能获胜（已记录的 TOCTOU 边界——仓库被假定为可信的单用户目录）。

• 配置在导入时只读取一次：轮换 bearer token 或更改允许的主机需要重启服务。

• 机密：Hermes API 密钥和 MCP token 存放在本仓库之外的 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。