dazzer-connect 0.1.0 → 0.2.0

package/README.md

@@ -1,30 +1,54 @@
-# dazzer-cli
+# dazzer-connect
 
-Sign in to Dazzer from your terminal and get a copy-paste MCP client configuration.
+Dazzer is a memory your AI tools share: they check what you already know before answering, and save what settles. This signs you in from a terminal, for the tools that cannot sign in by themselves.
 
-Requires Node.js 20 or later.
+## You probably do not need this
 
-## Install
+Most AI clients can sign in on their own. If yours can, skip this package entirely:
+
+- **Claude Code, Codex, Copilot, Cursor, Antigravity, Devin** — install the Dazzer plugin from inside the client. Each one words the command differently, so take it from the source rather than from here: [dazzer-io/dazzer-plugin](https://github.com/dazzer-io/dazzer-plugin). This is the route Dazzer's own first-time setup uses.
+- **Claude's desktop app, Claude in a browser, anything else with a connectors screen** — open its settings, add a connector, paste `https://graph.dazzer.io/mcp`, and sign in there. Nothing to install.
+
+Both of those stay connected and renew themselves. That leaves two cases, and they are the reason this exists: a client that only takes a pass you paste in, and a machine with no browser — a server, a container, a remote session.
+
+## Sign in
+
+Needs Node.js 22.12 or later. Once installed, the command is `dazzer`.
 
 ```bash
-# One-off sign-in (downloads and runs the CLI)
-npx dazzer-cli auth login
+# One-off, nothing installed
+npx dazzer-connect auth login
 
-# Or install globally — the command is `dazzer`
-npm i -g dazzer-cli
+# Or keep it around
+npm i -g dazzer-connect
 dazzer auth login
 ```
 
-The CLI opens your browser to sign in (or falls back to a device code when headless). On success it prints MCP client configuration to your terminal.
+Your browser opens to sign in. On a machine with no browser, add `--no-browser`:
+
+```bash
+dazzer auth login --no-browser
+```
 
-## Configure Claude Desktop
+You get a link to open on any other device — your phone will do. Sign in there and the terminal finishes on its own.
 
-After `dazzer auth login`, copy the JSON block from your terminal into your Claude Desktop MCP settings file:
+Sign-in does try to notice a missing browser on its own, but do not count on it — on a machine that merely *thinks* it has a screen it will wait for a browser that never opens.
 
-- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+## What you get, and how long it lasts
+
+Sign-in prints two ready-to-paste blocks. **Use the first one if you possibly can** — it names the address only, your client signs in for itself, and the connection renews without you:
+
+```json
+{
+  "mcpServers": {
+    "dazzer": {
+      "url": "https://graph.dazzer.io/mcp"
+    }
+  }
+}
+```
 
-The block looks like this (your access token is filled in automatically):
+The second carries a pass, for clients that cannot do that:
 
 ```json
 {
@@ -32,52 +56,59 @@ The block looks like this (your access token is filled in automatically):
     "dazzer": {
       "url": "https://graph.dazzer.io/mcp",
       "headers": {
-        "Authorization": "Bearer <your-access-token>"
+        "Authorization": "Bearer <your-pass>"
       }
     }
   }
 }
 ```
 
-Merge it with any existing `mcpServers` entries, save the file, then restart Claude Desktop.
+**That pass lasts about an hour.** Enough to get working now; not a way to set something up and walk away. When it expires, run `dazzer auth login` again — or switch to the first block and stop thinking about it.
 
-If keychain storage failed during login, the printed config is your fallback — paste it before closing the terminal.
+Merge either one with any `mcpServers` entries you already have, save, and restart your client.
 
 ## Other commands
 
 ```bash
-dazzer auth status    # show sign-in status
-dazzer auth logout    # sign out and remove stored tokens
+dazzer auth status    # is my sign-in still good?
+dazzer auth logout    # cancel your sign-in and remove it from this machine
 dazzer --help
 ```
 
-## Configuration
+`auth status` asks the server rather than trusting what is on disk, so it can tell you your sign-in has been revoked elsewhere.
 
-Production defaults apply when you omit flags and env vars:
+`auth logout` cancels your sign-in at the server and removes it from this machine, and says "Signed out." only when it knows both happened. If your sign-in could not be cancelled right now — the server did not answer, or your credential store would not open or would not let it go — it says so, fails, and keeps it, so running it again can finish. If the server gives an answer that will not change, it removes the sign-in from this machine and tells you it stops working once it goes 30 days unused. A pass you pasted into another app keeps working until it expires, within the hour.
 
-| Source | Variable | Default |
-|--------|----------|---------|
-| Flag | `--issuer` | — |
-| Env | `DAZZER_AUTH_ISSUER` | `https://auth.dazzer.io` |
-| Env | `DAZZER_AUTH_CLIENT_ID` | `dazzer-cli-local` |
-| Env | `DAZZER_AUTH_RESOURCE` | `https://graph.dazzer.io/mcp` |
+## Where your sign-in is kept
 
-For local development against a running authorization server:
+Your passes go in your operating system's own credential store — Keychain on macOS, Credential Manager on Windows, Secret Service on Linux. Nothing is written in plain text. The rest, such as which server you signed in to and when it expires, sits in a settings folder alongside your other applications' settings.
 
-```bash
-dazzer auth login --issuer http://localhost:3003
-```
+Plenty of servers and containers have no credential store at all. Sign-in still completes and prints the blocks above, and `auth status` tells you that is what happened rather than claiming you are signed out. On such a machine `auth logout` cannot check for a saved sign-in, so it will not call itself a sign-out; on Linux, `dazzer auth logout --forget-this-machine` removes this machine's record instead, says that nothing was cancelled, and leaves any sign-in still in the credential store where it is. It refuses on macOS and Windows, whose credential store is locked rather than missing, and when sign-in recorded saving a sign-in here.
 
-## Token storage
+## Settings
 
-- **Secrets** (access + refresh tokens): OS keychain via `@napi-rs/keyring` (macOS Keychain, Windows Credential Manager, Linux Secret Service). Prebuilt binaries install with the package — no compiler required.
-- **Metadata** (issuer, client id, expiry): config directory from `env-paths("dazzer")` — typically `~/Library/Application Support/dazzer/` on macOS.
+Everything points at production unless you say otherwise.
 
-If keychain storage fails, login still completes and prints copy-paste-ready MCP client config to stdout.
+| Setting | What it is | Default |
+|---|---|---|
+| `DAZZER_AUTH_ISSUER` | where you sign in | `https://auth.dazzer.io` |
+| `DAZZER_AUTH_CLIENT_ID` | which client is asking | `dazzer-cli-local` |
+| `DAZZER_AUTH_RESOURCE` | what you are signing in to | `https://graph.dazzer.io/mcp` |
+| `DAZZER_API_BASE_URL` | where Dazzer itself is | `https://graph.dazzer.io` |
 
-## Develop from source
+The first three are about signing in. The last one is Dazzer itself — the same service, seen from the other side — and it is the address the tool sends to once it has a sign-in to carry. Both addresses have to be `https`; an unencrypted one is refused before anything is sent.
+
+Signing in and checking status each take a matching flag — `--issuer`, `--client-id`, `--resource` — which wins over the setting. Against a sign-in server running on your own machine:
 
 ```bash
-pnpm --filter dazzer-cli build
-node packages/oauth-cli/dist/index.js auth login --issuer http://localhost:3003
+dazzer auth login --issuer http://localhost:3003
 ```
+
+## Something wrong?
+
+Email [support@dazzer.io](mailto:support@dazzer.io). If it is a security problem, write to
+[security@dazzer.io](mailto:security@dazzer.io) instead and please do not post it publicly first.
+
+## Licence
+
+MIT.