pebble-index-mcp

Puente MCP que expone una bóveda local de Obsidian y una instancia de Hermes Agent al sandbox MCP de doble clic del anillo inteligente Pebble Index 01. Las capturas de voz del anillo son enrutadas por el agente en la nube de la aplicación Pebble hacia las herramientas de este servidor, y la respuesta vuelve como notificación en el teléfono.

Arquitectura

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

• El servidor habla MCP sobre HTTP Streamable (SDK oficial mcp, FastMCP).

• Cada solicitud debe llevar un token de portador; cualquier otra cosa recibe 401.

• La protección contra reenlace de DNS de FastMCP está activada: los hosts permitidos son loopback más cualquier cosa listada en MCP_ALLOWED_HOSTS.

• La exposición pública es un túnel cloudflared hacia el puerto loopback; no se requiere infraestructura en la nube más allá de eso.

Related MCP server: mcp-obsidian

Componentes

Herramientas

• vault_search(query, max_results=5) — búsqueda de texto sin distinción de mayúsculas; devuelve líneas path: excerpt.

• vault_read(note_path, max_chars=1500) — lee el inicio de una nota.

• vault_append(note_path, text) — añade una línea con marca de tiempo - HH:MM text, creando la nota si es necesario.

• ask_hermes(question) — reenvía al servidor de API de Hermes; timeout de 60s con un reconocimiento honesto en caso de fallo.

Seguridad

• Autenticación: token de portador estático (MCP_BEARER_TOKEN), comparado en tiempo constante, requerido en cada solicitud. Un token vacío falla cerrado (todas las solicitudes 401) y registra una advertencia al inicio.

• Transporte: TLS termina en el borde del túnel; el origen escucha solo en loopback.

• Validación de host: la protección contra reenlace de DNS rechaza solicitudes cuyo encabezado Host no sea loopback o esté en MCP_ALLOWED_HOSTS.

• Sandbox de rutas: las herramientas de la bóveda resuelven todas las rutas y exigen que permanezcan dentro de la raíz de la bóveda; se rechazan escapes de symlink y las aperturas de archivos usan O_NOFOLLOW en el componente final. El sandbox protege contra uso accidental y remoto; un proceso local hostil que compita con un intercambio de directorio padre aún puede ganar (límite TOCTOU documentado — se asume que la bóveda es un directorio de un solo usuario de confianza).

• La configuración se lee una vez al importar: rotar el token de portador o cambiar los hosts permitidos requiere reiniciar el servicio.

• Secretos: la clave de API de Hermes y el token MCP viven en un archivo de entorno 0600 fuera de este repositorio, nunca en código, registros o commits.

• Nota de privacidad: las grabaciones enrutadas a través del sandbox de doble clic transitan por el agente en la nube de la aplicación Pebble. Las capturas de un solo clic permanecen en el dispositivo. Los pensamientos sensibles pertenecen al clic único.

Configuración (env)

HERMES_API_URL acepta cualquier endpoint de chat completions compatible con OpenAI, por lo que ask_hermes funciona directamente contra OpenRouter, Ollama, o cualquier otra API compatible — Hermes es solo el predeterminado.

Desarrollo

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

Ejecutar localmente: configura las variables de entorno anteriores y python -m pebble_index_mcp.server.

Despliegue

deploy/ contiene una plantilla de unidad de usuario de systemd y una plantilla de túnel cloudflared (hostname y credenciales completados en el host, no en este repositorio). Consulta docs/ring-checklist.md para la configuración del lado del teléfono y la matriz de pruebas.

Licencia

MIT — ver LICENSE.