@bevel-software/platform-core-backend 0.34.0 → 0.35.0

package/src/modules/tool-manuals/__tests__/tool-manuals.mcp-oauth.test.ts

@@ -1,17 +1,19 @@
 import { describe, test, expect, beforeEach, afterEach, vi } from 'vitest';
-import { NodeFs } from '../../kb-fs/node-fs.js';
-import { KbPluginSource } from '../../plugins/discovery/kb-plugin-source.js';
+// The real disk, and the service wired over it, come from the composition-root
+// fixtures, as production wires them: this suite constructs no implementation
+// from its file, its own module's included.
+import { realDisk } from '../../../__tests__/real-disk.js';
+import { realToolManualService, type McpAuthDiscoveryPort } from '../../../__tests__/tool-manuals.js';
 
 /** The one disk, as production wires it: the service and its discovery read the same one. */
-const disk = new NodeFs();
+const disk = realDisk();
 import { mkdtemp, rm, mkdir, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
-import { ToolManualService, type McpAuthDiscoveryPort } from '../tool-manuals.service.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
-import type { WorkspaceService } from '../../workspace/workspace.service.js';
-import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { WorkspaceService } from '../../workspace/index.js';
+import type { IAccessControl } from '../../access/index.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 
 const KB_DIR = 'knowledge-base';
@@ -63,9 +65,10 @@ describe('ToolManualService — MCP OAuth auto-discovery decoration', () => {
   });
 
   function svcWith(discovery: McpAuthDiscoveryPort) {
-    const svc = new ToolManualService(workspaceService, allowAll, testKbContext({ kbDirName: KB_DIR }), disk, new KbPluginSource(disk, testKbContext({ kbDirName: KB_DIR })));
-    svc.setMcpAuthDiscovery(discovery);
-    return svc;
+    return realToolManualService(
+      { workspaceService, accessControl: allowAll, kb: testKbContext({ kbDirName: KB_DIR }), disk },
+      discovery,
+    );
   }
 
   test('a bare mcp tool whose server demands OAuth gains the synthetic sign-in var + header', async () => {
@@ -94,8 +97,10 @@ describe('ToolManualService — MCP OAuth auto-discovery decoration', () => {
 
     // The served call template carries the header the variable loader will fill.
     const templates = await svc.toManualCallTemplates('user@example.com');
-    const notionTemplate = templates.find((t) => t.name === 'notion') as any;
-    expect(notionTemplate.config.mcpServers.notion.headers).toEqual({
+    const notionTemplate = templates.find((t) => t.name === 'notion') as
+      | { config: { mcpServers: Record<string, { headers: Record<string, string> }> } }
+      | undefined;
+    expect(notionTemplate?.config.mcpServers.notion?.headers).toEqual({
       Authorization: 'Bearer ${MCP_OAUTH}',
     });
   });
@@ -298,4 +303,185 @@ describe('ToolManualService — MCP OAuth auto-discovery decoration', () => {
     // The declaration is carried verbatim, opt-out included.
     expect(hubspot.variables?.[0].oauth).toMatchObject({ clientId: 'owner-app', pkce: false });
   });
+
+  describe('liveDeclaration — what a sign-in start reads', () => {
+    const HUBSPOT_ENDPOINTS = {
+      authorizationUrl: 'https://auth.hubspot.example/authorize',
+      tokenUrl: 'https://auth.hubspot.example/token',
+    };
+
+    test('reads the file as it is now, not the catalog the last scan cached', async () => {
+      await writeDeclaredServer({ clientId: 'client-A', ...HUBSPOT_ENDPOINTS });
+      const svc = svcWith({ statusFor: vi.fn(async () => ({ status: 'open' as const })) });
+      // The catalog is scanned and cached under client A…
+      const cached = (await svc.listAccessible('user@example.com')).find((m) => m.name === 'hubspot')!;
+      expect(cached.variables?.[0].oauth?.clientId).toBe('client-A');
+
+      // …the file is edited, and nothing invalidates the catalog.
+      await writeDeclaredServer({ clientId: 'client-B', ...HUBSPOT_ENDPOINTS, scopes: ['crm.read'] });
+      const stale = (await svc.listAccessible('user@example.com')).find((m) => m.name === 'hubspot')!;
+      expect(stale.variables?.[0].oauth?.clientId).toBe('client-A');
+
+      const live = await svc.liveDeclaration('user@example.com', 'hubspot', 'HUBSPOT_TOKEN');
+      expect(live?.manual.name).toBe('hubspot');
+      expect(live?.variable?.oauth).toEqual({ clientId: 'client-B', ...HUBSPOT_ENDPOINTS, scopes: ['crm.read'] });
+    });
+
+    test('a .tool file is read afresh the same way', async () => {
+      const toolsDir = join(root, wsId, KB_DIR, 'Plugins');
+      const write = (clientId: string) =>
+        writeFile(
+          join(toolsDir, 'crm.tool'),
+          JSON.stringify({
+            name: 'crm',
+            type: 'http',
+            url: 'https://api.crm.example/openapi.json',
+            variables: [{ name: 'SIGNIN', scope: 'user', oauth: { clientId, ...HUBSPOT_ENDPOINTS } }],
+          }),
+        );
+      await write('client-A');
+      const svc = svcWith({ statusFor: vi.fn(async () => ({ status: 'open' as const })) });
+      await svc.listAccessible('user@example.com');
+      await write('client-B');
+      const live = await svc.liveDeclaration('user@example.com', 'crm', 'SIGNIN');
+      expect(live?.variable?.oauth?.clientId).toBe('client-B');
+    });
+
+    test('completes a client-id-only declaration from the server metadata, or carries the discovery reason', async () => {
+      await writeDeclaredServer({ clientId: 'owner-app' });
+      const statusFor = vi.fn(async () => ({ status: 'open' as const }));
+      const providerForDeclaredClient = vi.fn(async () => ({
+        status: 'oauth' as const,
+        provider: { ...HUBSPOT_ENDPOINTS, clientId: 'owner-app', pkce: true, resource: 'https://mcp.hubspot.example/mcp' },
+      }));
+      const live = await svcWith({ statusFor, providerForDeclaredClient }).liveDeclaration(
+        'user@example.com',
+        'hubspot',
+        'HUBSPOT_TOKEN',
+      );
+      expect(live?.variable?.oauth).toEqual({
+        clientId: 'owner-app',
+        ...HUBSPOT_ENDPOINTS,
+        resource: 'https://mcp.hubspot.example/mcp',
+      });
+      // Never a zero-config probe or registration for a declared sign-in.
+      expect(statusFor).not.toHaveBeenCalled();
+
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const stuck = await svcWith({
+        statusFor,
+        providerForDeclaredClient: async () => ({ status: 'unsupported' as const, reason: 'no authorization-server metadata' }),
+      }).liveDeclaration('user@example.com', 'hubspot', 'HUBSPOT_TOKEN');
+      expect(stuck?.variable?.oauth).toEqual({ clientId: 'owner-app' });
+      expect(stuck?.manual.setup).toEqual({ kind: 'oauth-manual', reason: 'no authorization-server metadata' });
+      warn.mockRestore();
+    });
+
+    test('a .tool whose sign-in endpoint fails validation answers the parser’s reason, even while the catalog holds the valid version', async () => {
+      const toolsDir = join(root, wsId, KB_DIR, 'Plugins');
+      const write = (tokenUrl: string) =>
+        writeFile(
+          join(toolsDir, 'crm.tool'),
+          JSON.stringify({
+            name: 'crm',
+            type: 'http',
+            url: 'https://api.crm.example/openapi.json',
+            variables: [{ name: 'SIGNIN', scope: 'user', oauth: { clientId: 'c', authorizationUrl: HUBSPOT_ENDPOINTS.authorizationUrl, tokenUrl } }],
+          }),
+        );
+      await write(HUBSPOT_ENDPOINTS.tokenUrl);
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const svc = svcWith({ statusFor: vi.fn(async () => ({ status: 'open' as const })) });
+      expect((await svc.listAccessible('user@example.com')).some((m) => m.name === 'crm')).toBe(true);
+
+      await write('http://127.0.0.1/token');
+      await expect(svc.liveDeclaration('user@example.com', 'crm', 'SIGNIN')).resolves.toEqual({
+        refused: '`variables[0].oauth.tokenUrl` must use https',
+      });
+      await write('https://10.0.0.5/token');
+      await expect(svc.liveDeclaration('user@example.com', 'crm', 'SIGNIN')).resolves.toEqual({
+        refused: '`variables[0].oauth.tokenUrl` host is not allowed',
+      });
+      warn.mockRestore();
+    });
+
+    test('a plugin.json sign-in whose endpoint fails validation answers the reason too, not only a log line', async () => {
+      await writeDeclaredServer({ clientId: 'owner-app', ...HUBSPOT_ENDPOINTS, tokenUrl: 'http://127.0.0.1/token' });
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const svc = svcWith({ statusFor: vi.fn(async () => ({ status: 'open' as const })) });
+      const live = await svc.liveDeclaration('user@example.com', 'hubspot', 'HUBSPOT_TOKEN');
+      expect(live?.refused).toContain('`variables[0].oauth.tokenUrl` must use https');
+      // Located by position, never by the name the entry declared (the .tool parser's rule).
+      expect(live?.refused).not.toContain('HUBSPOT_TOKEN');
+      // The catalog's public listing is unchanged by this: the server is still left out.
+      const catalog = await svc.listAccessibleCatalog('user@example.com');
+      expect(catalog.tools.some((m) => m.name === 'hubspot')).toBe(false);
+      warn.mockRestore();
+    });
+
+    test('a refusal is read-gated like the manual it would have been', async () => {
+      await writeDeclaredServer({ clientId: 'owner-app', ...HUBSPOT_ENDPOINTS, tokenUrl: 'http://127.0.0.1/token' });
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      const denyAll = {
+        canRead: async () => false,
+        canReadBatch: async (_w: string, _e: string, paths: string[]) => new Map(paths.map((p) => [p, false])),
+      } as unknown as IAccessControl;
+      const locked = realToolManualService({
+        workspaceService,
+        accessControl: denyAll,
+        kb: testKbContext({ kbDirName: KB_DIR }),
+        disk,
+      });
+      await expect(locked.liveDeclaration('user@example.com', 'hubspot', 'HUBSPOT_TOKEN')).resolves.toBeNull();
+      warn.mockRestore();
+    });
+
+    test('a workspace that cannot be opened is an error for a sign-in start, where the catalog answers empty', async () => {
+      await writeDeclaredServer({ clientId: 'owner-app', ...HUBSPOT_ENDPOINTS });
+      const down = {
+        getOrCreateForBranch: async () => {
+          throw new Error('workspace unavailable');
+        },
+      } as unknown as WorkspaceService;
+      const allowAll = {
+        canRead: async () => true,
+        canReadBatch: async (_w: string, _e: string, paths: string[]) => new Map(paths.map((p) => [p, true])),
+      } as unknown as IAccessControl;
+      const svc = realToolManualService({
+        workspaceService: down,
+        accessControl: allowAll,
+        kb: testKbContext({ kbDirName: KB_DIR }),
+        disk,
+      });
+      // The catalog degrades to "nothing released" and tries again next scan…
+      await expect(svc.listAccessible('user@example.com')).resolves.toEqual([]);
+      // …but a sign-in start must not read that as "no sign-in declared".
+      await expect(svc.liveDeclaration('user@example.com', 'hubspot', 'HUBSPOT_TOKEN')).rejects.toThrow(
+        'workspace unavailable',
+      );
+    });
+
+    test('answers no variable when the file declares none of that name, and null for an unreadable manual', async () => {
+      await writeDeclaredServer({ clientId: 'owner-app', ...HUBSPOT_ENDPOINTS });
+      const statusFor = vi.fn(async () => ({ status: 'oauth' as const, provider: OAUTH_PROVIDER }));
+      const svc = svcWith({ statusFor });
+      // The zero-config variable is synthesised by the catalog, not declared in any file.
+      const bare = await svc.liveDeclaration('user@example.com', 'notion', 'MCP_OAUTH');
+      expect(bare?.manual.name).toBe('notion');
+      expect(bare?.variable).toBeUndefined();
+      expect(statusFor).not.toHaveBeenCalled();
+
+      const denyAll = {
+        canRead: async () => false,
+        canReadBatch: async (_w: string, _e: string, paths: string[]) => new Map(paths.map((p) => [p, false])),
+      } as unknown as IAccessControl;
+      const locked = realToolManualService({
+        workspaceService,
+        accessControl: denyAll,
+        kb: testKbContext({ kbDirName: KB_DIR }),
+        disk,
+      });
+      await expect(locked.liveDeclaration('user@example.com', 'hubspot', 'HUBSPOT_TOKEN')).resolves.toBeNull();
+    });
+  });
 });

package/src/modules/tool-manuals/__tests__/tool-manuals.tools.test.ts

@@ -1,11 +1,13 @@
 import type { Server as HttpServer } from 'node:http';
 import express from 'express';
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import { ToolRegistry } from '../../tool-registry/tool-registry.js';
-import { InternalTokenService } from '../../tool-auth/internal-token.service.js';
-import { createToolAuthMiddleware } from '../../tool-auth/tool-auth.middleware.js';
-import { createToolContextResolver } from '../../tool-helpers/tool-context.js';
-import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
+import { ToolRegistry } from '../../tool-registry/index.js';
+import {
+  InternalTokenService,
+  createToolAuthMiddleware,
+  createToolContextResolver,
+  createToolHandlerFactory,
+} from '../../../__tests__/tool-wiring.js';
 import { registerToolManualsTools } from '../tool-manuals.tools.js';
 import type { IToolManualService } from '../tool-manuals.contract.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
@@ -337,3 +339,92 @@ describe('list_tool_setup — a declaration that lives on a draft says so', () =
     expect(toolManualService.listDeclaredOnlyOnBranch).not.toHaveBeenCalled();
   });
 });
+
+describe('list_tool_setup — a tool that needs the caller’s own value says so', () => {
+  const TICKETS = {
+    slug: 'ticketdesk',
+    name: 'ticketdesk',
+    path: 'Plugins/Support/ticketdesk.tool',
+    type: 'http' as const,
+    variables: [{ name: 'TICKETDESK_TOKEN', scope: 'user' as const, label: null }],
+  };
+
+  it('tells a caller without their own value where to set it, and to reconnect', async () => {
+    const base = await start();
+    vi.mocked(toolManualService.listAccessibleCatalog).mockResolvedValueOnce({ tools: [TICKETS], invalid: [] } as never);
+    // Bob has configured nothing (see `statusFor`).
+    const body = (await (await callSetup(base, 'bevel_bob')).json()) as { note?: string };
+    expect(body.note).toContain('`ticketdesk` needs your own value or sign-in');
+    expect(body.note).toContain('Connect page, never in the chat');
+    expect(body.note).toContain('reconnect your assistant');
+  });
+
+  it('says nothing to a caller who has set theirs', async () => {
+    const base = await start();
+    vi.mocked(toolManualService.listAccessibleCatalog).mockResolvedValueOnce({ tools: [TICKETS], invalid: [] } as never);
+    const body = (await (await callSetup(base, 'bevel_alice')).json()) as { note?: string };
+    expect(body.note).toBeUndefined();
+  });
+
+  const SIGN_IN = {
+    ...TICKETS,
+    variables: [{ name: 'TICKETDESK_OAUTH', scope: 'user' as const, label: null, oauth: { scopes: ['tickets'] } }],
+  };
+
+  /** The owner's side of a sign-in: a provider row of the OAuth kind. */
+  const ownerSignedUp = { adminConfigured: true, adminKind: 'oauth' as const };
+
+  it('tells a caller to sign in once the owner has set the sign-in up', async () => {
+    const base = await start();
+    vi.mocked(toolManualService.listAccessibleCatalog).mockResolvedValueOnce({ tools: [SIGN_IN], invalid: [] } as never);
+    statusFor.mockImplementationOnce(async (_userId: string, keys: string[]) =>
+      keys.map((key) => ({ key, ...ownerSignedUp, userConfigured: false })),
+    );
+    const body = (await (await callSetup(base, 'bevel_bob')).json()) as { note?: string };
+    expect(body.note).toContain('`ticketdesk` needs your own value or sign-in');
+  });
+
+  it('names a tool the proxy hides for a stale credential: the wrong kind, or a sign-in short of a scope', async () => {
+    const base = await start();
+    // A row left from when the variable was a plain key.
+    vi.mocked(toolManualService.listAccessibleCatalog).mockResolvedValueOnce({ tools: [SIGN_IN], invalid: [] } as never);
+    statusFor.mockImplementationOnce(async (_userId: string, keys: string[]) =>
+      keys.map((key) => ({ key, ...ownerSignedUp, userConfigured: true, userKind: 'static' as const })),
+    );
+    expect(((await (await callSetup(base, 'bevel_bob')).json()) as { note?: string }).note).toContain('`ticketdesk` needs your own value or sign-in');
+    // Signed in, but before the tool asked for `tickets`.
+    vi.mocked(toolManualService.listAccessibleCatalog).mockResolvedValueOnce({ tools: [SIGN_IN], invalid: [] } as never);
+    statusFor.mockImplementationOnce(async (_userId: string, keys: string[]) =>
+      keys.map((key) => ({ key, ...ownerSignedUp, userConfigured: true, userKind: 'oauth' as const, userAuthorized: true, grantedScopes: 'profile' })),
+    );
+    expect(((await (await callSetup(base, 'bevel_bob')).json()) as { note?: string }).note).toContain('`ticketdesk` needs your own value or sign-in');
+    // Signed in with the scope: nothing to say.
+    vi.mocked(toolManualService.listAccessibleCatalog).mockResolvedValueOnce({ tools: [SIGN_IN], invalid: [] } as never);
+    statusFor.mockImplementationOnce(async (_userId: string, keys: string[]) =>
+      keys.map((key) => ({ key, ...ownerSignedUp, userConfigured: true, userKind: 'oauth' as const, userAuthorized: true, grantedScopes: 'tickets' })),
+    );
+    expect(((await (await callSetup(base, 'bevel_bob')).json()) as { note?: string }).note).toBeUndefined();
+  });
+
+  it('does not send a caller to sign in before the owner has set the sign-in up', async () => {
+    const base = await start();
+    vi.mocked(toolManualService.listAccessibleCatalog).mockResolvedValueOnce({ tools: [SIGN_IN], invalid: [] } as never);
+    statusFor.mockImplementationOnce(async (_userId: string, keys: string[]) =>
+      keys.map((key) => ({ key, adminConfigured: false, userConfigured: false })),
+    );
+    const body = (await (await callSetup(base, 'bevel_bob')).json()) as { note?: string };
+    expect(body.note).toBeUndefined();
+  });
+
+  it('does not send a caller to sign in on a shared key left from when the variable was static', async () => {
+    const base = await start();
+    // The owner turned a plain key into a sign-in; the old shared row is still
+    // there, so `adminConfigured` is true, but it is no provider to sign in to.
+    vi.mocked(toolManualService.listAccessibleCatalog).mockResolvedValueOnce({ tools: [SIGN_IN], invalid: [] } as never);
+    statusFor.mockImplementationOnce(async (_userId: string, keys: string[]) =>
+      keys.map((key) => ({ key, adminConfigured: true, adminKind: 'static' as const, userConfigured: false })),
+    );
+    const body = (await (await callSetup(base, 'bevel_bob')).json()) as { note?: string };
+    expect(body.note).toBeUndefined();
+  });
+});

package/src/modules/tool-manuals/mcp-json-discovery.ts

@@ -90,39 +90,62 @@ const SERVER_NAME_RE = /^[a-z0-9][a-z0-9_-]*$/;
  * silently vanishes from the catalog the moment its edit lands.
  */
 export function validatedVariables(raw: unknown): ToolVariable[] | null {
-  if (raw === undefined) return [];
-  if (!Array.isArray(raw)) return null;
+  const verdict = judgeVariables(raw);
+  return verdict.ok ? verdict.variables : null;
+}
+
+/**
+ * {@link validatedVariables} with the reason a declaration was refused. The
+ * reason locates the entry by its position (`` `variables[2] ``), never by
+ * the name it declared or any other value the author wrote — the `.tool`
+ * parser's discipline (`describeManualFault`): passing `[A-Za-z0-9_]+` makes
+ * a string a legal identifier, not one this process may repeat. The reason
+ * reaches logs and, for a sign-in start on the server, the person signing in.
+ */
+function judgeVariables(
+  raw: unknown,
+): { ok: true; variables: ToolVariable[] } | { ok: false; reason: string } {
+  const no = (reason: string) => ({ ok: false as const, reason });
+  if (raw === undefined) return { ok: true, variables: [] };
+  if (!Array.isArray(raw)) return no('`variables` must be a list');
   const out: ToolVariable[] = [];
   const declared = new Set<string>();
-  for (const entry of raw) {
-    if (!isRecord(entry)) return null;
-    if (typeof entry.name !== 'string' || !/^[A-Za-z0-9_]+$/.test(entry.name)) return null;
+  for (const [i, entry] of raw.entries()) {
+    const at = `\`variables[${i}]`;
+    if (!isRecord(entry)) return no(`${at}\` must be an object`);
+    if (typeof entry.name !== 'string' || !/^[A-Za-z0-9_]+$/.test(entry.name)) {
+      return no(`${at}.name\` must match [A-Za-z0-9_]+`);
+    }
     // The `.tool` parser's declaration rules, at this file's grain: a
     // platform-seeded name may not be re-declared (it would shadow the
     // seeding), and a duplicate would make later scope resolution depend on
     // declaration order.
-    if (RESERVED_VARIABLE_NAMES.includes(entry.name) || declared.has(entry.name)) return null;
+    if (RESERVED_VARIABLE_NAMES.includes(entry.name)) return no(`${at}.name\` is reserved for platform seeding`);
+    if (declared.has(entry.name)) return no(`${at}.name\` duplicates an earlier entry's`);
     declared.add(entry.name);
     const scope = entry.scope ?? 'admin';
-    if (scope !== 'admin' && scope !== 'user') return null;
+    if (scope !== 'admin' && scope !== 'user') return no(`${at}.scope\` must be \`admin\` or \`user\``);
     let oauth: ToolVariable['oauth'];
     if (entry.oauth !== undefined) {
       // OAuth is inherently per-caller (same rule the `.tool` parser
       // enforces): an admin-shared OAuth token would leak one user's token
       // to all callers.
-      if (!isRecord(entry.oauth) || scope !== 'user') return null;
+      if (!isRecord(entry.oauth)) return no(`${at}.oauth\` must be an object`);
+      if (scope !== 'user') return no(`${at}\` has \`oauth\`, so its \`scope\` must be \`user\``);
       const o = entry.oauth;
       // Confidential material never loads from a file, on either declaration
       // surface: the `.tool` parser throws on these keys, and silently
       // dropping one here would leave a plugin.json carrying a secret that
       // "worked" — the file is portable package data, readable by every
       // client that loads the plugin.
-      if (o.clientSecret !== undefined || o.client_secret !== undefined || o.secret !== undefined) return null;
+      if (o.clientSecret !== undefined || o.client_secret !== undefined || o.secret !== undefined) {
+        return no(`${at}.oauth\` may not carry a client secret — it is set through the protected client-secret route`);
+      }
       // `clientId` is trimmed and must be non-empty, exactly as the `.tool`
       // parser requires: a whitespace-only value would pass discovery and
       // then fail the owner's client-secret setup with "clientId is
       // required" — an error at the wrong surface, long after the save.
-      if (typeof o.clientId !== 'string' || !o.clientId.trim()) return null;
+      if (typeof o.clientId !== 'string' || !o.clientId.trim()) return no(`${at}.oauth.clientId\` is required`);
       // The endpoints are OPTIONAL here, unlike in a `.tool`: an MCP server
       // publishes its authorization-server metadata, so a declaration that
       // names only the client id is completed at scan time. Both or neither
@@ -137,33 +160,38 @@ export function validatedVariables(raw: unknown): ToolVariable[] | null {
       const authorizationUrl = optionalUrl(o.authorizationUrl);
       const tokenUrl = optionalUrl(o.tokenUrl);
       const resource = optionalUrl(o.resource);
-      if (authorizationUrl === null || tokenUrl === null || resource === null) return null;
-      if ((authorizationUrl === undefined) !== (tokenUrl === undefined)) return null;
+      if (authorizationUrl === null || tokenUrl === null || resource === null) {
+        return no(`${at}.oauth\` URLs must be strings`);
+      }
+      if ((authorizationUrl === undefined) !== (tokenUrl === undefined)) {
+        return no(`${at}.oauth\` must declare both \`authorizationUrl\` and \`tokenUrl\`, or neither`);
+      }
       // The same https + SSRF gate the `.tool` parser runs on these URLs: a
       // sign-in or token exchange aimed at an internal host is a declaration
       // this surface must refuse exactly like the other one does. `resource`
       // is never fetched, but it names the remote server — same bar.
       try {
         if (authorizationUrl !== undefined) {
-          assertSafeFetchUrl(authorizationUrl, { requireHttps: true, label: `${entry.name} oauth.authorizationUrl` });
-          assertSafeFetchUrl(tokenUrl!, { requireHttps: true, label: `${entry.name} oauth.tokenUrl` });
+          assertSafeFetchUrl(authorizationUrl, { requireHttps: true, label: `${at}.oauth.authorizationUrl\`` });
+          assertSafeFetchUrl(tokenUrl!, { requireHttps: true, label: `${at}.oauth.tokenUrl\`` });
         }
         if (resource !== undefined) {
-          assertSafeFetchUrl(resource, { requireHttps: true, label: `${entry.name} oauth.resource` });
+          assertSafeFetchUrl(resource, { requireHttps: true, label: `${at}.oauth.resource\`` });
         }
-      } catch {
-        return null;
+      } catch (err) {
+        // `assertSafeFetchUrl` names the field and the rule, never the URL.
+        return no(err instanceof Error ? err.message : `${at}.oauth\` has an invalid URL`);
       }
       // Forwarded verbatim as query params later — a non-string value here is
       // a malformed declaration, not something to coerce.
       if (o.authParams !== undefined) {
         if (!isRecord(o.authParams) || !Object.values(o.authParams).every((v) => typeof v === 'string')) {
-          return null;
+          return no(`${at}.oauth.authParams\` must be an object of string values`);
         }
       }
       // PKCE is on unless the declaration says `false`; anything else there is
       // a malformed flag, not a preference.
-      if (o.pkce !== undefined && typeof o.pkce !== 'boolean') return null;
+      if (o.pkce !== undefined && typeof o.pkce !== 'boolean') return no(`${at}.oauth.pkce\` must be a boolean`);
       oauth = {
         ...(authorizationUrl !== undefined ? { authorizationUrl, tokenUrl: tokenUrl! } : {}),
         clientId: o.clientId.trim(),
@@ -182,7 +210,7 @@ export function validatedVariables(raw: unknown): ToolVariable[] | null {
       ...(oauth ? { oauth } : {}),
     });
   }
-  return out;
+  return { ok: true, variables: out };
 }
 
 /**
@@ -318,6 +346,12 @@ export function descriptorsFromMcpJson(
   mcpJsonText: string,
   pluginJsonText: string | null,
   layout: KbLayout,
+  /**
+   * Told of every server this file declares and the parse refuses, with the
+   * reason the log line gives. The scan keeps them so a sign-in started on a
+   * refused server answers why, instead of finding nothing by that name.
+   */
+  onRefused?: (server: string, reason: string, path: string) => void,
 ): ToolManualDescriptor[] {
   const { pluginsDir } = layout;
   let mcp: unknown;
@@ -347,10 +381,14 @@ export function descriptorsFromMcpJson(
   const mcpJsonPath = `${pluginsDir}/${pluginFolder}/${PLUGIN_MCP_FILE}`;
 
   const out: ToolManualDescriptor[] = [];
+  const skip = (name: string, reason: string) => {
+    log.warn(`skipping mcp server "${name}" in ${mcpJsonPath}: ${reason}`);
+    onRefused?.(name, reason, mcpJsonPath);
+  };
   for (const [name, rawEntry] of Object.entries(mcp.mcpServers)) {
     const verdict = judgeMcpServerEntry(name, rawEntry);
     if (!verdict.ok) {
-      log.warn(`skipping mcp server "${name}" in ${mcpJsonPath}: ${verdict.reason}.`);
+      skip(name, `${verdict.reason}.`);
       continue;
     }
     // Narrowed by the verdict: an entry that passed is a record.
@@ -365,22 +403,23 @@ export function descriptorsFromMcpJson(
     // into outbound requests exactly the same way.
     const reserved = referencesReservedVariable({ raw, ext });
     if (reserved !== null) {
-      log.warn(
-        `skipping mcp server "${name}" in ${mcpJsonPath}: its declaration (mcp.json ` +
-          `entry or plugin.json extension) references the reserved variable "${reserved}" — API_URL and ` +
-          'CONNECTION_KEY are platform-seeded and may not appear in server declarations.',
+      skip(
+        name,
+        `its declaration (mcp.json entry or plugin.json extension) references the reserved variable "${reserved}" — ` +
+          'API_URL and CONNECTION_KEY are platform-seeded and may not appear in server declarations.',
       );
       continue;
     }
-    const variables = validatedVariables(ext.variables);
-    if (variables === null) {
-      log.warn(
-        `skipping mcp server "${name}" in ${mcpJsonPath}: its plugin.json \`variables\` ` +
-          'declaration is malformed — a dropped declaration would silently re-scope a credential, so ' +
-          'the server stays offline until the manifest is fixed.',
+    const judged = judgeVariables(ext.variables);
+    if (!judged.ok) {
+      skip(
+        name,
+        `its plugin.json \`variables\` declaration is malformed (${judged.reason}) — a dropped declaration ` +
+          'would silently re-scope a credential, so the server stays offline until the manifest is fixed.',
       );
       continue;
     }
+    const variables = judged.variables;
     const shared = {
       slug: name,
       name,
@@ -408,9 +447,9 @@ export function descriptorsFromMcpJson(
       try {
         assertSafeFetchUrl(url, { label: `mcp server "${name}" url` });
       } catch (err) {
-        log.warn(
-          `skipping mcp server "${name}" in ${mcpJsonPath}: ` +
-            `${err instanceof Error ? err.message : String(err)} (declare it \`local: true\` if it is deliberately private).`,
+        skip(
+          name,
+          `${err instanceof Error ? err.message : String(err)} (declare it \`local: true\` if it is deliberately private).`,
         );
         continue;
       }

package/src/modules/tool-manuals/tool-manuals.contract.ts

@@ -366,6 +366,11 @@ export interface ToolManualDetail extends Omit<ToolManualSummary, 'description'>
  */
 export type ConnectorScope = (definitionPath: string) => boolean;
 
+/** A manual as its file reads now — see {@link IToolManualService.liveDeclaration}. */
+export type LiveDeclaration =
+  | { manual: ToolManualSummary; variable?: ToolVariable; refused?: undefined }
+  | { refused: string; manual?: undefined; variable?: undefined };
+
 export interface IToolManualService {
   /** The `.tool` manuals the user can read, as summaries. */
   listAccessible(userEmail: string): Promise<ToolManualSummary[]>;
@@ -395,6 +400,23 @@ export interface IToolManualService {
    * confirm that a tool the caller can't see exists).
    */
   getDetail(userEmail: string, slug: string): Promise<ToolManualDetail | null>;
+  /**
+   * One manual's declaration as its file reads on the default branch NOW, for a
+   * sign-in about to start: the files are parsed afresh, never served from the
+   * catalog's cached scan, so an edit made seconds ago is already what this
+   * answers. A sign-in variable that names only its `clientId` is completed from
+   * the server's OAuth metadata by the same walk the catalog completes it with;
+   * when that fails, the endpoints stay absent and `manual.setup.reason` says why.
+   *
+   * `refused` when the file declaring this slug is one the parse refuses as it
+   * reads now (an endpoint failing the https/SSRF check, say): the parser's
+   * reason, so the sign-in can say why instead of finding nothing. `null` when
+   * no readable manual has this slug (fail-closed, like {@link getDetail});
+   * `variable` absent when the file declares no variable of that name. Nothing
+   * the platform synthesises from discovery (the zero-config sign-in variable)
+   * is in the answer: it is not in any file.
+   */
+  liveDeclaration(userEmail: string, slug: string, varName: string): Promise<LiveDeclaration | null>;
 
   /**
    * Wire where a hidden tool's schema finding comes from (the MCP proxy, which