docs: deployment guide + per-client setup + connect matrix

- doc/deployment.md: run familiar as a remote MCP server — secure defaults, bearer vs OAuth modes, the full env-var reference, one-time login / token-store provisioning, the published images, docker compose, and TLS reverse-proxy blocks for nginx (proxy_buffering off + long read timeout), Caddy, and Traefik. - doc/clients/: one page per client with exact working steps — Claude Code, VS Code (.vscode/mcp.json with a masked token input, and the workspace .mcp.json header gotcha), Mistral Le Chat, Claude Desktop + Cowork (mcp-remote bridge, per-OS config paths), and Claude web (oauth mode + external IdP, with "use Desktop + bearer" as the simpler alternative). Plus a clients/ index. - README: a "Connect a client" matrix (client -> auth -> guide) and a compact "Deploy with Docker" section linking to doc/deployment.md; oauth mode noted. - doc/README.md index: rows for Deployment and Client setup. - doc/getting-started.md: pointer from the HTTPS quickstart to the full docs. - CLAUDE.md: FAMILIAR_AUTH_MODE / FAMILIAR_OAUTH_* / FAMILIAR_ALLOW_INSECURE_BIND and /healthz in the transport note; the split ci.yml / docker.yml workflows. Deployment docs live under the existing doc/ tree (the repo uses doc/, not a separate docs/) to keep a single documentation directory.
2026-07-04 19:26:33 +02:00
1 parent eb2922f63c
commit df9e06a3e7
@@ -38,6 +38,8 @@ fittings, fleet, UI windows, PI) gated behind a safety choke point.
 | Document | What's in it |
 | --- | --- |
 | [Getting Started](getting-started.md) | Install with `uv`, log in via EVE SSO, connect to Claude, first queries. |
+| [Deployment](deployment.md) | Run familiar as a remote MCP server: Docker, reverse proxy + TLS, bearer/OAuth, env reference. |
+| [Client setup](clients/) | Exact connection steps per client — Claude Code, VS Code, Desktop, Cowork, web, Mistral. |
 | [Architecture](architecture.md) | How the server is assembled, the ESI/auth/charutil/writes layers, the module pattern. |
 | [Authentication](authentication.md) | EVE SSO PKCE flow, the encrypted multi-character store, scopes, CLI commands. |
 | [Write Safety](write-safety.md) | The `writes.guard` choke point, dry-run previews, the audit log, enabling/disabling. |
@@ -0,0 +1,18 @@
+# Connect a client
+
+Exact steps to point each MCP client at a familiar server deployed over HTTPS
+(see [deployment](../deployment.md) first). Most clients use a **bearer token**
+(`FAMILIAR_HTTP_TOKEN`); only the claude.ai web connector needs **OAuth**.
+
+| Client | Auth | Guide |
+| --- | --- | --- |
+| Claude Code | Bearer | [claude-code.md](claude-code.md) |
+| VS Code (Copilot) | Bearer | [vscode.md](vscode.md) |
+| Mistral Le Chat | Bearer | [mistral.md](mistral.md) |
+| Claude Desktop | Bearer (via `mcp-remote`) | [claude-desktop.md](claude-desktop.md) |
+| Claude Cowork | Bearer (via `mcp-remote`) | [claude-cowork.md](claude-cowork.md) |
+| Claude web (claude.ai) | OAuth 2.1 (external IdP) | [claude-web.md](claude-web.md) |
+
+Bearer works everywhere except the claude.ai web connector, which requires
+OAuth 2.1 with Dynamic Client Registration. If you're a Claude user who doesn't
+want to run an IdP, use the **Desktop** app with a bearer token instead.
@@ -0,0 +1,28 @@
+# Connect Claude Code
+
+**Auth:** bearer token. **Prereq:** familiar deployed over HTTPS (see [deployment](../deployment.md)).
+
+Claude Code speaks HTTP MCP with custom headers directly. Add the server:
+
+```bash
+claude mcp add --transport http familiar https://familiar.yourdomain.tld/mcp \
+  --header "Authorization: Bearer <your-token>"
+```
+
+- `<your-token>` is your `FAMILIAR_HTTP_TOKEN`.
+- Use the full URL including the `FAMILIAR_HTTP_PATH` (default `/mcp`).
+
+Check it:
+
+```bash
+claude mcp list          # familiar should show as connected
+```
+
+Then ask Claude Code to call `ping`, or "what's Tritanium worth in Jita?".
+
+To scope it to the current project instead of your user config, add `--scope project` (writes a `.mcp.json` in the repo). Remove it with `claude mcp remove familiar`.
+
+## Troubleshooting
+
+- **401** — the token is wrong or missing; re-run `claude mcp add` with the correct `Authorization` header.
+- **Hangs / times out** — your reverse proxy is likely buffering; set `proxy_buffering off;` and a long read timeout (see [deployment](../deployment.md#tls-reverse-proxy)).
@@ -0,0 +1,9 @@
+# Connect Claude Cowork
+
+**Auth:** bearer token, via a local bridge.
+
+Cowork shares Claude Desktop's connector plumbing, so the setup is identical: bridge the remote HTTP server to a local stdio command with `mcp-remote` so the `Authorization: Bearer <token>` header gets forwarded.
+
+Follow **[Connect Claude Desktop](claude-desktop.md)** — the same `claude_desktop_config.json` entry (the `npx mcp-remote … --header "Authorization: Bearer <token>"` block) applies. After editing, restart Cowork.
+
+If you've configured it once for Desktop on the same machine, Cowork picks up the same config.
@@ -0,0 +1,38 @@
+# Connect Claude Desktop
+
+**Auth:** bearer token, via a local bridge. **Prereq:** familiar deployed over HTTPS (see [deployment](../deployment.md)), plus Node.js (`npx`) on the machine running Claude Desktop.
+
+Claude Desktop's **Connectors** UI can add a remote MCP URL but **cannot attach a bearer header**. So bridge the remote HTTP server to a local stdio command with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), which forwards the `Authorization` header.
+
+Edit `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "familiar": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-remote",
+        "https://familiar.yourdomain.tld/mcp",
+        "--header",
+        "Authorization: Bearer <your-token>"
+      ]
+    }
+  }
+}
+```
+
+Config file location:
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux:** `~/.config/Claude/claude_desktop_config.json`
+
+Restart Claude Desktop fully (quit, not just close the window). familiar appears in the tools/plug icon.
+
+## Troubleshooting
+
+- **Server fails to start** — ensure Node.js is installed and `npx` is on PATH; the first run downloads `mcp-remote`.
+- **401** — fix the token in the `--header` argument, then restart.
+- **Want native (no bridge)?** Only the OAuth path is header-free, and Desktop's connector is happiest with bearer via this bridge — keep `mcp-remote` unless you've set up [oauth mode](claude-web.md).
@@ -0,0 +1,39 @@
+# Connect Claude web (claude.ai)
+
+**Auth:** OAuth 2.1 only. **Prereq:** familiar in `oauth` mode behind HTTPS, plus an external identity provider.
+
+The claude.ai custom-connector flow speaks **OAuth 2.1 with Dynamic Client Registration (DCR)** and does **not** accept a static bearer token. familiar itself is only a **resource server** — it validates JWTs and advertises where to authenticate, but it is **not** an authorization server and does no DCR. So Claude web needs an external IdP that supports DCR (e.g. **Authentik** or **Keycloak**) sitting in front.
+
+> **Simpler alternative:** if you don't want to run an IdP, use the **Claude Desktop** app with a bearer token instead — see [Connect Claude Desktop](claude-desktop.md). Bearer is easier for every client except the claude.ai web connector.
+
+## 1. Set up the IdP (external)
+
+On your IdP, create an application/provider for familiar that:
+
+- issues **JWT access tokens** signed with a key published at a **JWKS** endpoint,
+- sets the token **audience** to familiar's public URL (the resource),
+- supports **Dynamic Client Registration** so claude.ai can register itself.
+
+Note the issuer URL and (optionally) the JWKS URL.
+
+## 2. Configure familiar in oauth mode
+
+```bash
+FAMILIAR_AUTH_MODE=oauth
+FAMILIAR_OAUTH_ISSUER=https://idp.yourdomain.tld/application/o/familiar/
+FAMILIAR_OAUTH_RESOURCE=https://familiar.yourdomain.tld
+# FAMILIAR_OAUTH_AUDIENCE defaults to the resource URL; override if your IdP differs.
+# FAMILIAR_OAUTH_JWKS_URI is discovered from the issuer's OIDC metadata if unset.
+```
+
+No `FAMILIAR_HTTP_TOKEN` is needed in oauth mode. familiar serves the discovery document at `https://familiar.yourdomain.tld/.well-known/oauth-protected-resource/mcp`, and unauthenticated MCP calls return `401` with a `WWW-Authenticate: Bearer` header pointing at your issuer.
+
+## 3. Add the connector
+
+In claude.ai: **Settings → Connectors → Add custom connector**, URL `https://familiar.yourdomain.tld/mcp`. Claude discovers your IdP from the metadata, registers via DCR, and runs the OAuth login. Approve familiar's scopes and you're connected.
+
+## Troubleshooting
+
+- **"couldn't connect" immediately** — familiar isn't in `oauth` mode, or `FAMILIAR_OAUTH_RESOURCE`/`ISSUER` are unset; the metadata endpoint must return 200.
+- **Login loops / invalid token** — audience mismatch: your IdP's token `aud` must equal `FAMILIAR_OAUTH_RESOURCE` (or your `FAMILIAR_OAUTH_AUDIENCE`).
+- **DCR fails** — the IdP doesn't have Dynamic Client Registration enabled; claude.ai requires it.
@@ -0,0 +1,17 @@
+# Connect Mistral Le Chat
+
+**Auth:** bearer token. **Prereq:** familiar deployed over HTTPS (see [deployment](../deployment.md)).
+
+Mistral's [chat.mistral.ai](https://chat.mistral.ai) supports remote MCP servers with a bearer token natively.
+
+1. Open **Intelligence → Connectors → Add custom connector**.
+2. **URL:** `https://familiar.yourdomain.tld/mcp` (include the `FAMILIAR_HTTP_PATH`, default `/mcp`).
+3. **Authentication:** choose **Bearer Token** and paste your `FAMILIAR_HTTP_TOKEN`.
+4. Save, then enable the connector in a conversation.
+
+Ask Le Chat to call `ping`, or "compare Plex prices across trade hubs".
+
+## Troubleshooting
+
+- **401 / connector won't enable** — wrong or missing token; re-check the Bearer Token value.
+- **Timeouts** — reverse-proxy buffering; set `proxy_buffering off;` and a long read timeout (see [deployment](../deployment.md#tls-reverse-proxy)).
@@ -0,0 +1,38 @@
+# Connect VS Code (Copilot / MCP)
+
+**Auth:** bearer token. **Prereq:** familiar deployed over HTTPS (see [deployment](../deployment.md)).
+
+VS Code's MCP support reads an **`http`** server entry with custom headers. Put it in **`.vscode/mcp.json`** (per-workspace) or your user `mcp.json`.
+
+> ⚠️ Use **`.vscode/mcp.json`**, not a workspace-root **`.mcp.json`**. The workspace `.mcp.json` format ignores `headers`, so the bearer token never gets sent and you'll get a silent 401. This is a known VS Code quirk.
+
+`.vscode/mcp.json`:
+
+```json
+{
+  "inputs": [
+    {
+      "id": "familiar_token",
+      "type": "promptString",
+      "description": "familiar bearer token",
+      "password": true
+    }
+  ],
+  "servers": {
+    "familiar": {
+      "type": "http",
+      "url": "https://familiar.yourdomain.tld/mcp",
+      "headers": {
+        "Authorization": "Bearer ${input:familiar_token}"
+      }
+    }
+  }
+}
+```
+
+On first use VS Code prompts for the token (masked, thanks to `password: true`) and reuses it. Start the server from the MCP view or the `MCP: List Servers` command, then use it from Copilot Chat's agent mode.
+
+## Troubleshooting
+
+- **Silent 401 / "no tools"** — you're almost certainly in a root `.mcp.json`; move the config to `.vscode/mcp.json` so `headers` is honored.
+- **401 after entering a token** — wrong token; clear it via `MCP: Reset Cached Tokens` (or restart) and re-enter.
@@ -0,0 +1,140 @@
+# Deployment — familiar as a remote MCP server
+
+familiar runs two ways from the **same** code and token store:
+
+1. **Local (stdio)** — the default. How Claude Desktop / Claude Code / Cowork launch it. Nothing here changes; see [getting-started](getting-started.md).
+2. **Remote (HTTP)** — opt-in via `familiar serve`. Streamable HTTP behind a TLS reverse proxy, gated by a bearer token (or external OAuth). This page covers (2).
+
+Once it's running, see [doc/clients/](clients/) for exact per-client setup.
+
+## Secure defaults
+
+- **stdio unless told otherwise.** `familiar serve` (not the bare `familiar`) starts HTTP.
+- **Loopback bind by default** (`127.0.0.1`). The Docker image binds `0.0.0.0` so the reverse proxy can reach it.
+- **Fail closed.** familiar refuses to start without authentication. In bearer mode that means no `FAMILIAR_HTTP_TOKEN` → it won't boot; a non-loopback bind without a token is called out explicitly. The only override is the explicit `FAMILIAR_ALLOW_INSECURE_BIND=true` escape hatch.
+- **Writes off over HTTP.** A network-reachable, LLM-driven endpoint keeps writes disabled unless you set `FAMILIAR_ENABLE_WRITES=true`. Local stdio keeps writes on.
+- **Token never in the URL.** Clients authenticate with an `Authorization: Bearer <token>` header only.
+
+## Authentication modes
+
+`FAMILIAR_AUTH_MODE` picks how the HTTP transport authenticates:
+
+- **`bearer`** (default) — one static token in `FAMILIAR_HTTP_TOKEN`. Simple, and every client below except Claude web supports it. Recommended.
+- **`oauth`** — familiar runs as an OAuth 2.1 **resource server**: it validates incoming JWT access tokens against an external issuer's JWKS and serves `/.well-known/oauth-protected-resource/<path>` so OAuth-only clients can discover the authorization server. familiar is **not** an authorization server and does **no** Dynamic Client Registration — you must run an external IdP that does (Authentik, Keycloak, …). Only needed for the native **Claude web** connector. See [doc/clients/claude-web.md](clients/claude-web.md).
+
+## Environment variables
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `FAMILIAR_HTTP_HOST` | `127.0.0.1` | Bind address (image sets `0.0.0.0`). |
+| `FAMILIAR_HTTP_PORT` | `8080` | Bind port. |
+| `FAMILIAR_HTTP_PATH` | `/mcp` | MCP endpoint path. |
+| `FAMILIAR_AUTH_MODE` | `bearer` | `bearer` or `oauth`. |
+| `FAMILIAR_HTTP_TOKEN` | *(unset)* | Bearer token. **Required** in bearer mode. |
+| `FAMILIAR_ALLOW_INSECURE_BIND` | `false` | Allow a bind without a token (don't). |
+| `FAMILIAR_OAUTH_ISSUER` | *(unset)* | Authorization-server URL (oauth mode). |
+| `FAMILIAR_OAUTH_RESOURCE` | *(unset)* | This server's public URL, e.g. `https://familiar.example.com` (oauth mode). |
+| `FAMILIAR_OAUTH_AUDIENCE` | = resource | Expected token audience (oauth mode). |
+| `FAMILIAR_OAUTH_JWKS_URI` | *(discovered)* | JWKS URL; if unset, discovered from the issuer's OIDC metadata. |
+| `FAMILIAR_DATA_DIR` | per-user | Where `token.enc` + `key` + `audit.log` + write toggle live. Image sets `/data`. |
+| `FAMILIAR_ENABLE_WRITES` | on (stdio) / off (HTTP) | `true` allows guarded writes; over HTTP it's off unless set. |
+
+`/healthz` is an unauthenticated liveness probe (used by the Docker healthcheck and reverse-proxy probes). It returns only `{"status":"ok","server":"familiar","version":"…"}` — no account data. Every MCP call under `FAMILIAR_HTTP_PATH` requires authentication.
+
+## One-time login (why it happens on the host)
+
+EVE SSO login is a browser PKCE flow with a `localhost` callback — awkward inside a container. Authenticate **once on a machine with a browser**, then hand the resulting token store to the container. The container only ever *refreshes* tokens.
+
+```bash
+uv run familiar login          # opens the browser, writes token.enc + key
+uv run familiar status         # confirm the character(s)
+```
+
+Then make that data dir available to the container. Point `FAMILIAR_DATA_DIR_HOST` at it, or copy `token.enc` + `key` into `./data`:
+
+```bash
+mkdir -p ./data
+# Linux/macOS host default:
+cp ~/.local/share/familiar/{token.enc,key} ./data/
+# Windows host default:
+#   copy %LOCALAPPDATA%\familiar\token.enc .\data\ ; copy %LOCALAPPDATA%\familiar\key .\data\
+```
+
+**Headless host?** Use `uv run familiar login --no-browser`: it prints the SSO URL, you authorize in any browser, and paste the redirected callback URL back on stdin. The `/data` volume is mounted read-write so token refresh (which rotates the refresh token) and the audit log persist.
+
+## Published images (Gitea)
+
+`.gitea/workflows/docker.yml` builds, smoke-tests (non-root, `/healthz` 200, MCP 401 without / 200 with a token), and pushes on every push to `main`/`dev`:
+
+| Branch | Tags |
+| --- | --- |
+| `main` | `git.hiddenden.cafe/hiddenden/familiar:latest`, `:main`, `:sha-<12>` |
+| `dev`  | `git.hiddenden.cafe/hiddenden/familiar:dev`, `:sha-<12>` |
+
+Pushing needs a Gitea PAT with `write:package` scope stored as the repo secret `REGISTRY_TOKEN`. Pick the channel with `FAMILIAR_IMAGE` in `.env`.
+
+## Run with Docker Compose
+
+```bash
+cp .env.example .env
+# edit .env: FAMILIAR_HTTP_TOKEN (openssl rand -hex 32), FAMILIAR_DOMAIN,
+#            cert resolver, FAMILIAR_IMAGE (:latest prod / :dev dev channel)
+
+docker network create proxy    # once, if your reverse proxy doesn't own it yet
+
+docker login git.hiddenden.cafe
+docker compose pull && docker compose up -d
+#   ...or build locally instead:  docker compose up -d --build
+
+docker compose logs -f familiar
+```
+
+The compose service joins the external `proxy` network (not published to the host), runs non-root with a `read_only` rootfs + tmpfs `/tmp`, `no-new-privileges` and `cap_drop: ALL`, and healthchecks `GET /healthz`.
+
+## TLS reverse proxy
+
+familiar terminates no TLS itself — a proxy does. Streamable HTTP holds a long-lived response open, so **disable buffering** and use a **generous read timeout** on the MCP path.
+
+### nginx
+
+```nginx
+location /mcp {
+    proxy_pass http://127.0.0.1:8080/mcp;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_buffering off;          # stream events straight through
+    proxy_read_timeout 3600s;     # don't cut long-lived MCP sessions
+}
+```
+
+(If you run the container on the `proxy` network instead of publishing to the host, point `proxy_pass` at `http://familiar:8080/mcp`.)
+
+### Caddy
+
+```
+familiar.yourdomain.tld {
+    reverse_proxy familiar:8080
+}
+```
+
+Caddy fetches and renews the certificate automatically and streams by default.
+
+### Traefik (labels included)
+
+`docker-compose.yml` already carries Traefik router labels. Set in `.env`:
+
+```
+FAMILIAR_DOMAIN=familiar.yourdomain.tld
+TRAEFIK_CERTRESOLVER=letsencrypt
+```
+
+Traefik terminates HTTPS and forwards to the container's port 8080 on the `proxy` network. Your public URL is then `https://familiar.yourdomain.tld/mcp`.
+
+## Operational notes
+
+- **Rotate the token** by changing `FAMILIAR_HTTP_TOKEN` and restarting; update every client header.
+- **Restrict inbound** at the proxy/firewall to the clients you expect.
+- **Watch** `docker compose logs` for `401` auth failures and `/data/audit.log` for the write trail.
+- **Re-login** (host) whenever you change requested scopes, then refresh the `/data` token store.
@@ -106,6 +106,10 @@ To reach familiar from a **remote** MCP client (for example a [chat.mistral.ai](
 custom connector), run the opt-in **streamable-HTTP** transport instead. stdio stays the default;
 nothing here changes how `uv run familiar` behaves with no arguments.

+> This section is a quickstart. For the full production setup — Docker, reverse proxy (nginx / Caddy /
+> Traefik), the bearer vs OAuth modes, and the env-var reference — see [deployment](deployment.md), and
+> for exact per-client steps see [doc/clients/](clients/).
+
 ```bash
 FAMILIAR_HTTP_TOKEN=$(openssl rand -hex 32) uv run familiar serve
 ```
@@ -158,6 +162,16 @@ location /mcp {
 - **Copy the store** — run `familiar login` on your desktop, then copy the encrypted store
  (`token.enc` + `key` from your `FAMILIAR_DATA_DIR`) to the server's data dir.

+### Run it in Docker
+
+CI publishes a container image on every merge to `dev`/`main`
+(`git.hiddenden.cafe/hiddenden/familiar`, tags `:dev` and `:main`/`:latest`). It runs `familiar serve`
+as a non-root user on port `8080`, with a `/healthz` healthcheck and the encrypted token store under a
+`/data` volume. Use the bundled [`docker-compose.yml`](../docker-compose.yml): copy
+[`.env.example`](../.env.example) to `.env`, set `FAMILIAR_HTTP_TOKEN`, put your logged-in store in
+`./data`, then `docker compose up -d`. It publishes on `127.0.0.1:8080` only — the nginx block above
+proxies to it. The container refuses to start without `FAMILIAR_HTTP_TOKEN`.
+
 ### Add it in Mistral

 In [chat.mistral.ai](https://chat.mistral.ai): **Intelligence → Connectors → Add custom connector**,