feat(mcp-catalog): add Somvia Apple Health MCP

[xukecheng]

What does this PR do?

Adds Somvia to the Nous-reviewed MCP Catalog so Hermes users can discover and install its hosted Apple Health MCP from the built-in picker.

Somvia is a hosted, closed-source service: its iOS app handles HealthKit permission and sync, while https://somvia.app/mcp exposes eight read-only health_* tools for daily metrics, sleep stages, workout summaries, splits, and bounded time series. The manifest discloses the iPhone and Pro prerequisites, pins the current reviewed tool set, and documents both supported authentication paths.

This PR also tightens the existing Catalog installer contract for manifests that explicitly declare tools.default_enabled: after a successful probe, Hermes now retains the confirmed selection in tools.include even when it equals every tool currently reported by the server. That keeps tools added by the server later opt-in. Entries without manifest defaults retain the existing all-selected/no-filter behavior.

Dual auth by design

Somvia's /mcp endpoint supports both:

• native MCP OAuth 2.1 for interactive clients; and
• an app-issued som_ Bearer token for headless, VPS, or unattended agents.

A version 1 Hermes Catalog manifest selects one auth.type for its install flow rather than presenting an auth-method chooser. This entry uses auth.type: oauth, which current Hermes main already supports. On first connection Hermes can discover Somvia's authorization server, register a client, and open the browser flow.

Bearer support remains available through Hermes' existing manual MCP configuration with Authorization: Bearer ${SOMVIA_ACCESS_TOKEN}. The manifest's post_install links the headless guide. This PR does not depend on the separate Catalog API-key header changes in #59586 or #67682.

Related Issue

No separate Somvia issue exists; I searched open and closed issues and PRs before submitting.

Type of Change

• ✨ New feature (non-breaking change that adds functionality)

Changes Made

• optional-mcps/somvia/manifest.yaml
  • registers the hosted Streamable HTTP endpoint;
  • uses native MCP OAuth for the built-in Catalog flow;
  • retains the app-issued Bearer path for manual headless configuration;
  • defaults to the eight currently exposed read-only tools;
  • documents setup, subscription, first-sync, rotation, and deletion behavior.
• hermes_cli/mcp_catalog.py
  • treats an explicitly declared tools.default_enabled list as a persistent opt-in boundary;
  • retains the current no-filter behavior when a manifest does not declare defaults.
• tests/hermes_cli/test_mcp_catalog.py
  • covers a successful interactive probe where all declared defaults are selected;
  • protects the existing no-default compatibility path.
• website/docs/user-guide/features/mcp.md
  • documents when an all-selected install remains pinned versus filter-free.

How to Test

1. Run the focused Catalog suite:

   scripts/run_tests.sh tests/hermes_cli/test_mcp_catalog.py -q

   Local result on current main: 20 passed, 0 failed.

2. Parse the shipped manifest with current main. _build_server_config() returns:

   {"url": "https://somvia.app/mcp", "auth": "oauth"}

3. Verify OAuth discovery:

   • GET https://somvia.app/.well-known/oauth-protected-resource/mcp
     returns the protected resource and authorization_servers: ["https://somvia.app"].
   • GET https://somvia.app/.well-known/oauth-authorization-server
     advertises /authorize, /token, /register, PKCE, authorization-code, and refresh-token support.

4. Run:

   hermes mcp install somvia

   Complete Sign in with Apple in the browser, restart the Hermes session, then call health_connection_status plus one data-returning read-only tool. Confirm that mcp_servers.somvia.tools.include contains the eight reviewed tools after accepting the pre-checked list.

5. For a headless verification, follow https://somvia.app/hermes-apple-health and configure the app-issued som_ token as an explicit Bearer header.

The Somvia maintainer has verified the service's OAuth path with Claude and the manual Bearer path with Hermes. The Catalog OAuth config path is covered by Hermes' existing Catalog tests; this PR adds the successful-probe regression requested in review.

Public boundary checks performed while preparing this PR:

• https://somvia.app/hermes-apple-health → 200
• https://apps.apple.com/app/id6786936154 → 200
• OAuth protected-resource metadata → 200 application/json
• OAuth authorization-server metadata → 200 application/json
• unauthenticated MCP initialize POST → 401 application/json

No access token or personal health data is included in this PR or its test output.

Security and privacy notes

• Every catalog-default tool is annotated read-only by the MCP server.
• The iOS app syncs only the Health categories and history window selected by the user.
• Interactive Catalog users authenticate through OAuth; Hermes manages the resulting credentials.
• For the optional headless path, the plaintext som_ token is shown to the user for agent setup; Somvia stores only its SHA-256 hash server-side.
• Refreshing the app-issued token invalidates the previous token. Deleting the Somvia account deletes synced Health data and invalidates OAuth access and app-issued tokens.
• Somvia is not a medical device and does not provide diagnosis or treatment.

Checklist

Code

• I've read the Contributing Guide.
• My commits follow Conventional Commits.
• I searched existing issues and PRs before submitting.
• The PR contains the focused manifest plus the minimal installer semantics, tests, and docs required to preserve its reviewed tool boundary.
• The focused Catalog suite passes: 20/20.
• Added successful-probe regression coverage and protected the existing no-default behavior.
• Tested on macOS 26.4.1; the manifest is platform-neutral remote HTTP configuration.

Documentation & Housekeeping

• Setup guidance is included in post_install and the linked public guide.
• Catalog tool-selection semantics are documented in website/docs/user-guide/features/mcp.md.
• cli-config.yaml.example — N/A; no config key was added or changed.
• CONTRIBUTING.md / AGENTS.md — N/A; contributor workflow is unchanged.
• Cross-platform impact considered — remote URL, native MCP OAuth, optional manual Bearer header, and platform-neutral config persistence only.
• Tool descriptions/schemas — N/A; this PR does not change the Somvia MCP tool schemas.

Prepared with Codex assistance. The manifest, live OAuth metadata, public boundaries, Catalog semantics, and focused tests were reviewed during preparation; the Somvia maintainer verified Claude OAuth and Hermes Bearer connectivity.

[teknium1]

Thanks for using the MCP catalog rather than expanding the core tool surface.

Problems

• optional-mcps/somvia/manifest.yaml:25 says newly added server tools stay opt-in, but all eight known tools are listed under default_enabled. On a successful interactive probe, hermes_cli/mcp_catalog.py:681-687 treats selecting every probed tool as "no filter" and explicitly permits future tools to auto-enable. Therefore the manifest does not preserve the reviewed eight-tool boundary it describes.

Suggested changes

• Add a manifest/install path that persists tools.include for a declared reviewed default set even when it currently equals the complete probed set, and add a successful-probe regression test in tests/hermes_cli/test_mcp_catalog.py.

Automated hermes-sweeper review.

[teknium1]

This promise is not upheld when the server currently exposes exactly these eight tools: hermes_cli/mcp_catalog.py:681-687 clears tools.include when all probed tools are selected, which explicitly auto-enables future upstream tools. Please add installer/manifest semantics that retain an explicit reviewed include list in this case.

[xukecheng]

Fixed in a2d1e46. When a manifest explicitly declares tools.default_enabled, the successful interactive path now persists the confirmed selection as tools.include even if it covers every probed tool, so future server tools remain opt-in. Manifests without defaults retain the existing no-filter behavior. Added regression coverage for both paths; the focused Catalog suite passes 20/20.