@dobbyai/mcp-external 1.1.0 → 1.2.0

package/dist/server.js

@@ -0,0 +1,1017 @@
+/**
+ * MCP Server factory
+ *
+ * Builds the Dobby MCP Server with all request handlers registered.
+ * Extracted from index.ts (2026-07-12) so tests can exercise the REAL
+ * handlers — index.ts runs main() on import, which is unsafe under vitest.
+ *
+ * In STDIO mode: tenant context comes from env/CLI config; full tool access
+ * (the local key already proves the tenant).
+ * In HTTP mode: tenant context comes from the OAuth token; tool access is
+ * ENFORCED per token from authInfo.scopes — the introspection endpoint
+ * (web/app/oauth/token/introspect) derives the effective mcp scope from the
+ * org's plan (tier) + the token's own scopes (read vs execute).
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { createDobbyClient, DobbyClient } from "./lib/dobby-client.js";
+import { resolveSessionGatewayKey } from "./lib/gateway-key-resolver.js";
+import { getToolDefinitions, getToolAccessDenial, handleToolCall, resolveToolTier, isReadOnlyScopes, } from "./tools/index.js";
+import { resourceDefinitions, resourceTemplates, handleResourceRead, } from "./resources/index.js";
+import { promptDefinitions, handlePromptGet } from "./prompts/index.js";
+import { classifyKeyType } from "./lib/consts.js";
+/**
+ * Synthetic discovery tool for a user-scoped session (ADR-020). It is NOT a
+ * registered capability (keeps the registry at 131 + all golden/parity/tier
+ * tests byte-identical) — the server injects it into ListTools and handles it
+ * in CallTool only when the session is user-scoped, because it is meaningless
+ * for a tenant-pinned connection (you already know your one tenant).
+ */
+const USER_SCOPED_TENANTS_TOOL = "list_my_tenants";
+const USER_SCOPED_TENANTS_TOOL_DEF = {
+    name: USER_SCOPED_TENANTS_TOOL,
+    description: "List the tenants (workspaces) and organizations you can act in, with your " +
+        "live role in each. Use a returned tenant_id as the `tenant_id` argument to " +
+        "other tools in this user-scoped connection.",
+    inputSchema: {
+        type: "object",
+        properties: {},
+        additionalProperties: false,
+    },
+    annotations: {
+        title: "List my tenants",
+        readOnlyHint: true,
+        destructiveHint: false,
+        openWorldHint: false,
+    },
+};
+/**
+ * Structured "needs_selection" envelope — a user-scoped call omitted the scope
+ * argument it needs. Returned as machine-readable JSON (a client can JSON.parse
+ * `content[0].text` and read `status`/`argument`/`list_tool`) that is ALSO
+ * human-readable via the `message` field. isError stays true: the call could not
+ * proceed. UAT onboarding: return needs_selection, never silently inherit scope.
+ */
+export function needsSelectionResult(select, argument, listTool) {
+    const article = select === "organization" ? "an" : "a";
+    const envelope = {
+        status: "needs_selection",
+        select,
+        argument,
+        list_tool: listTool,
+        message: `This is a user-scoped connection with no fixed ${select}. Call ` +
+            `"${listTool}" to see the ${select}s you can access, then re-call this ` +
+            `tool with ${article} "${argument}" argument naming the ${select} to act in.`,
+    };
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(envelope, null, 2) },
+        ],
+        isError: true,
+    };
+}
+/**
+ * Structured "needs_pat" envelope — an identity/discovery call needs a Personal
+ * Access Token that is absent or not accepted. Names the env var to set and what
+ * it unlocks, as machine-readable JSON with a human `message` (UAT onboarding).
+ */
+export function needsPatResult(unlocks, detail) {
+    const envelope = {
+        status: "needs_pat",
+        token_prefix: "dobby_pat_",
+        env_var: "DOBBY_API_KEY",
+        unlocks,
+        message: `A Personal Access Token (dobby_pat_…) is required to ${unlocks}. ` +
+            `Provide it as the DOBBY_API_KEY env var (or connect via OAuth to ` +
+            `mcp.dobby-ai.com), then retry. Create one under Settings → Personal ` +
+            `Access Tokens.` +
+            (detail ? ` (server said: ${detail})` : ""),
+    };
+    return {
+        content: [
+            { type: "text", text: JSON.stringify(envelope, null, 2) },
+        ],
+        isError: true,
+    };
+}
+/**
+ * Handle the synthetic `list_my_tenants` tool. Calls the web user-scoped
+ * endpoint (PAT-authed) that returns the caller's tenants + orgs + live role in
+ * each, so a user-scoped client can populate the `tenant_id` argument.
+ */
+async function handleListMyTenants(apiUrl, token) {
+    try {
+        const response = await fetch(`${apiUrl}/api/v1/me/tenants`, {
+            method: "GET",
+            headers: {
+                "Content-Type": "application/json",
+                "X-API-Key": token,
+            },
+        });
+        if (!response.ok) {
+            const body = await response.text();
+            if (response.status === 401) {
+                return needsPatResult("list the tenants you can act in", body.slice(0, 200));
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to list your tenants (${response.status}): ${body}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const data = (await response.json());
+        const tenants = data.tenants ?? [];
+        if (tenants.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "You are not a member of any tenants.",
+                    },
+                ],
+                isError: false,
+            };
+        }
+        const lines = tenants.map((t) => `• ${t.name || t.tenant_id} — tenant_id: ${t.tenant_id}` +
+            (t.role ? ` · role: ${t.role}` : "") +
+            (t.region ? ` · region: ${t.region}` : "") +
+            (t.organization_id ? ` · org: ${t.organization_id}` : ""));
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `You can act in ${tenants.length} tenant(s). Pass the tenant_id of ` +
+                        `the one you want when calling a tool:\n\n${lines.join("\n")}`,
+                },
+            ],
+            isError: false,
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to list your tenants: ${error.message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+/**
+ * Short-prompt onboarding: resolve the caller's SOLE tenant. Returns the
+ * tenant_id when the user belongs to exactly ONE tenant — so a user-scoped call
+ * that omitted `tenant_id` can proceed silently without a needs_selection
+ * round-trip — or null when there are zero, many, or the lookup fails (the
+ * caller then falls back to the structured needs_selection envelope). Reuses the
+ * same PAT-authed /api/v1/me/tenants endpoint as list_my_tenants.
+ */
+export async function resolveSoleTenant(apiUrl, token) {
+    try {
+        const response = await fetch(`${apiUrl}/api/v1/me/tenants`, {
+            method: "GET",
+            headers: { "Content-Type": "application/json", "X-API-Key": token },
+        });
+        if (!response.ok)
+            return null;
+        const data = (await response.json());
+        const tenants = data.tenants ?? [];
+        return tenants.length === 1 ? tenants[0].tenant_id : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Synthetic discovery tool for the ORG side of a user-scoped session (ADR-020),
+ * the sibling of `list_my_tenants`. Also NOT a registered capability (keeps the
+ * registry at 131 + all golden/parity/tier tests byte-identical) — injected
+ * into ListTools and handled in CallTool only for a user-scoped session.
+ */
+const USER_SCOPED_ORGS_TOOL = "list_my_orgs";
+const USER_SCOPED_ORGS_TOOL_DEF = {
+    name: USER_SCOPED_ORGS_TOOL,
+    description: "List the organizations you can act in, with your live role in each. Use a " +
+        "returned organization_id as the `org_id` argument to org-scoped tools " +
+        "(memory stores, rubrics, orchestration configs) in this user-scoped connection.",
+    inputSchema: {
+        type: "object",
+        properties: {},
+        additionalProperties: false,
+    },
+    annotations: {
+        title: "List my organizations",
+        readOnlyHint: true,
+        destructiveHint: false,
+        openWorldHint: false,
+    },
+};
+/**
+ * Handle the synthetic `list_my_orgs` tool. Calls the web user-scoped endpoint
+ * (PAT-authed) that returns the caller's orgs + live role in each, so a
+ * user-scoped client can populate the `org_id` argument.
+ */
+async function handleListMyOrgs(apiUrl, token) {
+    try {
+        const response = await fetch(`${apiUrl}/api/v1/me/organizations`, {
+            method: "GET",
+            headers: {
+                "Content-Type": "application/json",
+                "X-API-Key": token,
+            },
+        });
+        if (!response.ok) {
+            const body = await response.text();
+            if (response.status === 401) {
+                return needsPatResult("list the organizations you can act in", body.slice(0, 200));
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to list your organizations (${response.status}): ${body}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const data = (await response.json());
+        const orgs = data.organizations ?? [];
+        if (orgs.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "You are not a member of any organizations.",
+                    },
+                ],
+                isError: false,
+            };
+        }
+        const lines = orgs.map((o) => `• ${o.name || o.organization_id} — org_id: ${o.organization_id}` +
+            (o.role ? ` · role: ${o.role}` : ""));
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `You can act in ${orgs.length} organization(s). Pass the org_id of ` +
+                        `the one you want as the "org_id" argument:\n\n${lines.join("\n")}`,
+                },
+            ],
+            isError: false,
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to list your organizations: ${error.message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+/**
+ * Synthetic `whoami` tool (onboarding identity echo). Unlike list_my_tenants /
+ * list_my_orgs it is available in BOTH transports and is NEVER gated or errored
+ * — its whole job is to answer "who am I, what can this key do, is a PAT present,
+ * which environment am I on?" so an onboarding agent never has to read `ps aux`
+ * or guess which org/tenant it silently inherited. NOT a registered capability
+ * (keeps the registry at 131 + all golden/parity/tier tests byte-identical).
+ */
+const WHOAMI_TOOL = "whoami";
+export const WHOAMI_TOOL_DEF = {
+    name: WHOAMI_TOOL,
+    description: "Report the current connection identity and what your credentials can do: " +
+        "transport, API URL, key type, the tenant/organization/user in context, whether " +
+        "a Personal Access Token is present, and your scopes. Never fails on missing " +
+        "credentials — it reports exactly what is set and what is missing. Call this " +
+        "FIRST to confirm which environment (prod vs dev) and which scope you are acting in.",
+    inputSchema: {
+        type: "object",
+        properties: {},
+        additionalProperties: false,
+    },
+    annotations: {
+        title: "Who am I",
+        readOnlyHint: true,
+        destructiveHint: false,
+        openWorldHint: false,
+    },
+};
+/**
+ * Build the identity echo for `whoami`. Never throws and never returns an error
+ * envelope — missing credentials are reported as `missing[]` notes, not failures.
+ */
+export function handleWhoami(input) {
+    const missing = [];
+    let identity;
+    if (input.mode === "stdio") {
+        const keyType = classifyKeyType(input.apiKey);
+        if (keyType === "none")
+            missing.push("DOBBY_API_KEY (no key configured)");
+        if (!input.tenantId)
+            missing.push("DOBBY_TENANT_ID (no default workspace set)");
+        if (keyType === "pat") {
+            missing.push("gateway/execute tools disabled — a dobby_pat_ cannot mint a gateway key in local STDIO; use a gk_ key, or connect over the remote HTTP transport (mcp.dobby-ai.com)");
+        }
+        else if (!input.gatewayEnabled) {
+            missing.push("DOBBY_GATEWAY_KEY (gateway/execute tools disabled; a gk_ DOBBY_API_KEY also enables them)");
+        }
+        identity = {
+            transport: "stdio",
+            api_url: input.apiUrl,
+            key_type: keyType,
+            pat_present: keyType === "pat",
+            gateway_tools_enabled: input.gatewayEnabled,
+            tenant_id: input.tenantId ?? null,
+            organization_id: input.organizationId ?? null,
+            user_id: input.userId,
+            user_scoped: false,
+            // Local STDIO is full-access; scopes are not enforced by the server.
+            scopes: null,
+            is_super_admin: null,
+        };
+    }
+    else {
+        const token = input.authInfo?.token;
+        const extra = input.authInfo?.extra;
+        const userScoped = extra?.user_scoped === true;
+        const keyType = classifyKeyType(token);
+        if (!token)
+            missing.push("bearer token (no authenticated session)");
+        if (userScoped && !extra?.tenant_id) {
+            missing.push('tenant_id — this is a user-scoped connection: pass a "tenant_id" argument per call, or run list_my_tenants to see your options');
+        }
+        identity = {
+            transport: "http",
+            api_url: input.apiUrl,
+            key_type: keyType,
+            pat_present: keyType === "pat" || userScoped,
+            tenant_id: extra?.tenant_id ?? null,
+            organization_id: extra?.org_id ?? null,
+            user_id: extra?.user_id ?? null,
+            user_scoped: userScoped,
+            tenant_role: extra?.tenant_role ?? null,
+            org_role: extra?.org_role ?? null,
+            is_super_admin: extra?.is_super_admin === true,
+            scopes: input.authInfo?.scopes ?? [],
+        };
+    }
+    const summary = Object.entries(identity)
+        .map(([k, v]) => {
+        const rendered = v === null
+            ? "—"
+            : Array.isArray(v)
+                ? v.length
+                    ? v.join(", ")
+                    : "—"
+                : String(v);
+        return `• ${k}: ${rendered}`;
+    })
+        .join("\n");
+    const missingBlock = missing.length
+        ? `\n\nMissing / notes:\n${missing.map((m) => `⚠️ ${m}`).join("\n")}`
+        : "\n\n✅ Nothing missing for the current scope.";
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Dobby MCP — current identity\n\n${summary}${missingBlock}\n\n` +
+                    "```json\n" +
+                    JSON.stringify({ ...identity, missing }, null, 2) +
+                    "\n```",
+            },
+        ],
+        isError: false,
+    };
+}
+/**
+ * Synthetic `validate_credentials` tool. The sibling of `whoami`: where whoami
+ * ECHOES the session identity, this CONFIRMS the credentials actually work — it
+ * classifies the key, and in STDIO runs a live reachability probe so an
+ * onboarding agent can fail fast with one clear message instead of hunting
+ * through a scatter of downstream 401/404/500s. Like whoami it is a synthetic
+ * tool (registry stays 131), available in both transports, and NEVER throws —
+ * it reports what fails and the exact env var that supplies each credential.
+ * This is the MCP-callable counterpart of the `dobby-mcp --doctor` CLI (which an
+ * autonomous agent cannot run).
+ */
+const VALIDATE_CREDENTIALS_TOOL = "validate_credentials";
+export const VALIDATE_CREDENTIALS_TOOL_DEF = {
+    name: VALIDATE_CREDENTIALS_TOOL,
+    description: "Check whether your configured credentials actually work. Reports, per " +
+        "credential, present / format_ok / authorized (a live reachability probe in " +
+        "STDIO) plus the exact env var that supplies it. Complements whoami (which " +
+        "only echoes identity). Never throws — it reports what fails. Call this if a " +
+        "tool returns an auth error and you are unsure which credential is the problem.",
+    inputSchema: {
+        type: "object",
+        properties: {},
+        additionalProperties: false,
+    },
+    annotations: {
+        title: "Validate credentials",
+        readOnlyHint: true,
+        destructiveHint: false,
+        openWorldHint: false,
+    },
+};
+/**
+ * Run the credential validation. Never throws / never returns isError:true —
+ * failures are reported as `report.*.authorized=false` + `notes[]`.
+ */
+export async function handleValidateCredentials(input) {
+    const report = {
+        transport: input.mode,
+        api_url: input.apiUrl,
+    };
+    const notes = [];
+    if (input.mode === "stdio") {
+        const keyType = classifyKeyType(input.apiKey);
+        const present = keyType !== "none";
+        const formatOk = keyType === "gateway" || keyType === "tenant" || keyType === "pat";
+        // Live authorization probe — only when we have both a key and a tenant.
+        // checkHealth never throws (it catches internally), but guard anyway.
+        let authorized = null;
+        if (present && input.tenantId) {
+            try {
+                const probe = createDobbyClient({
+                    apiUrl: input.apiUrl,
+                    apiKey: input.apiKey,
+                    tenantId: input.tenantId,
+                });
+                authorized = await probe.checkHealth();
+            }
+            catch {
+                authorized = false;
+            }
+        }
+        if (!present) {
+            notes.push("Set DOBBY_API_KEY — a gk_user_/gk_svc_ gateway key, an sk_live_ tenant key, or (remote only) a dobby_pat_.");
+        }
+        else if (!formatOk) {
+            notes.push("DOBBY_API_KEY has an unrecognized prefix — expected gk_user_/gk_svc_/gk_tmp_, sk_live_, or dobby_pat_.");
+        }
+        if (present && !input.tenantId) {
+            notes.push("Set DOBBY_TENANT_ID to run the live authorization probe (tenant-scoped tools also need it).");
+        }
+        if (authorized === false) {
+            notes.push(`Could not reach/authorize against ${input.apiUrl} — check DOBBY_API_URL, the key value, and the tenant.`);
+        }
+        if (keyType === "pat") {
+            notes.push("A dobby_pat_ does NOT enable gateway/execute tools in local STDIO — use a gk_ key, or the remote HTTP transport.");
+        }
+        report.api_key = {
+            present,
+            key_type: keyType,
+            format_ok: formatOk,
+            authorized,
+            env_var: "DOBBY_API_KEY",
+        };
+        report.gateway_tools = {
+            enabled: input.gatewayEnabled,
+            source: input.gatewaySource,
+            env_var: "DOBBY_GATEWAY_KEY",
+        };
+        report.tenant = {
+            present: Boolean(input.tenantId),
+            env_var: "DOBBY_TENANT_ID",
+        };
+        report.ok = present && formatOk && authorized !== false;
+    }
+    else {
+        const token = input.authInfo?.token;
+        const extra = input.authInfo?.extra;
+        const keyType = classifyKeyType(token);
+        const present = Boolean(token);
+        // We only reach here AFTER the token passed OAuth introspection, so an
+        // authenticated session is itself proof of authorization.
+        const authorized = present;
+        if (!present) {
+            notes.push("No bearer token — authenticate with OAuth or a dobby_pat_ against mcp.dobby-ai.com.");
+        }
+        if (extra?.user_scoped && !extra?.tenant_id) {
+            notes.push('User-scoped session: pass a "tenant_id" per call, or run list_my_tenants to see your options.');
+        }
+        report.api_key = {
+            present,
+            key_type: keyType,
+            format_ok: present,
+            authorized,
+            env_var: "Authorization: Bearer",
+        };
+        report.gateway_tools = {
+            enabled: true,
+            source: "gk_tmp_ minted per request from your session",
+        };
+        report.tenant = {
+            present: Boolean(extra?.tenant_id),
+            user_scoped: extra?.user_scoped === true,
+        };
+        report.scopes = input.authInfo?.scopes ?? [];
+        report.ok = present;
+    }
+    const notesBlock = notes.length
+        ? `\n\nNotes:\n${notes.map((n) => `⚠️ ${n}`).join("\n")}`
+        : "\n\n✅ Credentials look good for the current scope.";
+    return {
+        content: [
+            {
+                type: "text",
+                text: "Dobby MCP — credential validation\n\n```json\n" +
+                    JSON.stringify(report, null, 2) +
+                    "\n```" +
+                    notesBlock,
+            },
+        ],
+        isError: false,
+    };
+}
+/**
+ * ADR-020 user-scoped tool classification. A user-scoped PAT has no tenant/org
+ * pin, so an org-scoped tool must resolve its target ORG (not tenant) per call:
+ *  - ORG_CLIENT_TOOLS read `client.organizationId` (memory stores / rubrics /
+ *    orchestration configs). The caller passes an `org_id` argument, which the
+ *    server sets on the per-request client; the org REST route then authorizes
+ *    it live (withOrgAuth + tryPatOrgAuth → 403 for a non-member).
+ *  - ORG_ARG_TOOLS already take an explicit `organization_id` in their own
+ *    schema (the governance/policies tools), so they carry their own target —
+ *    the user-scoped branch just must NOT demand a tenant_id for them.
+ *  - PLATFORM_TOOLS are platform-scoped superadmin ops tools (health / status /
+ *    issues / audit). They target NO tenant or org — they call the web app's
+ *    /api/v1/internal/ops/* endpoints server-to-server (x-internal-secret), so
+ *    the user-scoped branch must NOT demand a tenant_id for them either. Their
+ *    visibility is still gated upstream by visibleTo({ isSuperAdmin }).
+ * Everything else is tenant-scoped and resolves from a per-call `tenant_id`.
+ */
+const ORG_CLIENT_TOOLS = new Set([
+    "memory_store_list",
+    "memory_store_read",
+    "memory_store_write",
+    "memory_store_search",
+    "memory_store_delete",
+    "rubric_list",
+    "rubric_create",
+    "orchestration_config_list",
+]);
+const ORG_ARG_TOOLS = new Set([
+    "export_policies",
+    "validate_policies",
+    "apply_guardrail",
+    "import_policies",
+]);
+// Platform-scoped superadmin ops tools (capability-core `superAdminOnly`). They
+// act on platform-global ops data via /api/v1/internal/ops/* (server-to-server
+// x-internal-secret), NOT on any tenant/org, so a user-scoped (PAT) connection
+// must NOT be asked for a tenant_id. Visibility is still gated upstream by
+// visibleTo({ isSuperAdmin }); this only stops the tenant-required default from
+// rejecting them once visible (ADR-020).
+const PLATFORM_TOOLS = new Set([
+    "get_ops_health_summary",
+    "get_service_status",
+    "get_active_issues",
+    "acknowledge_ops_issue",
+    "get_ops_audit_log",
+]);
+// ============================================
+// Gateway Key Resolution
+// ============================================
+/**
+ * Resolve the gateway key to use for auth + audit logging.
+ * Priority: explicit DOBBY_GATEWAY_KEY > auto-detect gk_* in DOBBY_API_KEY > undefined (disabled)
+ */
+export function resolveGatewayKey(opts) {
+    if (opts.gatewayKey)
+        return opts.gatewayKey;
+    if (opts.apiKey && opts.apiKey.startsWith("gk_"))
+        return opts.apiKey;
+    return undefined;
+}
+/**
+ * Create an MCP Server with all handlers registered.
+ *
+ * In STDIO mode: tenant context comes from config/env vars.
+ * In HTTP mode: tenant context comes from OAuth token (extra.authInfo.extra.tenant_id).
+ * The DobbyClient is created lazily per-request in HTTP mode.
+ */
+export async function createServer(opts = { mode: "stdio" }) {
+    const apiUrl = opts.apiUrl || process.env.DOBBY_API_URL || "https://dobby-ai.com";
+    // STDIO gateway auth context — resolved BEFORE the client so gateway-scoped
+    // fetch helpers send the gk_* downstream via client.gatewayBearer() (they
+    // previously always sent apiKey, so DOBBY_GATEWAY_KEY + sk_live_ setups
+    // never reached gateway-guarded routes).
+    const gatewayKey = resolveGatewayKey({
+        gatewayKey: opts.gatewayKey,
+        apiKey: opts.apiKey,
+    });
+    const gatewayUrl = opts.gatewayUrl || apiUrl;
+    // In STDIO mode, create a shared client from env vars
+    let stdioClient;
+    if (opts.mode === "stdio") {
+        stdioClient = createDobbyClient({
+            apiUrl: opts.apiUrl,
+            apiKey: opts.apiKey,
+            tenantId: opts.tenantId,
+            gatewayKey,
+        });
+    }
+    // HTTP mode: per-SESSION memoized gateway-key resolution. createServer() is
+    // instantiated once per HTTP session (index.ts wires it as http-server.ts's
+    // createMcpServer factory, called on each new Mcp-Session-Id), so this
+    // closure caches ONE resolved gk_tmp_* key per session. Memoized on FIRST
+    // use: the OAuth token may rotate mid-session, but the resolved key stays
+    // valid — it is identity-bound (tenant+user), not token-bound.
+    //
+    // Tenant-pinned families (dobby_at_/sk_live_) use this single-key memo. A
+    // user-scoped PAT (ADR-020) has no pin — its gateway-scoped tools are
+    // tenant-scoped and carry a per-call tenant_id, so it memoizes a gk_tmp_ PER
+    // TARGET TENANT here (a session-wide key would be wrong for a cross-tenant
+    // caller).
+    let sessionGatewayKey;
+    const patGatewayKeyByTenant = new Map();
+    // Create MCP server
+    const server = new Server({
+        name: "dobby-mcp-server",
+        version: "1.1.0",
+    }, {
+        capabilities: {
+            tools: {},
+            resources: {},
+            prompts: {},
+        },
+    });
+    // STDIO user context
+    const userContext = {
+        userId: process.env.DOBBY_USER_ID || "mcp-user",
+        userName: process.env.DOBBY_USER_NAME || "MCP User",
+    };
+    // ============================================
+    // Tools Handler
+    // ============================================
+    server.setRequestHandler(ListToolsRequestSchema, async (_request, extra) => {
+        // HTTP mode: the introspection endpoint put the EFFECTIVE mcp scope on
+        // the token (plan-derived tier + read/execute) — filter the list by it.
+        // STDIO mode stays full access (local setup, key already proves tenant).
+        if (opts.mode === "http") {
+            const scopes = extra.authInfo?.scopes ?? [];
+            const rbac = extra.authInfo?.extra;
+            const tools = getToolDefinitions(resolveToolTier({ scopes }), {
+                readOnly: isReadOnlyScopes(scopes),
+                role: rbac?.tenant_role,
+                isSuperAdmin: rbac?.is_super_admin,
+            });
+            // whoami + validate_credentials are always available (identity echo +
+            // credential check) — appended after the tier-filtered list so they show
+            // for every token family.
+            tools.push(WHOAMI_TOOL_DEF);
+            tools.push(VALIDATE_CREDENTIALS_TOOL_DEF);
+            // ADR-020: a user-scoped session also gets the synthetic discovery tools
+            // so a client can enumerate the tenants + organizations it may act in.
+            // Append-only — a tenant-pinned session (and the byte-identical golden
+            // tests) is unchanged.
+            if (rbac?.user_scoped) {
+                tools.push(USER_SCOPED_TENANTS_TOOL_DEF);
+                tools.push(USER_SCOPED_ORGS_TOOL_DEF);
+            }
+            return { tools };
+        }
+        return {
+            tools: [
+                ...getToolDefinitions("enterprise"),
+                WHOAMI_TOOL_DEF,
+                VALIDATE_CREDENTIALS_TOOL_DEF,
+            ],
+        };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+        const { name, arguments: args } = request.params;
+        try {
+            // whoami — always available, never gated, never errors. Answer identity
+            // BEFORE any tier/tenant resolution so a caller can orient even when its
+            // credentials are missing or ambiguous.
+            if (name === WHOAMI_TOOL) {
+                return opts.mode === "http"
+                    ? handleWhoami({
+                        mode: "http",
+                        apiUrl,
+                        authInfo: extra.authInfo,
+                    })
+                    : handleWhoami({
+                        mode: "stdio",
+                        apiUrl,
+                        apiKey: opts.apiKey,
+                        tenantId: opts.tenantId ?? process.env.DOBBY_TENANT_ID,
+                        organizationId: process.env.DOBBY_ORGANIZATION_ID,
+                        gatewayEnabled: Boolean(gatewayKey),
+                        userId: userContext.userId,
+                    });
+            }
+            // validate_credentials — like whoami, always available and never gated.
+            // In STDIO it runs a live reachability probe, so it is async.
+            if (name === VALIDATE_CREDENTIALS_TOOL) {
+                return opts.mode === "http"
+                    ? await handleValidateCredentials({
+                        mode: "http",
+                        apiUrl,
+                        authInfo: extra.authInfo,
+                    })
+                    : await handleValidateCredentials({
+                        mode: "stdio",
+                        apiUrl,
+                        apiKey: opts.apiKey,
+                        tenantId: opts.tenantId ?? process.env.DOBBY_TENANT_ID,
+                        gatewayEnabled: Boolean(gatewayKey),
+                        gatewaySource: opts.gatewayKey
+                            ? "explicit"
+                            : opts.apiKey?.startsWith("gk_")
+                                ? "api_key"
+                                : "none",
+                    });
+            }
+            // HTTP mode: enforce tier + read-only on the CALL, not just the list —
+            // list filtering alone is cosmetic (clients can call any tool by name).
+            if (opts.mode === "http") {
+                const rbac = extra.authInfo?.extra;
+                const denial = getToolAccessDenial(name, {
+                    scopes: extra.authInfo?.scopes ?? [],
+                    role: rbac?.tenant_role,
+                    isSuperAdmin: rbac?.is_super_admin,
+                });
+                if (denial) {
+                    return {
+                        content: [{ type: "text", text: denial }],
+                        isError: true,
+                    };
+                }
+            }
+            let client;
+            let userId;
+            let userName;
+            let tenantId;
+            let region;
+            let gwKey;
+            let gwUrl;
+            // ADR-019/020 identity, threaded into the CapabilityContext so handlers
+            // can authorize per call (Wave 2/3). Empty in STDIO mode (local, full
+            // access). For a user-scoped PAT tenant_role/org_role are the AGGREGATE role.
+            let ctxOrgId;
+            let ctxScopes;
+            let ctxTenantRole;
+            let ctxOrgRole;
+            let ctxIsSuperAdmin = false;
+            if (opts.mode === "http" && extra.authInfo) {
+                // HTTP mode — resolve context from the introspected token.
+                const tokenExtra = extra.authInfo.extra;
+                const token = extra.authInfo.token;
+                const isGatewayKeyToken = token.startsWith("gk_");
+                const userScoped = tokenExtra?.user_scoped === true;
+                const tokenUserId = tokenExtra?.user_id || "oauth-user";
+                // Identity carried from introspection (ADR-019 P2 / ADR-020). For a
+                // user-scoped PAT, tenant_role/org_role are the AGGREGATE (max) role.
+                ctxOrgId = tokenExtra?.org_id ?? undefined;
+                ctxScopes = extra.authInfo.scopes ?? [];
+                ctxTenantRole = tokenExtra?.tenant_role;
+                ctxOrgRole = tokenExtra?.org_role;
+                ctxIsSuperAdmin = tokenExtra?.is_super_admin === true;
+                // User-scoped discovery tools (ADR-020): not registered capabilities,
+                // so intercept them before any tenant/org resolution or client build.
+                // They fetch directly (apiUrl + token) and need no per-request client.
+                if (userScoped && name === USER_SCOPED_TENANTS_TOOL) {
+                    return await handleListMyTenants(apiUrl, token);
+                }
+                if (userScoped && name === USER_SCOPED_ORGS_TOOL) {
+                    return await handleListMyOrgs(apiUrl, token);
+                }
+                // Resolve the TARGET tenant/org.
+                //  - Pinned families (dobby_at_/sk_live_/gk_): the token's single tenant
+                //    pin (org-scoped tools resolve their org downstream from the pin).
+                //  - User-scoped PAT (ADR-020): the target comes from a per-call
+                //    argument, authorized LIVE by the web REST layer (never a frozen
+                //    cross-tenant/cross-org grant):
+                //      · ORG_CLIENT_TOOLS → an `org_id` arg, set on the per-request
+                //        client so the handler's /organizations/{org}/… call is
+                //        authorized by withOrgAuth + tryPatOrgAuth (403 for a non-member).
+                //      · ORG_ARG_TOOLS → the tool's own `organization_id` arg carries
+                //        the target; nothing to require here.
+                //      · everything else is tenant-scoped → a `tenant_id` arg
+                //        (withTenantAuth + tryPatAuth → 403 for a non-member).
+                let targetTenantId;
+                let targetOrgId;
+                if (userScoped) {
+                    if (ORG_CLIENT_TOOLS.has(name)) {
+                        const rawOrgArg = args
+                            ?.org_id;
+                        const argOrg = typeof rawOrgArg === "string" ? rawOrgArg.trim() : "";
+                        if (!argOrg) {
+                            return needsSelectionResult("organization", "org_id", USER_SCOPED_ORGS_TOOL);
+                        }
+                        targetOrgId = argOrg;
+                    }
+                    else if (ORG_ARG_TOOLS.has(name)) {
+                        // The tool carries its own `organization_id`; its org REST route
+                        // authorizes the PAT live against it. No tenant/org to resolve here.
+                    }
+                    else if (PLATFORM_TOOLS.has(name)) {
+                        // Platform-scoped ops tool: targets no tenant/org (it hits
+                        // /api/v1/internal/ops/* server-to-server). Nothing to resolve here;
+                        // visibility is already gated by visibleTo({ isSuperAdmin }).
+                    }
+                    else {
+                        const rawTenantArg = args
+                            ?.tenant_id;
+                        const argTenant = typeof rawTenantArg === "string" ? rawTenantArg.trim() : "";
+                        if (!argTenant) {
+                            // Short-prompt UX: if the caller belongs to exactly ONE tenant,
+                            // auto-select it silently — no needs_selection round-trip, so
+                            // "create an agent named X" works from a single prompt. Ambiguous
+                            // cases (zero or many tenants) still return the structured
+                            // needs_selection envelope so the client asks which workspace.
+                            const sole = await resolveSoleTenant(apiUrl, token);
+                            if (!sole) {
+                                return needsSelectionResult("tenant", "tenant_id", USER_SCOPED_TENANTS_TOOL);
+                            }
+                            targetTenantId = sole;
+                        }
+                        else {
+                            targetTenantId = argTenant || undefined;
+                        }
+                    }
+                }
+                else {
+                    targetTenantId = tokenExtra?.tenant_id;
+                    if (!targetTenantId) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: "Error: OAuth token missing tenant_id",
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                    // Tenant-pinned families (dobby_at_ / sk_live_ / gk_) carry their org
+                    // in the token — wire it onto the per-request client so ORG-scoped
+                    // tools (memory_store_*, rubric_*, orchestration_config_list) work.
+                    // Those handlers read client.organizationId; without this a
+                    // tenant-pinned OAuth/sk_live_ session got "No organization context"
+                    // for every org-scoped tool even though whoami showed the org
+                    // (customer hit 2026-07-20). user-scoped PATs resolve org per-call
+                    // above, so this only fills the pinned case.
+                    targetOrgId = tokenExtra?.org_id ?? undefined;
+                }
+                // Reflect the per-call org target in the identity context too, so the
+                // CapabilityContext.orgId a handler sees matches the org it acts on.
+                if (targetOrgId)
+                    ctxOrgId = targetOrgId;
+                // Create per-request client using the session bearer as the API key
+                // (tenant-scoped tools send it as X-API-Key, which the web app accepts
+                // for all families: dobby_at_ / sk_live_ / gk_ / dobby_pat_).
+                //
+                // Gateway-scoped tools authenticate downstream with a gk_* key
+                // (authenticateGatewayRequest hard-requires one). The provider that
+                // supplies it differs by session family:
+                // - gk_* Bearer session: the token IS a gateway key — no provider;
+                //   gatewayBearer() falls back to apiKey and sends it downstream.
+                // - dobby_at_ / sk_live_ session: a LAZY provider exchanges the token
+                //   for a tenant+user-bound gk_tmp_* via the web app's internal
+                //   endpoint (tenant derived from the token), memoized once per session.
+                // - user-scoped PAT (ADR-020): gateway-scoped tools are tenant-scoped
+                //   and carry a per-call tenant_id, so the provider resolves a gk_tmp_*
+                //   for THAT tenant (memoized per tenant). The internal endpoint
+                //   authorizes the PAT's LIVE membership in the tenant before minting,
+                //   so no frozen cross-tenant grant is possible. Org-scoped tools have
+                //   no tenant → no gateway provider (they are not gateway-scoped).
+                let getGatewayKey;
+                if (isGatewayKeyToken) {
+                    getGatewayKey = undefined;
+                }
+                else if (userScoped) {
+                    if (targetTenantId) {
+                        const t = targetTenantId;
+                        getGatewayKey = () => {
+                            let p = patGatewayKeyByTenant.get(t);
+                            if (!p) {
+                                p = resolveSessionGatewayKey({ apiUrl, token, tenantId: t });
+                                patGatewayKeyByTenant.set(t, p);
+                            }
+                            return p;
+                        };
+                    }
+                }
+                else {
+                    getGatewayKey = () => (sessionGatewayKey ??= resolveSessionGatewayKey({ apiUrl, token }));
+                }
+                client = new DobbyClient({
+                    apiUrl,
+                    apiKey: token,
+                    tenantId: targetTenantId ?? "",
+                    // ADR-020 org-scoped tools (ORG_CLIENT_TOOLS): the per-call `org_id`
+                    // becomes the client's org context, which their handlers read via
+                    // client.organizationId to build /organizations/{org}/… requests.
+                    organizationId: targetOrgId,
+                    ...(getGatewayKey ? { getGatewayKey } : {}),
+                });
+                userId = tokenUserId;
+                userName = "OAuth User";
+                tenantId = targetTenantId;
+                region = undefined; // resolved by web app from tenant
+                // Gateway pre-check key (checkGatewayAuth → POST /api/v1/gateway/mcp/tools):
+                // - gk_* Bearer session: forward the token — restores the pre-check +
+                //   gateway metering for genuine gateway-key sessions (commit 157db598b
+                //   disabled it for ALL families; only OAuth/sk_live_ needed the skip).
+                // - dobby_at_ / sk_live_ / user-scoped session: leave it undefined —
+                //   the pre-check authenticates a gk_* GATEWAY key, and forwarding a
+                //   non-gk_ token made the gateway 404 → every tool denied "Not Found"
+                //   (found 2026-07-12 on the live claude.ai connector). Unset correctly
+                //   short-circuits the pre-check to allowed; the REAL gate for
+                //   gateway-scoped endpoints is downstream authenticateGatewayRequest,
+                //   reached with the resolved gk_tmp_* (client.gatewayBearer()).
+                gwKey = isGatewayKeyToken ? token : undefined;
+                gwUrl = apiUrl;
+            }
+            else {
+                // STDIO mode — use env vars
+                client = stdioClient;
+                userId = userContext.userId;
+                userName = userContext.userName;
+                tenantId = client.tenantId;
+                region = process.env.DOBBY_REGION;
+                gwKey = gatewayKey;
+                gwUrl = gatewayUrl;
+            }
+            const result = await handleToolCall(name, args || {}, {
+                client,
+                userId,
+                userName,
+                gatewayKey: gwKey,
+                gatewayUrl: gwUrl,
+                tenantId,
+                region,
+                orgId: ctxOrgId,
+                scopes: ctxScopes,
+                tenantRole: ctxTenantRole,
+                orgRole: ctxOrgRole,
+                isSuperAdmin: ctxIsSuperAdmin,
+            });
+            return result;
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // ============================================
+    // Resources Handler
+    // ============================================
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        return {
+            resources: resourceDefinitions,
+            resourceTemplates: resourceTemplates,
+        };
+    });
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const { uri } = request.params;
+        const client = stdioClient || new DobbyClient({ apiUrl, apiKey: "", tenantId: "" });
+        try {
+            return await handleResourceRead(uri, client);
+        }
+        catch (error) {
+            throw new Error(`Failed to read resource ${uri}: ${error.message}`);
+        }
+    });
+    // ============================================
+    // Prompts Handler
+    // ============================================
+    server.setRequestHandler(ListPromptsRequestSchema, async () => {
+        return {
+            prompts: promptDefinitions,
+        };
+    });
+    server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        try {
+            return handlePromptGet(name, args || {});
+        }
+        catch (error) {
+            throw new Error(`Failed to get prompt ${name}: ${error.message}`);
+        }
+    });
+    return server;
+}
+//# sourceMappingURL=server.js.map