dazzer-connect 0.1.0 → 0.1.1

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
+```
+
+You get a link to open on any other device — your phone will do. Sign in there and the terminal finishes on its own.
+
+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.
 
-## Configure Claude Desktop
+## What you get, and how long it lasts
 
-After `dazzer auth login`, copy the JSON block from your terminal into your Claude Desktop MCP settings file:
+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:
 
-- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+```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,54 @@ 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    # sign out and delete what is stored
 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.
+
+## Where your sign-in is kept
 
-Production defaults apply when you omit flags and env vars:
+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.
 
-| 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` |
+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.
 
-For local development against a running authorization server:
+## Settings
+
+Everything points at production unless you say otherwise.
+
+| 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` |
+
+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
 dazzer auth login --issuer http://localhost:3003
 ```
 
-## Token storage
+## Something wrong?
 
-- **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.
+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.
 
-If keychain storage fails, login still completes and prints copy-paste-ready MCP client config to stdout.
+## Licence
 
-## Develop from source
-
-```bash
-pnpm --filter dazzer-cli build
-node packages/oauth-cli/dist/index.js auth login --issuer http://localhost:3003
-```
+MIT.