affine-mcp-server 1.9.0 → 1.10.0

package/README.md

@@ -2,7 +2,7 @@
 
 A Model Context Protocol (MCP) server that integrates with AFFiNE (self‑hosted or cloud). It exposes AFFiNE workspaces and documents to AI assistants over stdio (default) or HTTP (`/mcp`).
 
-[![Version](https://img.shields.io/badge/version-1.9.0-blue)](https://github.com/dawncr0w/affine-mcp-server/releases)
+[![Version](https://img.shields.io/badge/version-1.10.0-blue)](https://github.com/dawncr0w/affine-mcp-server/releases)
 [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-1.17.2-green)](https://github.com/modelcontextprotocol/typescript-sdk)
 [![CI](https://github.com/dawncr0w/affine-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/dawncr0w/affine-mcp-server/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-MIT-yellow)](LICENSE)
@@ -16,10 +16,10 @@ A Model Context Protocol (MCP) server that integrates with AFFiNE (self‑hosted
 - Purpose: Manage AFFiNE workspaces and documents through MCP
 - Transport: stdio (default) and optional HTTP (`/mcp`) for remote MCP deployments
 - Auth: Token, Cookie, or Email/Password (priority order)
-- Tools: 47 focused tools with WebSocket-based document editing
+- Tools: 61 focused tools with WebSocket-based document editing
 - Status: Active
  
-> New in v1.9.0: Added database schema discovery, preset-backed data views, self-bootstrapping comprehensive regression, focused supporting-tools coverage, and markdown callout round-trips.
+> New in v1.10.0: Added document search/discovery utilities, template and batch document workflows, optional OAuth-protected HTTP mode, richer CLI diagnostics, and an HTTP multi-session email/password auth fix.
 
 ## Features
 
@@ -93,7 +93,12 @@ The MCP server will use these credentials automatically.
 ```
 
 Other CLI commands:
+- `affine-mcp --help` / `-h` / `help` — show command help
 - `affine-mcp status` — show current config and test connection
+- `affine-mcp doctor` — run config and connectivity diagnostics
+- `affine-mcp show-config` — print the effective config with secrets redacted
+- `affine-mcp config-path` — print the config file path
+- `affine-mcp snippet <claude|cursor|codex> [--env]` — print ready-to-paste client configuration snippets
 - `affine-mcp logout` — remove stored credentials
 - `affine-mcp --version` / `-v` / `version` — print the installed CLI version and exit
 
@@ -186,6 +191,8 @@ Or with email/password for self-hosted instances (not supported on AFFiNE Cloud
 Tips
 - Prefer `affine-mcp login` or `AFFINE_API_TOKEN` for zero‑latency startup.
 - If your password contains `!` (zsh history expansion), wrap it in single quotes in shells or use the JSON config above.
+- `affine-mcp doctor` is the fastest way to confirm that your saved config still works.
+- `affine-mcp snippet claude --env` and `affine-mcp snippet codex --env` can generate ready-to-paste client setup from your current config.
 
 ### Codex CLI
 
@@ -246,12 +253,16 @@ If you want to host the server remotely (e.g., using Render, Railway, Docker, or
 Required:
 - `MCP_TRANSPORT=http`
 - `AFFINE_BASE_URL` (example: `https://app.affine.pro`)
-- One auth method:
+- `AFFINE_MCP_AUTH_MODE=bearer` (default) or `AFFINE_MCP_AUTH_MODE=oauth`
+
+Bearer mode backend auth:
 - `AFFINE_API_TOKEN` (recommended), or `AFFINE_COOKIE`, or `AFFINE_EMAIL` + `AFFINE_PASSWORD`
 
+OAuth mode backend auth:
+- `AFFINE_API_TOKEN` (required service credential for AFFiNE backend access)
+
 Recommended for remote/public deployments:
 - `AFFINE_MCP_HTTP_HOST=0.0.0.0`
-- `AFFINE_MCP_HTTP_TOKEN=<strong-random-token>` (protects `/mcp`, `/sse`, `/messages`)
 - `AFFINE_MCP_HTTP_ALLOWED_ORIGINS=<comma-separated-origins>` (for browser clients)
 
 Optional:
@@ -260,31 +271,68 @@ Optional:
 - `AFFINE_GRAPHQL_PATH` (defaults to `/graphql`)
 - `AFFINE_MCP_HTTP_ALLOW_ALL_ORIGINS=true` (testing only)
 
+Bearer-mode only:
+- `AFFINE_MCP_HTTP_TOKEN=<strong-random-token>` (protects `/mcp`, `/sse`, `/messages`)
+
+OAuth-mode only:
+- `AFFINE_MCP_PUBLIC_BASE_URL=https://mcp.yourdomain.com`
+- `AFFINE_OAUTH_ISSUER_URL=https://auth.yourdomain.com`
+- `AFFINE_OAUTH_SCOPES=mcp` (defaults to `mcp`)
+
+#### HTTP auth modes
+
+`AFFINE_MCP_AUTH_MODE=bearer` keeps the current static bearer-token behavior.
+
 ```bash
-# Export your configuration first
 export MCP_TRANSPORT=http
+export AFFINE_MCP_AUTH_MODE=bearer
 export AFFINE_API_TOKEN="your_token..."
-export AFFINE_MCP_HTTP_HOST="0.0.0.0" # Default: 127.0.0.1
+export AFFINE_MCP_HTTP_HOST="0.0.0.0"
 export AFFINE_MCP_HTTP_TOKEN="your-super-secret-token"
 export PORT=3000
 
-# Start in HTTP mode (Streamable HTTP on /mcp)
 npm run start:http
-# OR manually:
-# MCP_TRANSPORT=http node dist/index.js
-# ("sse" is still accepted at /sse)
 ```
 
+`AFFINE_MCP_AUTH_MODE=oauth` turns the MCP endpoint into an OAuth-protected resource for web MCP clients. In this mode:
+- the server exposes `/.well-known/oauth-protected-resource`
+- unauthenticated `/mcp` requests return `401` with a `WWW-Authenticate` challenge
+- `AFFINE_MCP_HTTP_TOKEN` and `?token=` are disabled
+- `sign_in` is not registered
+- `AFFINE_API_TOKEN` is still required so the server can call AFFiNE as a service credential
+
+```bash
+export MCP_TRANSPORT=http
+export AFFINE_MCP_AUTH_MODE=oauth
+export AFFINE_API_TOKEN="your-affine-service-token"
+export AFFINE_MCP_HTTP_HOST="0.0.0.0"
+export AFFINE_MCP_PUBLIC_BASE_URL="https://mcp.yourdomain.com"
+export AFFINE_OAUTH_ISSUER_URL="https://auth.yourdomain.com"
+export AFFINE_OAUTH_SCOPES="mcp"
+export PORT=3000
+
+npm run start:http
+```
+
+Notes for oauth mode:
+- use HTTPS for non-local deployments
+- `AFFINE_MCP_HTTP_ALLOW_ALL_ORIGINS=true` is rejected in oauth mode
+- tokens are validated against the issuer discovery metadata and JWKS
+- the protected resource metadata is also served at `/.well-known/oauth-protected-resource/mcp` for path-specific discovery
+- `GET /healthz` and `GET /readyz` are available for deployment diagnostics
+
 #### Recommended presets
 
 Local testing (HTTP mode):
 - `MCP_TRANSPORT=http`
+- `AFFINE_MCP_AUTH_MODE=bearer`
 - `AFFINE_MCP_HTTP_HOST=127.0.0.1`
 - `AFFINE_MCP_HTTP_TOKEN=<token>` (recommended even locally)
 - `AFFINE_MCP_HTTP_ALLOWED_ORIGINS=http://localhost:3000` (if testing from a browser app)
 
 Docker / container runtime:
 - `MCP_TRANSPORT=http`
+- `AFFINE_MCP_AUTH_MODE=bearer`
 - `AFFINE_MCP_HTTP_HOST=0.0.0.0`
 - `PORT=3000` (or container/platform port)
 - `AFFINE_MCP_HTTP_TOKEN=<strong-token>`
@@ -292,14 +340,19 @@ Docker / container runtime:
 
 Render / Railway / VPS (public endpoint):
 - `MCP_TRANSPORT=http`
+- `AFFINE_MCP_AUTH_MODE=bearer` or `oauth`
 - `AFFINE_MCP_HTTP_HOST=0.0.0.0`
-- `AFFINE_MCP_HTTP_TOKEN=<strong-token>`
+- `AFFINE_MCP_HTTP_TOKEN=<strong-token>` (bearer mode)
+- `AFFINE_MCP_PUBLIC_BASE_URL=<public base URL>` (oauth mode)
+- `AFFINE_OAUTH_ISSUER_URL=<issuer URL>` (oauth mode)
 - `AFFINE_MCP_HTTP_ALLOWED_ORIGINS=<your client origin(s)>`
 
 Endpoints currently available:
 - `/mcp` - MCP server (Streamable HTTP)
 - `/sse` - SSE endpoint (old protocol compatible)
 - `/messages` - Messages endpoint (old protocol compatible)
+- `/healthz` - HTTP liveness probe
+- `/readyz` - HTTP readiness probe
 
 ## Available Tools
 
@@ -313,6 +366,7 @@ Endpoints currently available:
 ### Documents
 - `list_docs` – list documents with pagination (includes `node.tags`)
 - `list_tags` – list all tags in a workspace
+- `search_docs` – fast title search with substring/prefix/exact matching, optional tag filtering, and updatedAt sorting
 - `list_docs_by_tag` – list documents by tag
 - `get_doc` – get document metadata
 - `read_doc` – read document block content and plain text snapshot (WebSocket)
@@ -380,7 +434,7 @@ npm run pack:check
 - For full tool-surface verification, run `npm run test:comprehensive` (self-bootstraps a local Docker AFFiNE stack).
 - For pre-provisioned environments, use `npm run test:comprehensive:raw`.
 - For full environment verification, run `npm run test:e2e` (Docker + MCP + Playwright).
-- Additional focused runners: `npm run test:db-create`, `npm run test:db-cells`, `npm run test:db-schema`, `npm run test:supporting-tools`, `npm run test:bearer`, `npm run test:cli-version`, `npm run test:playwright`.
+- Additional focused runners: `npm run test:db-create`, `npm run test:db-cells`, `npm run test:db-schema`, `npm run test:supporting-tools`, `npm run test:bearer`, `npm run test:http-email-password`, `npm run test:http-bearer`, `npm run test:oauth-http`, `npm run test:doc-discovery`, `npm run test:cli-version`, `npm run test:cli-commands`, `npm run test:playwright`.
 
 ## Troubleshooting
 

package/dist/cli.js

@@ -1,7 +1,7 @@
 import { fetch } from "undici";
 import * as fs from "fs";
 import * as readline from "readline";
-import { CONFIG_FILE, loadConfigFile, writeConfigFile, validateBaseUrl, VERSION } from "./config.js";
+import { CONFIG_FILE, loadConfig, loadConfigFile, validateBaseUrl, VERSION, writeConfigFile } from "./config.js";
 import { loginWithPassword } from "./auth.js";
 const CLI_FETCH_TIMEOUT_MS = 30_000;
 class CliError extends Error {
@@ -42,12 +42,12 @@ function readHidden(prompt) {
                     process.stderr.write("\n");
                     resolve(buf.join(""));
                     break;
-                case "\u0003": // Ctrl-C
+                case "\u0003":
                     cleanup();
                     process.stderr.write("\n");
                     reject(new CliError("Aborted."));
                     break;
-                case "\u007F": // Backspace
+                case "\u007F":
                 case "\b":
                     buf.pop();
                     break;
@@ -69,9 +69,9 @@ async function gql(baseUrl, auth, query, variables) {
         "User-Agent": `affine-mcp-server/${VERSION}`,
     };
     if (auth.token)
-        headers["Authorization"] = `Bearer ${auth.token}`;
+        headers.Authorization = `Bearer ${auth.token}`;
     if (auth.cookie)
-        headers["Cookie"] = auth.cookie;
+        headers.Cookie = auth.cookie;
     const body = { query };
     if (variables)
         body.variables = variables;
@@ -87,8 +87,9 @@ async function gql(baseUrl, auth, query, variables) {
         });
     }
     catch (err) {
-        if (err.name === "AbortError")
+        if (err.name === "AbortError") {
             throw new Error(`Request timed out after ${CLI_FETCH_TIMEOUT_MS / 1000}s`);
+        }
         throw err;
     }
     finally {
@@ -101,6 +102,112 @@ async function gql(baseUrl, auth, query, variables) {
         throw new Error(json.errors.map((e) => e.message).join("; "));
     return json.data;
 }
+function parseFlag(args, ...flags) {
+    return args.some((arg) => flags.includes(arg));
+}
+function ensureNoUnexpectedArgs(args, command) {
+    if (args.length > 0) {
+        throw new CliError(`Unexpected arguments for '${command}': ${args.join(" ")}`);
+    }
+}
+function redactSecret(value) {
+    if (!value)
+        return null;
+    if (value.length <= 8)
+        return "*".repeat(value.length);
+    return `${value.slice(0, 4)}…${value.slice(-4)}`;
+}
+function getConfigValueSource(name, file, fallback) {
+    if (process.env[name])
+        return "env";
+    if (file[name])
+        return "config";
+    if (fallback !== undefined)
+        return "default";
+    return "unset";
+}
+function buildEffectiveConfigSummary() {
+    const stored = loadConfigFile();
+    const effective = loadConfig();
+    const authKind = effective.apiToken
+        ? "api-token"
+        : effective.cookie
+            ? "cookie"
+            : effective.email && effective.password
+                ? "email-password"
+                : "none";
+    return {
+        configFile: CONFIG_FILE,
+        configFileExists: fs.existsSync(CONFIG_FILE),
+        baseUrl: effective.baseUrl,
+        graphqlPath: effective.graphqlPath,
+        workspaceId: effective.defaultWorkspaceId || null,
+        authMode: effective.authMode,
+        authKind,
+        apiToken: effective.apiToken ? redactSecret(effective.apiToken) : null,
+        cookie: effective.cookie ? "(set)" : null,
+        email: effective.email || null,
+        publicBaseUrl: effective.publicBaseUrl || null,
+        oauthIssuerUrl: effective.oauthIssuerUrl || null,
+        oauthScopes: effective.oauthScopes,
+        sources: {
+            baseUrl: getConfigValueSource("AFFINE_BASE_URL", stored, "http://localhost:3010"),
+            apiToken: getConfigValueSource("AFFINE_API_TOKEN", stored),
+            cookie: getConfigValueSource("AFFINE_COOKIE", stored),
+            email: getConfigValueSource("AFFINE_EMAIL", stored),
+            password: getConfigValueSource("AFFINE_PASSWORD", stored),
+            workspaceId: getConfigValueSource("AFFINE_WORKSPACE_ID", stored),
+            authMode: getConfigValueSource("AFFINE_MCP_AUTH_MODE", stored, "bearer"),
+            publicBaseUrl: getConfigValueSource("AFFINE_MCP_PUBLIC_BASE_URL", stored),
+            oauthIssuerUrl: getConfigValueSource("AFFINE_OAUTH_ISSUER_URL", stored),
+            oauthScopes: getConfigValueSource("AFFINE_OAUTH_SCOPES", stored, "mcp"),
+        },
+    };
+}
+async function resolveCliAuth(baseUrl) {
+    const effective = loadConfig();
+    if (effective.apiToken) {
+        return { auth: { token: effective.apiToken }, authKind: "api-token" };
+    }
+    if (effective.cookie) {
+        return { auth: { cookie: effective.cookie }, authKind: "cookie" };
+    }
+    if (effective.email && effective.password) {
+        const { cookieHeader } = await loginWithPassword(baseUrl, effective.email, effective.password);
+        return { auth: { cookie: cookieHeader }, authKind: "email-password" };
+    }
+    throw new CliError("No authentication configured. Run 'affine-mcp login' or set AFFINE_API_TOKEN.");
+}
+function printHelp(command) {
+    if (command) {
+        const definition = COMMANDS[command];
+        if (!definition) {
+            throw new CliError(`Unknown command '${command}'.`);
+        }
+        console.log(`${definition.usage}\n`);
+        console.log(definition.summary);
+        return;
+    }
+    console.log(`affine-mcp ${VERSION}`);
+    console.log("");
+    console.log("Usage:");
+    console.log("  affine-mcp                 Start the MCP server over stdio");
+    console.log("  affine-mcp <command>       Run a CLI command");
+    console.log("");
+    console.log("Commands:");
+    for (const [name, definition] of Object.entries(COMMANDS)) {
+        console.log(`  ${name.padEnd(12)} ${definition.summary}`);
+    }
+    console.log("");
+    console.log("Common examples:");
+    console.log("  affine-mcp login");
+    console.log("  affine-mcp status");
+    console.log("  affine-mcp doctor");
+    console.log("  affine-mcp show-config --json");
+    console.log("  affine-mcp snippet claude --env");
+    console.log("  affine-mcp --version");
+    console.log("  affine-mcp --help");
+}
 async function detectWorkspace(baseUrl, auth) {
     console.error("Detecting workspaces...");
     try {
@@ -157,7 +264,6 @@ async function loginWithEmail(baseUrl) {
     catch (err) {
         throw new CliError(`Sign-in failed: ${err.message}`);
     }
-    // Verify identity
     const auth = { cookie: cookieHeader };
     try {
         const data = await gql(baseUrl, auth, "query { currentUser { name email } }");
@@ -166,7 +272,6 @@ async function loginWithEmail(baseUrl) {
     catch (err) {
         throw new CliError(`Session verification failed: ${err.message}`);
     }
-    // Auto-generate an API token so the MCP server can use token auth (no cookie expiry issues)
     console.error("Generating API token...");
     let token;
     try {
@@ -201,13 +306,13 @@ async function loginWithToken(baseUrl) {
     const workspaceId = await detectWorkspace(baseUrl, { token });
     return { token, workspaceId };
 }
-async function login() {
+async function login(_args) {
     console.error("Affine MCP Server — Login\n");
     const existing = loadConfigFile();
     if (existing.AFFINE_API_TOKEN) {
         console.error(`Existing config: ${CONFIG_FILE}`);
         console.error(`  URL:       ${existing.AFFINE_BASE_URL || "(default)"}`);
-        console.error(`  Token:     (set)`);
+        console.error("  Token:     (set)");
         console.error(`  Workspace: ${existing.AFFINE_WORKSPACE_ID || "(none)"}\n`);
         const overwrite = await ask("Overwrite? [y/N] ");
         if (!/^[yY]$/.test(overwrite)) {
@@ -223,15 +328,9 @@ async function login() {
     let result;
     if (isSelfHosted) {
         const method = await ask("\nAuth method — [1] Email/password (recommended)  [2] Paste API token: ");
-        if (method === "2") {
-            result = await loginWithToken(baseUrl);
-        }
-        else {
-            result = await loginWithEmail(baseUrl);
-        }
+        result = method === "2" ? await loginWithToken(baseUrl) : await loginWithEmail(baseUrl);
     }
     else {
-        // Cloudflare blocks programmatic sign-in on app.affine.pro — token is the only option
         result = await loginWithToken(baseUrl);
     }
     writeConfigFile({
@@ -242,14 +341,15 @@ async function login() {
     console.error(`\n✓ Saved to ${CONFIG_FILE} (mode 600)`);
     console.error("The MCP server will use these credentials automatically.");
 }
-async function status() {
+async function status(args) {
+    ensureNoUnexpectedArgs(args, "status");
     const config = loadConfigFile();
     if (!config.AFFINE_API_TOKEN) {
         throw new CliError("Not logged in. Run: affine-mcp login");
     }
     console.error(`Config: ${CONFIG_FILE}`);
     console.error(`URL:       ${config.AFFINE_BASE_URL || "(default)"}`);
-    console.error(`Token:     (set)`);
+    console.error("Token:     (set)");
     console.error(`Workspace: ${config.AFFINE_WORKSPACE_ID || "(none)"}\n`);
     try {
         const data = await gql(config.AFFINE_BASE_URL || "https://app.affine.pro", { token: config.AFFINE_API_TOKEN }, "query { currentUser { name email } workspaces { id } }");
@@ -260,7 +360,8 @@ async function status() {
         throw new CliError(`Connection failed: ${err.message}`);
     }
 }
-function logout() {
+function logout(args) {
+    ensureNoUnexpectedArgs(args, "logout");
     if (fs.existsSync(CONFIG_FILE)) {
         fs.unlinkSync(CONFIG_FILE);
         console.error(`Removed ${CONFIG_FILE}`);
@@ -269,13 +370,248 @@ function logout() {
         console.error("No config file found.");
     }
 }
-const COMMANDS = { login, status, logout };
-export async function runCli(command) {
-    const fn = COMMANDS[command];
-    if (!fn)
+function configPath(args) {
+    ensureNoUnexpectedArgs(args, "config-path");
+    console.log(CONFIG_FILE);
+}
+function showConfig(args) {
+    const asJson = parseFlag(args, "--json");
+    const unexpectedArgs = args.filter((arg) => arg !== "--json");
+    if (unexpectedArgs.length > 0) {
+        throw new CliError(`Unexpected arguments for 'show-config': ${unexpectedArgs.join(" ")}`);
+    }
+    const summary = buildEffectiveConfigSummary();
+    if (asJson) {
+        console.log(JSON.stringify(summary, null, 2));
+        return;
+    }
+    console.log(`Config file: ${summary.configFile} (${summary.configFileExists ? "found" : "missing"})`);
+    console.log(`Base URL: ${summary.baseUrl} (${summary.sources.baseUrl})`);
+    console.log(`GraphQL path: ${summary.graphqlPath}`);
+    console.log(`Auth mode: ${summary.authMode} (${summary.sources.authMode})`);
+    console.log(`Auth kind: ${summary.authKind}`);
+    console.log(`Workspace: ${summary.workspaceId || "(none)"} (${summary.sources.workspaceId})`);
+    if (summary.apiToken)
+        console.log(`API token: ${summary.apiToken} (${summary.sources.apiToken})`);
+    if (summary.cookie)
+        console.log(`Cookie: ${summary.cookie} (${summary.sources.cookie})`);
+    if (summary.email)
+        console.log(`Email: ${summary.email} (${summary.sources.email})`);
+    if (summary.publicBaseUrl)
+        console.log(`Public base URL: ${summary.publicBaseUrl} (${summary.sources.publicBaseUrl})`);
+    if (summary.oauthIssuerUrl)
+        console.log(`OAuth issuer URL: ${summary.oauthIssuerUrl} (${summary.sources.oauthIssuerUrl})`);
+    if (summary.authMode === "oauth")
+        console.log(`OAuth scopes: ${summary.oauthScopes.join(", ")} (${summary.sources.oauthScopes})`);
+}
+async function doctor(args) {
+    const asJson = parseFlag(args, "--json");
+    const unexpectedArgs = args.filter((arg) => arg !== "--json");
+    if (unexpectedArgs.length > 0) {
+        throw new CliError(`Unexpected arguments for 'doctor': ${unexpectedArgs.join(" ")}`);
+    }
+    const summary = buildEffectiveConfigSummary();
+    const checks = [];
+    checks.push({
+        name: "config-file",
+        ok: summary.configFileExists,
+        detail: summary.configFileExists ? summary.configFile : "No saved config file found",
+    });
+    let authKind = "none";
+    try {
+        const { auth, authKind: resolvedAuthKind } = await resolveCliAuth(summary.baseUrl);
+        authKind = resolvedAuthKind;
+        checks.push({
+            name: "auth-configured",
+            ok: true,
+            detail: `Using ${resolvedAuthKind}`,
+        });
+        const healthController = new AbortController();
+        const healthTimer = setTimeout(() => healthController.abort(), CLI_FETCH_TIMEOUT_MS);
+        try {
+            const response = await fetch(summary.baseUrl, { signal: healthController.signal });
+            checks.push({
+                name: "base-url",
+                ok: response.ok,
+                detail: `HTTP ${response.status}`,
+            });
+        }
+        catch (err) {
+            checks.push({
+                name: "base-url",
+                ok: false,
+                detail: err?.message || "Could not reach base URL",
+            });
+        }
+        finally {
+            clearTimeout(healthTimer);
+        }
+        try {
+            const data = await gql(summary.baseUrl, auth, "query { currentUser { name email } workspaces { id } }");
+            checks.push({
+                name: "graphql-auth",
+                ok: true,
+                detail: `${data.currentUser.email} (${data.workspaces.length} workspace(s))`,
+            });
+        }
+        catch (err) {
+            checks.push({
+                name: "graphql-auth",
+                ok: false,
+                detail: err?.message || "GraphQL auth failed",
+            });
+        }
+    }
+    catch (err) {
+        checks.push({
+            name: "auth-configured",
+            ok: false,
+            detail: err?.message || "No authentication configured",
+        });
+    }
+    if (summary.authMode === "oauth") {
+        const oauthReady = Boolean(summary.publicBaseUrl && summary.oauthIssuerUrl && summary.oauthScopes.length > 0);
+        checks.push({
+            name: "oauth-config",
+            ok: oauthReady,
+            detail: oauthReady
+                ? `${summary.publicBaseUrl} -> ${summary.oauthIssuerUrl}`
+                : "OAuth mode requires AFFINE_MCP_PUBLIC_BASE_URL and AFFINE_OAUTH_ISSUER_URL",
+        });
+    }
+    const ok = checks.every((check) => check.ok);
+    if (asJson) {
+        console.log(JSON.stringify({
+            ok,
+            config: summary,
+            checks,
+            authKind,
+        }, null, 2));
+        if (!ok)
+            process.exit(1);
+        return;
+    }
+    console.log(`Doctor: ${ok ? "OK" : "FAILED"}`);
+    console.log(`Base URL: ${summary.baseUrl}`);
+    console.log(`Auth mode: ${summary.authMode}`);
+    for (const check of checks) {
+        console.log(`${check.ok ? "✓" : "✗"} ${check.name}: ${check.detail}`);
+    }
+    if (!ok) {
+        throw new CliError("Doctor checks failed.");
+    }
+}
+function getSnippetEnv() {
+    const effective = loadConfig();
+    const env = {};
+    if (effective.baseUrl)
+        env.AFFINE_BASE_URL = effective.baseUrl;
+    if (effective.apiToken)
+        env.AFFINE_API_TOKEN = effective.apiToken;
+    if (effective.defaultWorkspaceId)
+        env.AFFINE_WORKSPACE_ID = effective.defaultWorkspaceId;
+    if (effective.authMode === "oauth") {
+        env.AFFINE_MCP_AUTH_MODE = "oauth";
+        if (effective.publicBaseUrl)
+            env.AFFINE_MCP_PUBLIC_BASE_URL = effective.publicBaseUrl;
+        if (effective.oauthIssuerUrl)
+            env.AFFINE_OAUTH_ISSUER_URL = effective.oauthIssuerUrl;
+        if (effective.oauthScopes.length > 0)
+            env.AFFINE_OAUTH_SCOPES = effective.oauthScopes.join(" ");
+    }
+    return env;
+}
+function snippet(args) {
+    const target = args[0];
+    if (!target) {
+        throw new CliError("Usage: affine-mcp snippet <claude|cursor|codex> [--env]");
+    }
+    const includeEnv = parseFlag(args, "--env");
+    const unexpectedArgs = args.slice(1).filter((arg) => arg !== "--env");
+    if (unexpectedArgs.length > 0) {
+        throw new CliError(`Unexpected arguments for 'snippet': ${unexpectedArgs.join(" ")}`);
+    }
+    const env = includeEnv ? getSnippetEnv() : undefined;
+    if (target === "claude" || target === "cursor") {
+        const payload = {
+            mcpServers: {
+                affine: {
+                    command: "affine-mcp",
+                    ...(env && Object.keys(env).length > 0 ? { env } : {}),
+                },
+            },
+        };
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+    }
+    if (target === "codex") {
+        if (!env || Object.keys(env).length === 0) {
+            console.log("codex mcp add affine -- affine-mcp");
+            return;
+        }
+        const envArgs = Object.entries(env)
+            .map(([key, value]) => `--env ${key}=${JSON.stringify(value)}`)
+            .join(" ");
+        console.log(`codex mcp add affine ${envArgs} -- affine-mcp`);
+        return;
+    }
+    throw new CliError(`Unknown snippet target '${target}'. Expected claude, cursor, or codex.`);
+}
+function help(args) {
+    if (args.length > 1) {
+        throw new CliError("Usage: affine-mcp help [command]");
+    }
+    printHelp(args[0]);
+}
+const COMMANDS = {
+    help: {
+        summary: "Show CLI help",
+        usage: "affine-mcp help [command]",
+        handler: help,
+    },
+    login: {
+        summary: "Interactive login and config bootstrap",
+        usage: "affine-mcp login",
+        handler: login,
+    },
+    status: {
+        summary: "Test the saved config and print current user info",
+        usage: "affine-mcp status",
+        handler: status,
+    },
+    logout: {
+        summary: "Remove the saved config file",
+        usage: "affine-mcp logout",
+        handler: logout,
+    },
+    "config-path": {
+        summary: "Print the config file path",
+        usage: "affine-mcp config-path",
+        handler: configPath,
+    },
+    "show-config": {
+        summary: "Print the effective config (redacted)",
+        usage: "affine-mcp show-config [--json]",
+        handler: showConfig,
+    },
+    doctor: {
+        summary: "Run local config and connectivity diagnostics",
+        usage: "affine-mcp doctor [--json]",
+        handler: doctor,
+    },
+    snippet: {
+        summary: "Print ready-to-paste Claude/Cursor/Codex snippets",
+        usage: "affine-mcp snippet <claude|cursor|codex> [--env]",
+        handler: snippet,
+    },
+};
+export async function runCli(command, args = []) {
+    const normalizedCommand = command.trim().toLowerCase();
+    const definition = COMMANDS[normalizedCommand];
+    if (!definition)
         return false;
     try {
-        await fn();
+        await definition.handler(args);
     }
     catch (err) {
         if (err instanceof CliError) {