From cccdca14692227192dbdb4d504c30a4bab9fd721 Mon Sep 17 00:00:00 2001 From: Phil Date: Wed, 11 Nov 2026 08:29:54 -0700 Subject: [PATCH] Mac: Karakeep MCP server for Hermes Hermes can search and read bookmarks, create them, tag them and add them to lists from Telegram. Per Karakeep's MCP README and Hermes's MCP docs: - the official server image (pinned 0.34.1) runs in a throwaway Podman container (`podman run -i --rm`), started on first use and stopped after 10 idle minutes; - only search/read/create/tag/add-to-list tools are registered (no update or delete); trust: full because Karakeep doesn't mark its search tools read-only; - the API key is in the vault, written to ~/.hermes/.env via the new hermes_env_secrets, and passed into the container by name. Co-Authored-By: Claude Opus 5.5 --- group_vars/mac/main.yml | 42 +++++++++++++++++++++++++++++ roles/mac/README.md | 5 ++++ roles/mac/tasks/hermes-settings.yml | 13 +++++++++ 3 files changed, 60 insertions(+) diff --git a/group_vars/mac/main.yml b/group_vars/mac/main.yml index 5d03a32..b9d53dd 100644 --- a/group_vars/mac/main.yml +++ b/group_vars/mac/main.yml @@ -85,6 +85,48 @@ hermes_settings: delegation.provider: openrouter delegation.model: deepseek/deepseek-v4.1-flash + mcp_servers.karakeep: "{{ hermes_mcp_karakeep }}" + +# MCP servers. Each stdio server runs in a throwaway Podman container (not on +# the Mac itself); secrets come from ~/.hermes/.env (hermes_env_secrets) and +# are passed to the container by name, never on the command line. +hermes_mcp_podman_args: [run, -i, --rm] + +# Karakeep (bookmarks): search/read, create, tag, add to list. No update or +# delete tools are registered. trust: full because Karakeep doesn't mark its +# search tools read-only, so "untrusted" would ask before every search. +# github.com/karakeep-app/karakeep/tree/main/apps/mcp +hermes_karakeep_mcp_image: ghcr.io/karakeep-app/karakeep-mcp:0.34.1 +hermes_mcp_karakeep: + command: /opt/podman/bin/podman + args: "{{ hermes_mcp_podman_args + ['-e', 'KARAKEEP_API_ADDR', '-e', 'KARAKEEP_API_KEY', hermes_karakeep_mcp_image] }}" + env: + KARAKEEP_API_ADDR: "https://{{ subdomains.bookmarks }}" + KARAKEEP_API_KEY: "${KARAKEEP_API_KEY}" + lazy: true # start the container on first use + idle_timeout_seconds: 600 # and stop it after 10 idle minutes + tools: + include: + - search-bookmarks + - get-bookmark + - get-bookmark-content + - get-bookmark-lists + - get-lists + - get-list + - get-list-bookmarks + - get-tags + - get-tag + - get-tag-bookmarks + - create-bookmark + - attach-tag-to-bookmark + - add-bookmark-to-list + resources: false + prompts: false + +# Secrets written to ~/.hermes/.env (single-quoted), from the vault. +hermes_env_secrets: + KARAKEEP_API_KEY: "{{ vault_cogitator02.karakeep_api_key }}" + # Keys `hermes config set` refuses without --force although Hermes reads them # (agent.reasoning_effort: hermes-agent #140221). hermes_settings_force: [agent.reasoning_effort] diff --git a/roles/mac/README.md b/roles/mac/README.md index 2b365dc..ab8d39a 100644 --- a/roles/mac/README.md +++ b/roles/mac/README.md @@ -32,6 +32,11 @@ Manages cogitator-02, an Apple Silicon Mac on the tailnet (`mac.yml`, cron on GLM-5.3 Flash, subagents on DeepSeek V4.1 Flash, `/model` aliases. Keys in `hermes_settings_force` are set with `--force` (Hermes reads `agent.reasoning_effort` but `config set` refuses it, hermes-agent #140221). +- **MCP servers and secrets** (also tag `hermes-settings`): MCP servers are + `mcp_servers.` entries in `hermes_settings`, each running in a + throwaway Podman container. Secrets they need are in `hermes_env_secrets` + (from the vault) and written to `~/.hermes/.env`. Today: Karakeep, with + only search/read/create/tag tools registered. - **Podman VM** (tag `podman`): a launchd job (`local.podman-machine`) that starts the VM running Hermes's sandbox at login, and `podman_machine_memory` for its size. A resize stops the VM and starts it again through that job. diff --git a/roles/mac/tasks/hermes-settings.yml b/roles/mac/tasks/hermes-settings.yml index d9ada01..711574c 100644 --- a/roles/mac/tasks/hermes-settings.yml +++ b/roles/mac/tasks/hermes-settings.yml @@ -1,3 +1,16 @@ +# Secrets go in first, so servers and settings that reference them +# (${VAR}) find them when the gateway restarts. +- name: Secrets in Hermes's .env + ansible.builtin.lineinfile: + path: "{{ hermes_env }}" + regexp: "^{{ item.key }}=" + line: "{{ item.key }}='{{ item.value }}'" + mode: "0600" + loop: "{{ hermes_env_secrets | default({}) | dict2items }}" + no_log: true + diff: false + notify: [Restart Hermes gateway, Restart Hermes dashboard] + # `hermes config get` prints the value as YAML, so it's compared # structurally; `hermes config set` takes JSON for lists and booleans. # Settings are always set explicitly: for a key that isn't in config.yaml,