hermes-mcp 0.4.0__tar.gz

hermes_mcp-0.4.0/.env.example

@@ -0,0 +1,53 @@
+# --- REQUIRED -----------------------------------------------------------------
+#
+# Static OAuth 2.1 client credentials used by any MCP client (Claude Desktop's
+# Custom Connector, OpenAI Codex CLI, Cursor, ...) to authenticate against
+# this bridge. Generate a fresh pair with:
+#   hermes-mcp mint-client
+# Paste the same values into your MCP client's connector / mcp.json / config.toml.
+
+OAUTH_CLIENT_ID=
+OAUTH_CLIENT_SECRET=
+
+# Public HTTPS URL where this server is reachable (your tunnel hostname).
+# Used as the OAuth issuer and to derive the resource-server URL.
+# Must be HTTPS, except http://localhost is allowed for local testing.
+OAUTH_ISSUER_URL=
+
+# Bearer token for the local Hermes Agent gateway's OpenAI-compatible API
+# (the `API_SERVER_KEY` value from ~/.hermes/.env).
+HERMES_API_KEY=
+
+# --- OPTIONAL -----------------------------------------------------------------
+
+# Base URL of the Hermes gateway. Default: http://127.0.0.1:8642
+# HERMES_API_URL=http://127.0.0.1:8642
+
+# Model identifier for /v1/chat/completions. Default: hermes-agent
+# HERMES_MODEL=hermes-agent
+
+# Bind address. Default 127.0.0.1 — your tunnel (cloudflared/ngrok) reaches it.
+# Do NOT bind to 0.0.0.0 unless you understand the implications.
+# BIND_HOST=127.0.0.1
+
+# Port. Default 8765.
+# BIND_PORT=8765
+
+# Max wall-clock seconds for a single hermes_ask call. Default 300.
+# HERMES_REQUEST_TIMEOUT_SECONDS=300
+
+# Comma-separated list of additional Host header values to accept (typically
+# your public tunnel hostname). 127.0.0.1, localhost, and ::1 are always
+# allowed. MCP's DNS-rebinding protection uses this list.
+# MCP_ALLOWED_HOSTS=hermes.example.com
+
+# Comma-separated list of OAuth redirect-URI custom schemes to accept.
+# Each MCP client uses its own scheme: Claude → claude/claudeai, Cursor →
+# cursor, Continue (VSCode) → vscode, etc. `https` and `http`-on-localhost
+# are always accepted as a security baseline. Default covers the clients
+# we test against. Add to this list (REPLACING the default) for new clients.
+# OAUTH_ALLOWED_REDIRECT_SCHEMES=claude,claudeai,cursor
+
+# Log level (DEBUG / INFO / WARNING / ERROR / CRITICAL). Default INFO.
+# DEBUG enables logging of full prompt bodies — leave at INFO unless debugging.
+# LOG_LEVEL=INFO

hermes_mcp-0.4.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @mlennie

hermes_mcp-0.4.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,53 @@
+---
+name: Bug report
+about: Something isn't working
+labels: bug
+---
+
+## Versions
+
+| Component | Version |
+|---|---|
+| hermes-mcp | |
+| Hermes Agent (`hermes --version`) | |
+| Python (`python --version`) | |
+| OS / distro | |
+
+## Setup
+
+- **Tunnel type:** <!-- cloudflared / ngrok / other / none (local only) -->
+- **Claude client:** <!-- Claude Desktop / Claude Mobile / API direct -->
+- **HERMES_TOOLSETS set?** <!-- yes (list them) / no -->
+- **Custom HERMES_BIN?** <!-- yes / no (using PATH) -->
+
+## What happened
+
+<!-- What did you observe? -->
+
+## What you expected
+
+<!-- What should have happened instead? -->
+
+## Steps to reproduce
+
+1.
+2.
+3.
+
+## Doctor output
+
+```
+# Run: hermes-mcp doctor
+# Paste the full output here
+```
+
+## Relevant logs
+
+```
+# Run: LOG_LEVEL=DEBUG hermes-mcp serve  (or journalctl -u hermes-mcp -n 100)
+# Redact your bearer token and any sensitive prompt content before pasting.
+```
+
+## What you've already tried
+
+<!-- Saves everyone time -->

hermes_mcp-0.4.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,29 @@
+---
+name: Feature request
+about: Suggest a new capability
+labels: enhancement
+---
+
+## Problem
+
+<!-- What friction or limitation are you hitting? Be concrete — "I want X" is less useful than "I'm trying to do Y and I can't because Z." -->
+
+## Proposed solution
+
+<!-- What would you like hermes-mcp to do differently? -->
+
+## Alternatives you've considered
+
+<!-- Other approaches, workarounds, or reasons they don't work for you. -->
+
+## Security considerations
+
+<!-- hermes-mcp sits between Claude and your local machine. Does this change:
+  - the authentication surface (new endpoints, new auth paths)?
+  - what Hermes can be asked to do?
+  - what gets logged, stored, or transmitted?
+If yes, describe the impact. If you're unsure, say so — we'll work through it together. -->
+
+## Does this add a new MCP tool?
+
+<!-- The single-tool design (hermes_ask only) is intentional — it keeps the attack surface small and puts authorization in Hermes's hands. If you're proposing a new tool, explain why hermes_ask can't cover it. -->

hermes_mcp-0.4.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,33 @@
+## What this does
+
+<!-- One paragraph. What changes and why. Link the issue if there is one (Fixes #NNN). -->
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Security fix
+- [ ] Refactor (no behavior change)
+- [ ] Docs / config only
+
+## Security impact
+
+<!-- hermes-mcp is a thin auth+subprocess wrapper. Before merging, confirm:
+  - Does this change the authentication or bearer-token handling? If yes, describe.
+  - Does this change how argv is constructed for the hermes subprocess? If yes, confirm shell=True is still absent.
+  - Does this add logging of prompt content above DEBUG level? It must not.
+  - Does this add any outbound network call from hermes-mcp itself? It must not (no telemetry policy).
+If none of the above apply, write "None." -->
+
+## Testing done
+
+- [ ] `ruff check .` passes
+- [ ] `ruff format --check .` passes
+- [ ] `mypy src/` passes
+- [ ] `pytest` passes
+- [ ] Manually tested against a real Hermes installation *(required if touching `hermes_client.py` or `server.py`)*
+
+## Checklist
+
+- [ ] `CHANGELOG.md` updated under `Unreleased`
+- [ ] Breaking changes (env var renames, CLI flag changes) noted in `CHANGELOG.md`

hermes_mcp-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install dependencies
+        run: uv pip install --system -e ".[dev]"
+
+      - name: Lint (ruff)
+        run: ruff check .
+
+      - name: Format check (ruff)
+        run: ruff format --check .
+
+      - name: Type check (mypy)
+        run: mypy src/
+
+      - name: Tests (pytest)
+        run: pytest

hermes_mcp-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,107 @@
+name: Release
+
+# Fires when a `vX.Y.Z` tag is pushed. Builds the wheel/sdist once, then
+# publishes to PyPI via Trusted Publishing (OIDC, no API token stored) and
+# creates a GitHub Release with the matching CHANGELOG section.
+#
+# One-time setup on PyPI (per project, https://pypi.org/manage/project/hermes-mcp/settings/publishing/):
+#   - Owner:               mlennie
+#   - Repository name:     hermes-mcp
+#   - Workflow filename:   release.yml
+#   - Environment name:    (leave blank, or set to `release` if you also
+#                          create a GitHub environment with that name)
+#
+# If trusted publishing is not configured on PyPI yet, the `publish-pypi`
+# job will fail with a clear error pointing at the PyPI settings page —
+# the `github-release` job runs independently and still succeeds.
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build:
+    name: Build wheel + sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build dependencies
+        run: pip install --upgrade build
+
+      - name: Verify tag matches package version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          pkg=$(python -c "import tomllib, pathlib; \
+            print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
+          if [ "$tag" != "$pkg" ]; then
+            echo "::error::Tag v$tag does not match pyproject.toml version $pkg"
+            exit 1
+          fi
+
+      - name: Build
+        run: python -m build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish via trusted publishing
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Extract release notes from CHANGELOG
+        run: |
+          python <<'PY'
+          import os, re, pathlib
+          tag = os.environ["GITHUB_REF_NAME"].lstrip("v")
+          changelog = pathlib.Path("CHANGELOG.md").read_text()
+          pattern = rf"## \[{re.escape(tag)}\][^\n]*\n(.*?)(?=^## \[|\Z)"
+          m = re.search(pattern, changelog, flags=re.DOTALL | re.MULTILINE)
+          notes = m.group(1).strip() if m else (
+              f"See [CHANGELOG.md](./CHANGELOG.md) for v{tag}."
+          )
+          pathlib.Path("release-notes.md").write_text(notes + "\n")
+          PY
+
+      - name: Create release
+        uses: softprops/action-gh-release@v2
+        with:
+          body_path: release-notes.md
+          files: dist/*
+          fail_on_unmatched_files: true

hermes_mcp-0.4.0/.gitignore

@@ -0,0 +1,62 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+*.egg
+.installed.cfg
+
+# Virtual envs
+.venv/
+venv/
+env/
+ENV/
+
+# Tests / coverage
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.tox/
+.nox/
+coverage.xml
+*.cover
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+.pyre/
+.ruff_cache/
+
+# Editors / IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# Env
+.env
+.env.local
+.env.*.local
+
+# Build / packaging
+*.egg-info/
+.eggs/
+
+# Misc
+*.log

hermes_mcp-0.4.0/CHANGELOG.md

@@ -0,0 +1,161 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.4.0] - 2026-05-17
+
+### Added
+- **`hermes_reset()` tool.** Clears every job from the in-memory `JobStore`
+  in one call, returning JSON like `{"cleared": 4, "by_status": {"running": 1, "pending": 3}}`.
+  Same caveat as `hermes_cancel`: does NOT stop in-flight worker threads
+  or gateway calls — workers whose jobs are wiped run to completion and
+  no-op when their `mark_completed` / `mark_failed` finds an unknown id.
+  The tool description warns the LLM that the job store is shared across
+  all MCP callers (multiple Claude sessions, background Hermes-agent
+  workflows), so reset is a global operation that should be confirmed
+  with the user when other work might be in flight.
+- `JobStore.reset_all() -> tuple[int, dict[JobStatus, int]]` helper backing
+  the tool. Reaps expired terminal jobs before counting so the returned
+  `by_status` reflects only jobs that were actually live in the store at
+  call time. Typed against the existing `JobStatus` literal for stronger
+  static checks.
+- **Multi-client groundwork.** Removed the hardcoded Claude-only
+  assumptions from the OAuth flow and tool descriptions. Any MCP client
+  that speaks Streamable HTTP + OAuth 2.1 **and supports pasting in a
+  static `client_id` / `client_secret`** can now connect. Today that's
+  still primarily Claude Desktop / Claude.ai. Codex CLI was tested and
+  found to require Dynamic Client Registration (which we currently
+  disable); Cursor / Continue likely have the same requirement. DCR
+  support is tracked as a follow-up so those clients can join — see the
+  Client compatibility section of the README for the current matrix.
+- **`OAUTH_ALLOWED_REDIRECT_SCHEMES` env var.** Comma-separated list of
+  OAuth redirect-URI custom schemes to accept (default:
+  `claude,claudeai,cursor`). `https` and `http`-on-localhost are always
+  allowed as a security baseline. Lets operators extend the allowlist
+  for new clients (e.g. `vscode` for Continue) without code changes.
+
+### Changed
+- Tool descriptions for `hermes_ask` / `hermes_check` / `hermes_cancel` /
+  `hermes_reset` are now client-neutral. No longer hardcode "Claude" as
+  the consumer; async-mode timeout guidance now notes that enforcement
+  varies by client (Claude.ai is ~2 min; Codex CLI, Cursor, others
+  differ). All async/sync decision heuristics remain unchanged.
+- README, CLAUDE.md, `.env.example`, and source-file docstrings reframed
+  around generic MCP clients. The README's Client compatibility section
+  is honest about the current matrix: Claude is the only client tested
+  end-to-end; Codex CLI is confirmed incompatible until DCR support
+  lands; Cursor and Continue are likely in the same boat.
+- `hermes-mcp mint-client` output now points at any MCP client's config
+  format, not just Claude Desktop's Custom Connector UI.
+
+## [0.3.0] - 2026-05-16
+
+### Added
+- **Async job mode for `hermes_ask`.** New optional `async_mode: bool = False`
+  parameter. When `True`, the call returns a JSON string
+  `{"job_id":"<id>","status":"pending"}` immediately and runs the gateway
+  request in a background thread. Designed to escape the MCP client's
+  per-call timeout (~2 minutes for Claude.ai / Claude Desktop) when Hermes
+  needs to chew on a long multi-step task.
+- **`hermes_check(job_id)` tool.** Returns JSON with `status` ∈
+  `{pending, running, completed, failed, cancelled, unknown}`, plus
+  `created_at` / `finished_at` epoch timestamps, `prompt_chars`, optional
+  `session_id`, and `result` or `error`.
+- **`hermes_cancel(job_id)` tool.** Releases the bookkeeping for an
+  in-flight async job. **Does NOT stop the gateway work** — Python cannot
+  safely kill a thread mid-I/O, so the worker runs to completion and any
+  side effects happen anyway. Use this when you want to release the
+  *result*, not undo the *work*. Tool description spells this out.
+- In-memory `JobStore` (`src/hermes_mcp/jobs.py`) with ~24h TTL, 1000-job
+  cap, lazy cleanup on access. Like OAuth state, jobs are not persisted —
+  a server restart loses every in-flight or completed job.
+- Tool description for `hermes_ask` documents `async_mode` and tells the
+  caller about `hermes_check` and `hermes_cancel`.
+
+### Changed
+- **Single-tool design rescinded** (see CLAUDE.md). The server now exposes
+  three tools tightly coupled around the async-job lifecycle: `hermes_ask`
+  (submit), `hermes_check` (poll), `hermes_cancel` (release). The shape of
+  `hermes_ask` in sync mode is unchanged — old callers continue to work
+  without changes.
+- `JobStore.mark_completed` and `JobStore.mark_failed` are now
+  terminal-state-aware: a late-finishing worker thread cannot overwrite a
+  cancellation (or any other terminal state). Both methods now return
+  `bool` to signal whether the state actually changed.
+
+### Security
+- Unexpected worker-thread exceptions surface only their type name in the
+  job record's `error` field (not `str(exc)`). Matches the existing
+  invariant that gateway error bodies are not echoed in user-visible
+  errors; the full traceback still lands in the server log at ERROR.
+- Cancelled jobs never accept a late `result` payload from the worker
+  thread — prevents a "phantom result" race where the user thinks they
+  cancelled and then sees a result appear anyway.
+
+## [0.2.0] - 2026-05-10
+
+### Changed (BREAKING)
+- **Auth replaced** with OAuth 2.1 (authorization code + PKCE) instead of a single bearer token.
+  Claude Desktop's Custom Connector UI requires this.
+  - New required env vars: `OAUTH_CLIENT_ID`, `OAUTH_CLIENT_SECRET`, `OAUTH_ISSUER_URL`.
+  - Removed: `MCP_BEARER_TOKEN`.
+- **Backend swapped** from `hermes -z` subprocess to HTTP POST against the
+  Hermes gateway's OpenAI-compatible API (`/v1/chat/completions`). Same brain
+  Telegram talks to — sessions, skills, loaded tools all carry over.
+  - New required env var: `HERMES_API_KEY` (the `API_SERVER_KEY` from `~/.hermes/.env`).
+  - New optional env vars: `HERMES_API_URL` (default `http://127.0.0.1:8642`),
+    `HERMES_MODEL` (default `hermes-agent`).
+  - Removed: `HERMES_BIN`, `HERMES_TOOLSETS`, `HERMES_TIMEOUT_SECONDS`
+    (replaced by `HERMES_REQUEST_TIMEOUT_SECONDS`).
+  - `session_id` is now forwarded as the `X-Hermes-Session-Id` header.
+
+### Added
+- `hermes-mcp mint-client` subcommand to generate a fresh client_id / client_secret pair.
+- `MCP_ALLOWED_HOSTS` env var so DNS-rebinding protection accepts the public tunnel hostname.
+- `BIND_HOST` non-loopback values now emit a startup warning.
+- `httpx` runtime dependency (`>=0.27,<1.0`).
+- systemd hardening flags on `deploy/hermes-mcp.service`: `ProtectSystem=strict`,
+  `ProtectHome=read-only` (with `ReadWritePaths=` for the env directory),
+  `RestrictAddressFamilies`, `LockPersonality`, `MemoryDenyWriteExecute`,
+  `CapabilityBoundingSet=`, `SystemCallFilter=@system-service`.
+
+### Security
+- **OAuth redirect-URI scheme allowlist** (`https`, `http` for localhost only,
+  `claude`, `claudeai`). Prevents `/authorize` becoming an open redirector to
+  `javascript:` / `data:` / `file:` URIs.
+- **Atomic refresh-token rotation.** Concurrent `/token` requests with the
+  same refresh token: only the first one wins; the second is rejected as
+  `invalid_grant`. Approximates RFC 6819 reuse detection.
+- **Atomic authorization-code single-use.** Pop-then-mint sequence ensures
+  a code cannot be redeemed twice.
+- **`/authorize` and access-token caps.** Drive-by attackers cannot grow
+  in-memory state unboundedly; expired entries are reaped opportunistically.
+- **Log injection mitigation.** OAuth `state` parameter is sanitized
+  (newlines escaped, truncated to 64 chars) before logging.
+- **Gateway error bodies redacted** from user-visible errors. A misbehaving
+  gateway can no longer inject content into the bridge's `HermesError`
+  responses to Claude. Bodies remain in DEBUG logs only.
+- `httpx.post`/`httpx.get` calls use `follow_redirects=False`.
+
+## [0.1.0] - TBD
+
+### Added
+- Initial release.
+- `hermes_ask(prompt, session_id?, toolsets?)` MCP tool wrapping `hermes -z` and `hermes --continue`.
+- Streamable HTTP transport via FastMCP + uvicorn.
+- Bearer-token auth middleware (`hmac.compare_digest`).
+- Startup doctor self-check (`hermes --version`).
+- Env-var configuration with `.env.example`.
+- systemd units for `hermes-mcp`, cloudflared, and ngrok in `deploy/`.
+- README with architecture diagram, threat model, and tunnel setup walkthroughs.
+
+[Unreleased]: https://github.com/mlennie/hermes-mcp/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/mlennie/hermes-mcp/releases/tag/v0.4.0
+[0.3.0]: https://github.com/mlennie/hermes-mcp/releases/tag/v0.3.0
+[0.2.0]: https://github.com/mlennie/hermes-mcp/releases/tag/v0.2.0
+[0.1.0]: https://github.com/mlennie/hermes-mcp/releases/tag/v0.1.0

hermes_mcp-0.4.0/CLAUDE.md

@@ -0,0 +1,91 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Setup
+uv venv .venv --python 3.11 && source .venv/bin/activate && uv pip install -e ".[dev]"
+
+# Full CI suite (must all pass)
+ruff check . && ruff format --check . && mypy src/ && pytest
+
+# Individual checks
+ruff check .                # lint
+ruff format .               # auto-format
+mypy src/                   # type-check (strict mode, src/ only — mcp module excluded)
+pytest                      # all tests
+pytest tests/test_oauth.py  # single test file
+pytest -k "test_name"       # single test by name
+
+# Run / inspect the server
+hermes-mcp serve            # or: python -m hermes_mcp serve
+hermes-mcp doctor           # startup self-check (probes the gateway)
+hermes-mcp mint-client      # generate a fresh OAuth client_id / client_secret
+```
+
+## Architecture
+
+**hermes-mcp** is an MCP bridge that lets MCP clients (today: Claude Desktop / Claude.ai; future: Codex CLI / Cursor / Continue once DCR ships) delegate tasks to a locally running **Hermes Agent**. The client calls MCP tools (`hermes_ask`, `hermes_check`, `hermes_cancel`, `hermes_reset`) over an HTTPS tunnel; the bridge gates that with OAuth 2.1 and forwards each call to the Hermes gateway's OpenAI-compatible HTTP API.
+
+**Static-client-only constraint.** The OAuth provider currently disables Dynamic Client Registration (`ClientRegistrationOptions(enabled=False)` in `build_app`; `StaticClientProvider.register_client` raises `NotImplementedError`). This means a client can only connect if it supports pasting in a static pre-shared `client_id` / `client_secret`. Claude Desktop's Custom Connector UI does. Codex CLI does not (empirically confirmed — `codex mcp login` auto-attempts DCR and fails). Adding DCR support is a tracked follow-up; tool-description / scheme-allowlist changes in 0.4.0 already removed the other Claude-only assumptions.
+
+```
+MCP client (Claude Desktop / Claude.ai / Codex CLI / Cursor / ...)
+  │  HTTPS via cloudflared tunnel
+  ▼
+hermes-mcp (this project, listening on 127.0.0.1:8765)
+  ├─ OAuth 2.1 (authorization code + PKCE), single static client_id/secret
+  └─ HTTP POST to the gateway
+     │
+     ▼
+hermes-gateway (127.0.0.1:8642, OpenAI-compatible /v1/chat/completions)
+  └─ same AIAgent loop that drives Telegram (skills, tools, sessions)
+```
+
+The gateway is a **separate, long-running process** owned by the user (typically a `systemd --user` service). hermes-mcp does not spawn it; it just sends HTTP requests.
+
+The six source modules in `src/hermes_mcp/` have clean single responsibilities:
+
+- **`config.py`** — frozen `Config` dataclass parsed from env vars. Required: `OAUTH_CLIENT_ID`, `OAUTH_CLIENT_SECRET`, `OAUTH_ISSUER_URL`, `HERMES_API_KEY`. Validates the issuer URL is HTTPS (or `http://localhost`), the client_secret is ≥32 chars, and warns if `BIND_HOST` is non-loopback.
+- **`oauth.py`** — `StaticClientProvider` implements the MCP SDK's `OAuthAuthorizationServerProvider` protocol with one pre-shared client. Mints opaque 256-bit access tokens (1h TTL) and refresh tokens (30d, rotated atomically on use). PKCE-S256 enforced by the SDK. DCR is disabled. `_StaticClient.validate_redirect_uri` enforces a scheme allowlist: `https` and `http`-on-localhost are always allowed (security baseline); custom URI schemes are operator-configured via `OAUTH_ALLOWED_REDIRECT_SCHEMES` (default `claude,claudeai,cursor`). This prevents `/authorize` from becoming an open redirector to `javascript:` / `data:` URIs while letting any MCP client whose scheme is in the allowlist complete the flow.
+- **`hermes_client.py`** — `HermesClient.ask()` does `httpx.post` to the gateway's `/v1/chat/completions` with `Authorization: Bearer $HERMES_API_KEY`. `session_id` is forwarded as `X-Hermes-Session-Id`. `toolsets` is accepted for backward-compat but ignored — toolset selection now lives in the Hermes config (`platform_toolsets.api_server`). Gateway error bodies are NOT echoed in user-visible errors (DEBUG only).
+- **`jobs.py`** — `JobStore` is a thread-safe in-memory dict of `Job` records, used by `hermes_ask(..., async_mode=True)`, `hermes_check`, `hermes_cancel`, and `hermes_reset`. Lazy TTL reap (24h) on every access, 1000-job cap. In-memory only by design; restart drops everything. `mark_completed`/`mark_failed` are terminal-state-aware so a late-finishing worker cannot overwrite a cancellation. `reset_all()` reaps first, then wipes the store and returns `(cleared, by_status)`. Times use `time.time()` (wall clock, epoch seconds) so they round-trip cleanly through JSON to the caller; small risk of confusion if the system clock jumps backwards, accepted in exchange for code simplicity.
+- **`server.py`** — `build_app()` constructs a `FastMCP` instance with `auth_server_provider`, `AuthSettings`, and `transport_security`. Registers four tools: `hermes_ask` (sync default; `async_mode=True` spawns a daemon thread and returns a `job_id`), `hermes_check(job_id)`, `hermes_cancel(job_id)`, and `hermes_reset()`. FastMCP itself adds `/authorize`, `/token`, `/.well-known/oauth-authorization-server`, and the `RequireAuthMiddleware` that gates `/mcp`. `serve()` runs uvicorn.
+- **`doctor.py`** — `run_checks()` probes the gateway's `/v1/health` (no auth) and `/v1/models` (with `HERMES_API_KEY`); warns if `HERMES_MODEL` isn't in the returned model list.
+
+**Four-tool design.** The tools form a tight lifecycle: submit (`hermes_ask`), poll (`hermes_check`), abandon a single job (`hermes_cancel`), wipe the store (`hermes_reset`). Do not add tools for *new* use cases (different actions, different domains) without discussing in an issue first.
+
+**`hermes_reset` is a global operation.** The job store is shared across every MCP caller (multiple Claude sessions, background Hermes-agent workflows, etc.). Resetting wipes them all. The tool description warns the LLM to confirm with the user before calling it when other work might be in flight.
+
+**Cancellation is a tombstone, not a kill switch.** `hermes_cancel` updates this server's bookkeeping; the worker thread keeps running and the gateway keeps doing whatever it was doing. There is no way around this in CPython — you cannot safely kill a thread blocked on `httpx.post`. The tool's description spells this out loudly so the LLM relays the caveat to the user. If we ever want real cancellation, the path is to rewrite `HermesClient` against `httpx.AsyncClient` with cancellation tokens and run the whole server on asyncio — large refactor, scoped for a future major version.
+
+## Key constraints
+
+- All four required env vars must be set or the server refuses to start.
+- `client_secret` comparison uses `hmac.compare_digest()` (delegated to the MCP SDK's `ClientAuthenticator`).
+- Access tokens are in-memory only — by design. Restart invalidates all sessions. **Claude Desktop does NOT re-auth transparently** in practice: it surfaces "Error occurred during tool execution" on the next call and the user has to manually Disconnect / Reconnect the connector once. The `client_id` / `client_secret` are saved on the connector, so the reconnect doesn't require re-pasting credentials. (Persisting tokens — and async-mode jobs — to disk is on the v0.4.0 roadmap.)
+- Async-mode jobs are also in-memory only (`jobs.py`). A server restart drops every job, in-flight or completed; if a user is mid-poll they will see `status: unknown`. The same Disconnect/Reconnect dance applies after a restart.
+- Refresh-token rotation is **atomic-pop-then-mint** in `oauth.py` — concurrent `/token` requests with the same refresh token cannot both succeed.
+- Prompt content must only be logged at DEBUG level, not INFO (privacy by default). The `state` query parameter is sanitized before logging. Async-job records intentionally store only `prompt_chars` (not the prompt itself).
+- Unexpected (non-`HermesError`) exceptions in the async worker thread surface as `error: "unexpected error: <ExceptionType>"` — never `str(exc)` — to preserve the existing invariant that gateway and library error bodies are not echoed in user-facing errors. Full traceback lands in the server log at ERROR.
+- `BIND_HOST` defaults to `127.0.0.1`; binding elsewhere gets a startup warning.
+- mypy is run on `src/` only — the `mcp` package lacks stubs and is excluded.
+- Python ≥ 3.11 required; CI tests 3.11 and 3.12.
+- Test count is 112 as of v0.3.0; a sudden drop is a regression smell.
+
+## Deployment shape
+
+This project ships with `deploy/hermes-mcp.service` and `deploy/cloudflared.service` as **systemd user units** (matching the `hermes-gateway` / `mcp-proxy` services it sits next to). Env file lives at `~/.config/hermes-mcp/env` mode 0600. `loginctl enable-linger` is required so user services start at boot.
+
+`deploy/hermes-mcp.service` ships with non-trivial hardening flags: `ProtectSystem=strict`, `ProtectHome=read-only` + `ReadWritePaths=%h/.config/hermes-mcp`, `RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX`, `LockPersonality=true`, `MemoryDenyWriteExecute=true`, empty `CapabilityBoundingSet=`, and `SystemCallFilter=@system-service` (excluding `@privileged @resources`). They are verified to start cleanly with the current Python deps; **do not strip them without intent** and re-test the service start. If a future dependency needs JIT or syscalls outside `@system-service`, narrow the rule rather than removing it.
+
+## Release process
+
+Per-release steps:
+1. Bump version in **both** `src/hermes_mcp/__init__.py` and `pyproject.toml`. The release workflow checks they match the pushed tag and fails the build if they don't.
+2. Move the `Unreleased` section in `CHANGELOG.md` to the new version heading with today's date. Keep the `[Unreleased]` heading empty above it. The release workflow's `github-release` job extracts this section verbatim as the release notes.
+3. Commit, tag `vX.Y.Z`, `git push origin main vX.Y.Z`. The tag push fires `.github/workflows/release.yml`, which builds the wheel + sdist, publishes to PyPI via OIDC trusted publishing (no API tokens stored anywhere), and creates a GitHub Release with the CHANGELOG section and built artifacts attached.
+
+One-time setup (already done for this project, listed here so a maintainer rotating the secret doesn't re-do it from scratch): a trusted publisher is configured at https://pypi.org/manage/project/hermes-mcp/settings/publishing/ pointing at this repo, workflow filename `release.yml`, no environment. If the workflow is renamed or moved, the PyPI trusted-publisher entry must be updated to match or the publish step will fail.