@bevel-software/platform-core-backend 0.31.0 → 0.33.0

package/src/modules/mcp/__tests__/read-only-hint.e2e.test.ts

@@ -0,0 +1,213 @@
+import type { Server as HttpServer } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import express, { type RequestHandler } from 'express';
+import { afterEach, describe, expect, it } from 'vitest';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { createMcpRoutes } from '../mcp.routes.js';
+import { McpService } from '../mcp.service.js';
+import { SpillStore } from '../../workspace/index.js';
+import { TOOL_READ_ONLY_SETTING, ToolReadOnlyHints, ToolRegistry, createManualRoutes } from '../../tool-registry/index.js';
+import { toolDef } from '../../tool-helpers/index.js';
+import { createCatalogRevisionRoutes } from '../../../core/catalog-revision.js';
+import { startFakeDownstreamMcpServer, type FakeDownstreamMcpServer } from './fake-downstream-mcp-server.js';
+
+/**
+ * The read-only hint as the HOSTED MCP endpoint lists it, over the real
+ * Streamable-HTTP transport: the real `McpService` discovering the real agent
+ * manual over loopback, with the real hints applied to it. What a client such
+ * as Claude Cowork reads to decide whether a call needs approval.
+ */
+
+const KEY = 'bevel_key_interactive';
+const fakeAuth: RequestHandler = (req, res, next) => {
+  if ((req.headers.authorization ?? '') !== `Bearer ${KEY}`) {
+    res.status(401).json({ error: 'unauthorized' });
+    return;
+  }
+  // An interactive caller (no connection-key id): the full listing, no credential filter.
+  req.userId = 'user-A';
+  next();
+};
+const pass: RequestHandler = (_req, _res, next) => next();
+
+const stops: Array<() => Promise<void>> = [];
+afterEach(async () => {
+  for (const stop of stops.splice(0).reverse()) await stop().catch(() => {});
+});
+
+async function startPlatform(opts: { downstream?: FakeDownstreamMcpServer; catalogRevision?: boolean } = {}) {
+  const registry = new ToolRegistry();
+  registry.registerExternalTool(
+    toolDef({ name: 'read_file', description: 'Read a file.', path: '/api/agent/tools/read_file', inputs: { type: 'object', properties: {} } }),
+  );
+  registry.registerExternalTool(
+    toolDef({
+      name: 'write_file',
+      description: 'Write a file.',
+      path: '/api/agent/tools/write_file',
+      inputs: { type: 'object', properties: {} },
+      tags: ['write'],
+    }),
+  );
+  // One stored row, as the deployment-settings table would hold it.
+  const row = { value: '' };
+  const hints = new ToolReadOnlyHints(registry, {
+    reload: async (key) => (key === TOOL_READ_ONLY_SETTING ? row.value : ''),
+    recordIfAbsent: async (_key, value) => {
+      if (row.value) return false;
+      row.value = value;
+      return true;
+    },
+    swapIfValue: async (_key, expected, next) => {
+      if (row.value !== expected) return false;
+      row.value = next ?? '';
+      return true;
+    },
+  });
+
+  const app = express();
+  app.use(express.json());
+  app.get('/api/agent/all-tools', (_req, res) => {
+    res.json({
+      manuals: [
+        {
+          name: 'KNOWLEDGE_BASE',
+          call_template_type: 'http',
+          http_method: 'GET',
+          url: '${API_URL}/api/agent/utcp',
+          content_type: 'application/json',
+          headers: { Authorization: 'Bearer ${CONNECTION_KEY}' },
+        },
+        // A plugin's MCP server: a tool from the knowledge base, not the platform's.
+        ...(opts.downstream
+          ? [{ name: 'notion', call_template_type: 'mcp', config: { mcpServers: { srv: { transport: 'http', url: opts.downstream.url } } } }]
+          : []),
+      ],
+    });
+  });
+  const httpServer = await new Promise<HttpServer>((resolve) => {
+    const s = app.listen(0, '127.0.0.1', () => resolve(s));
+  });
+  const baseUrl = `http://127.0.0.1:${(httpServer.address() as AddressInfo).port}`;
+  const service = new McpService({
+    loopbackBaseUrl: baseUrl,
+    manualName: 'KNOWLEDGE_BASE',
+    spillStore: new SpillStore(join(tmpdir(), 'bevel-test-spills')),
+    publicFrontendUrl: 'http://localhost:5173',
+    readOnlyOverrides: () => hints.overrides(),
+  });
+  const stub = {} as never;
+  app.use('/api', createMcpRoutes(service, stub, fakeAuth, fakeAuth, stub, stub, stub, ''));
+  app.use('/api', createManualRoutes(registry, pass, undefined, hints));
+  // The route the endpoint keys its cached tool surface by. Served, a listing
+  // reuses the surface it built until the revision moves; absent (404), every
+  // request builds its own. An override does not move it: the hints are
+  // joined on per listing, so the cached surface never holds one.
+  if (opts.catalogRevision) {
+    const asCaller: RequestHandler = (req, _res, next) => {
+      req.toolAuth = { userId: 'user-A' } as never;
+      next();
+    };
+    app.use(
+      '/api',
+      createCatalogRevisionRoutes({
+        toolManuals: { catalogFingerprints: async () => [] },
+        skills: { listSkills: async () => [] },
+        manualAuth: asCaller,
+        resolveUserEmail: async () => 'a@example.test',
+      }),
+    );
+  }
+  stops.push(async () => {
+    service.onSecretsChanged(null);
+    httpServer.closeAllConnections();
+    await new Promise<void>((r) => httpServer.close(() => r()));
+  });
+  return { baseUrl, hints };
+}
+
+async function connect(baseUrl: string): Promise<Client> {
+  const transport = new StreamableHTTPClientTransport(new URL(`${baseUrl}/api/mcp`), {
+    requestInit: { headers: { Authorization: `Bearer ${KEY}` } },
+  });
+  const client = new Client({ name: 'hint-client', version: '0.0.0' }, { capabilities: {} });
+  await client.connect(transport);
+  stops.push(() => client.close());
+  return client;
+}
+
+const annotationsOf = async (client: Client) =>
+  Object.fromEntries((await client.listTools()).tools.map((t) => [t.name, t.annotations]));
+
+describe('the hosted MCP endpoint lists the read-only hint', () => {
+  it('on every platform tool and every meta-tool, and no other annotation', async () => {
+    const { baseUrl } = await startPlatform();
+    expect(await annotationsOf(await connect(baseUrl))).toEqual({
+      list_tools: { readOnlyHint: true },
+      tools_info: { readOnlyHint: true },
+      call_tool_chain: { readOnlyHint: false },
+      read_file: { readOnlyHint: true },
+      write_file: { readOnlyHint: false },
+    });
+  });
+
+  it("lists an admin's change on the client's NEXT tools/list, with no reconnect, and a reset undoes it", async () => {
+    const { baseUrl, hints } = await startPlatform();
+    const client = await connect(baseUrl);
+    expect((await annotationsOf(client)).read_file).toEqual({ readOnlyHint: true });
+
+    await hints.set('read_file', false, '00000000-0000-4000-8000-00000000000a');
+    await hints.set('write_file', true, '00000000-0000-4000-8000-00000000000a');
+    await hints.set('call_tool_chain', true, '00000000-0000-4000-8000-00000000000a');
+    let listed = await annotationsOf(client);
+    expect(listed.read_file).toEqual({ readOnlyHint: false });
+    expect(listed.write_file).toEqual({ readOnlyHint: true });
+    expect(listed.call_tool_chain).toEqual({ readOnlyHint: true });
+
+    for (const name of ['read_file', 'write_file', 'call_tool_chain']) await hints.set(name, null, '00000000-0000-4000-8000-00000000000a');
+    listed = await annotationsOf(client);
+    expect(listed.read_file).toEqual({ readOnlyHint: true });
+    expect(listed.write_file).toEqual({ readOnlyHint: false });
+    expect(listed.call_tool_chain).toEqual({ readOnlyHint: false });
+  });
+
+  it("lists an admin's change and its reset on the next tools/list when the tool surface is cached", async () => {
+    const { baseUrl, hints } = await startPlatform({ catalogRevision: true });
+    const client = await connect(baseUrl);
+    expect((await annotationsOf(client)).read_file).toEqual({ readOnlyHint: true });
+
+    await hints.set('read_file', false, '00000000-0000-4000-8000-00000000000a');
+    await hints.set('write_file', true, '00000000-0000-4000-8000-00000000000a');
+    let listed = await annotationsOf(client);
+    expect(listed.read_file).toEqual({ readOnlyHint: false });
+    expect(listed.write_file).toEqual({ readOnlyHint: true });
+
+    for (const name of ['read_file', 'write_file']) await hints.set(name, null, '00000000-0000-4000-8000-00000000000a');
+    listed = await annotationsOf(client);
+    expect(listed.read_file).toEqual({ readOnlyHint: true });
+    expect(listed.write_file).toEqual({ readOnlyHint: false });
+  });
+
+  it('does not keep an override in the cached surface: one set before the surface is built is undone by its reset', async () => {
+    const { baseUrl, hints } = await startPlatform({ catalogRevision: true });
+    await hints.set('read_file', false, '00000000-0000-4000-8000-00000000000a');
+    const client = await connect(baseUrl);
+    expect((await annotationsOf(client)).read_file).toEqual({ readOnlyHint: false });
+
+    await hints.set('read_file', null, '00000000-0000-4000-8000-00000000000a');
+    expect((await annotationsOf(client)).read_file).toEqual({ readOnlyHint: true });
+  });
+
+  it('leaves a tool from a plugin MCP server unannotated, as before', async () => {
+    const downstream = await startFakeDownstreamMcpServer();
+    stops.push(() => downstream.stop());
+    const { baseUrl } = await startPlatform({ downstream });
+    const tools = (await (await connect(baseUrl)).listTools()).tools;
+    const proxied = tools.find((t) => t.name.endsWith('echo'));
+    expect(proxied).toBeDefined();
+    expect(proxied).not.toHaveProperty('annotations');
+  });
+});

package/src/modules/mcp/index.ts

@@ -0,0 +1,7 @@
+/**
+ * What the mcp module offers the other modules. A consumer outside the
+ * module imports from here, never from the files: they are the module's own
+ * layout and free to move. Export what another module needs; nothing more.
+ */
+export { signAuthRequest } from './oauth/oauth-state.js';
+export type { McpAuthRequestState } from './oauth/oauth-state.js';

package/src/modules/mcp/mcp-auth.middleware.ts

@@ -3,14 +3,13 @@ import { logger } from '../../shared/logging.js';
 
 const log = logger('mcp-auth');
 import { InvalidTokenError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
-import type { AuthService } from '../auth/auth.service.js';
-import { ACCOUNT_DEACTIVATED_MESSAGE, AccountDeactivatedError, AuthBackendError } from '../auth/account-admission.js';
-import type { IExternalApiKeyService } from '../tool-auth/external-api-key.interface.js';
-import type { InternalTokenService } from '../tool-auth/internal-token.service.js';
-import { rejectConnectionKey } from '../tool-auth/connection-key-rejection.js';
+import type { AuthService } from '../auth/index.js';
+import { ACCOUNT_DEACTIVATED_MESSAGE, AccountDeactivatedError, AuthBackendError } from '../auth/index.js';
+import type { IExternalApiKeyService, InternalTokenService } from '../tool-auth/index.js';
+import { rejectConnectionKey } from '../tool-auth/index.js';
 import type { BevelOAuthProvider } from './oauth/bevel-oauth-provider.js';
-import '../tool-auth/external-api-key.interface.js'; // Express Request augmentation (req.externalApiKeyId)
-import '../audit/audit.contract.js'; // Express Request augmentation (req.agentConnectionId)
+import '../tool-auth/index.js'; // Express Request augmentation (req.externalApiKeyId)
+import '../audit/index.js'; // Express Request augmentation (req.agentConnectionId)
 
 /** Which of the four credentials below an MCP request was authenticated with. */
 export type McpCallerKind = 'key' | 'oauth' | 'internal' | 'session';

package/src/modules/mcp/mcp.routes.ts

@@ -9,13 +9,11 @@ import {
   InvalidTokenLabelError,
   TokenNotFoundError,
   TokenStillActiveError,
-} from '../tool-auth/external-api-key.errors.js';
-import type { IExternalApiKeyService } from '../tool-auth/external-api-key.interface.js';
-import type { InternalTokenService } from '../tool-auth/internal-token.service.js';
+} from '../tool-auth/index.js';
+import type { IExternalApiKeyService, InternalTokenService, ILlmUsageMeter } from '../tool-auth/index.js';
 import { MCP_LOOPBACK_TOKEN_TTL_MS, type McpService } from './mcp.service.js';
 import type { BevelOAuthProvider } from './oauth/bevel-oauth-provider.js';
-import type { ILlmUsageMeter } from '../tool-auth/llm-usage-meter.js';
-import '../tool-auth/external-api-key.interface.js'; // req.externalApiKeyId augmentation
+import '../tool-auth/index.js'; // req.externalApiKeyId augmentation
 import './mcp-auth.middleware.js'; // req.mcpCallerKind augmentation
 import { isPagePath } from '../audit/index.js';
 

package/src/modules/mcp/mcp.service.ts

@@ -37,6 +37,7 @@ import {
   installSessionRecovery,
   flattenManualTool,
   toListedTool,
+  withReadOnlyOverride,
   toolError,
   retiredToolMessage,
   needsAuthorizationResult,
@@ -49,18 +50,13 @@ import {
   type LoadedSkill,
 } from '@bevel-software/platform-mcp-core';
 import type { KbLayout } from '@bevel-software/platform-shared';
-import { bevelSecretsLoaderConfig } from '../secrets-vault/index.js';
-import {
-  scopesCovered,
-  type ForcedRefreshOutcome,
-  type ISecretsVaultService,
-} from '../secrets-vault/secrets-vault.contract.js';
-import { EXTERNAL_KB_MANUAL_NAME } from '../tool-manuals/tool-manuals.contract.js';
-import type { IToolManualService } from '../tool-manuals/tool-manuals.contract.js';
-import type { SpillStore } from '../workspace/spill-store.js';
+import { bevelSecretsLoaderConfig, type ForcedRefreshOutcome, type ISecretsVaultService, scopesCovered } from '../secrets-vault/index.js';
+import { EXTERNAL_KB_MANUAL_NAME } from '../tool-manuals/index.js';
+import type { IToolManualService } from '../tool-manuals/index.js';
+import type { SpillStore } from '../workspace/index.js';
 import type { HiddenToolSource } from '../../shared/hidden-tools.js';
 import { seedBevelHostedManualVars } from '../../shared/utcp-namespace.js';
-import type { InternalTokenService } from '../tool-auth/internal-token.service.js';
+import type { InternalTokenService } from '../tool-auth/index.js';
 import { RequestAudit, type IAgentEventRecorder, type RecordedPrincipal } from '../audit/index.js';
 import { ManualFailureMemo } from './manual-failure-memo.js';
 import { DownstreamPool, POOL_KEY_SEPARATOR, type DownstreamPoolOptions, type Lease } from './downstream-pool.js';
@@ -78,7 +74,7 @@ import {
   type AgentPreambleReader,
   type ComposedAgentInstructions,
 } from '../agent-instructions/index.js';
-import { guideFirstDescription } from '../tool-registry/guide-first.js';
+import { guideFirstDescription } from '../tool-registry/index.js';
 
 /**
  * Configuration for the loopback proxy. `loopbackBaseUrl` is the backend's own
@@ -123,6 +119,16 @@ export interface McpProxyOptions {
    * knowledge base's.
    */
   secretsScope?: string;
+  /**
+   * The deployment's read-only overrides, by tool name, read per listing so an
+   * admin's change on the Tools page is in the next `tools/list`. Joined on
+   * here, at listing time, for the platform tools and the code-mode meta-tools
+   * alike: the platform tools' BUILT-IN hint arrives as the manual's
+   * `read-only` tag, in a surface that is cached across requests, so an
+   * override baked into it would outlive the toggle that set it. Absent, every
+   * tool lists its built-in hint.
+   */
+  readOnlyOverrides?: () => Promise<Readonly<Record<string, boolean>>>;
 }
 
 /** Who a request is from — everything the proxy needs, resolved from that request's own bearer. */
@@ -553,7 +559,15 @@ export class McpService {
     );
 
     server.setRequestHandler(ListToolsRequestSchema, async () => inRequest(async () => {
-      const [{ tools, catalogNames }, { toolPrefix }] = await Promise.all([requestSurface(), agentInstructions()]);
+      const [{ tools, catalogNames }, { toolPrefix }, readOnly] = await Promise.all([
+        requestSurface(),
+        agentInstructions(),
+        // A failed read lists the built-in hints rather than no listing at all.
+        this.opts.readOnlyOverrides?.().catch((err: unknown) => {
+          log.warn('tools/list: could not read the read-only overrides; listing built-in hints.', { err });
+          return undefined;
+        }),
+      ]);
       // A discovered tool whose name collides with a meta-tool would be
       // listed but never callable (the dispatcher routes the name to the
       // meta-tool first), so drop it from the listing entirely.
@@ -590,7 +604,9 @@ export class McpService {
         // place for it), so it is joined on here — the one point where a
         // discovered tool becomes a listing entry.
         const ui = apps && Object.hasOwn(apps.tools, t.mcpName) ? apps.tools[t.mcpName] : undefined;
-        const entry = toListedTool(ui ? { ...t, ui } : t); // logs its own reason on a name/schema drop
+        // An admin's override of a platform tool's hint, read for THIS listing.
+        const hinted = withReadOnlyOverride(t, readOnly);
+        const entry = toListedTool(ui ? { ...hinted, ui } : hinted); // logs its own reason on a name/schema drop
         if (!entry) {
           dropped.push(t.mcpName);
           continue;
@@ -641,6 +657,7 @@ export class McpService {
       // built here, so here it is.
       const metaTools = codeModeMetaTools(EXTERNAL_KB_MANUAL_NAME, examplePool, {
         sharedRulesPointer: '',
+        ...(readOnly ? { readOnly } : {}),
       }).map((tool) => ({ ...tool, description: guideFirstDescription(tool.description) }));
       // Log only when a tool was dropped (name/schema/duplicate) — that's the
       // anomaly worth surfacing, since a downstream client would otherwise hide