@stage-labs/metro 0.1.0-beta.304 → 0.1.0-beta.306

package/runtime/node_modules/@metro-labs/daemon/src/mcp-server/announced.ts

@@ -0,0 +1,68 @@
+import { errMsg, log } from '@metro-labs/core/log';
+import { isRecord } from '@metro-labs/core/is-record';
+import { readJson, writeSecure } from '@metro-labs/core/secure-fs';
+import { MCP_APPROVAL_ID_RE } from '@metro-labs/http/mcp-server-protocol';
+
+const KEEP_MS = 24 * 3_600_000;
+const MAX = 200;
+
+interface Announced {
+  line: string;
+  at: number;
+}
+
+let file: string | undefined;
+let known = new Map<string, Announced>();
+
+function entryOf(raw: unknown): Announced | null {
+  if (!isRecord(raw) || typeof raw.line !== 'string' || !raw.line.startsWith('metro://') || typeof raw.at !== 'number' || !Number.isFinite(raw.at)) return null;
+  return { line: raw.line, at: raw.at };
+}
+
+function parse(raw: unknown): Map<string, Announced> {
+  const out = new Map<string, Announced>();
+  const entries = isRecord(raw) && raw.version === 1 && isRecord(raw.announced) ? raw.announced : {};
+  for (const [id, value] of Object.entries(entries)) {
+    const entry = entryOf(value);
+    if (MCP_APPROVAL_ID_RE.test(id) && entry !== null) out.set(id, entry);
+  }
+  return out;
+}
+
+function prune(now: number): void {
+  for (const [id, entry] of known) if (now - entry.at >= KEEP_MS || entry.at > now) known.delete(id);
+  const oldest = [...known].sort(([, a], [, b]) => a.at - b.at);
+  for (const [id] of oldest.slice(0, Math.max(0, known.size - MAX))) known.delete(id);
+}
+
+function save(): void {
+  if (file === undefined) return;
+  const announced = Object.fromEntries([...known].map(([id, entry]) => [id, { line: entry.line, at: entry.at }]));
+  try {
+    writeSecure(file, `${JSON.stringify({ version: 1, announced })}\n`);
+  } catch (err) {
+    log.warn({ err: errMsg(err) }, 'mcp-server: the announced approvals could not be saved, so they are kept in memory only');
+  }
+}
+
+export function setAnnouncedFile(path: string, now = Date.now()): void {
+  file = path;
+  known = parse(readJson<unknown>(path, null, { warn: 'mcp-server: the announced approvals file is not valid JSON, so it was ignored' }));
+  prune(now);
+}
+
+export function announcedLine(id: string, now = Date.now()): string | undefined {
+  const entry = known.get(id);
+  return entry !== undefined && now - entry.at < KEEP_MS && entry.at <= now ? entry.line : undefined;
+}
+
+export function noteAnnounced(id: string, line: string, now = Date.now()): void {
+  known.set(id, { line, at: now });
+  prune(now);
+  save();
+}
+
+export function forgetAnnounced(): void {
+  file = undefined;
+  known = new Map();
+}

package/runtime/node_modules/@metro-labs/daemon/src/mcp-server/config.ts

@@ -1,6 +1,6 @@
 import { log } from '@metro-labs/core/log';
 
-export const MCP_SERVER_KEY = 'mcp';
+const DEFAULT_URL = 'https://mcp.metro.box';
 
 const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]']);
 
@@ -18,7 +18,7 @@ function usable(raw: string): boolean {
 }
 
 export function mcpServerUrl(env: NodeJS.ProcessEnv = process.env): string | null {
-  const raw = env.METRO_MCP_SERVER_URL?.trim() ?? '';
+  const raw = env.METRO_MCP_SERVER_URL?.trim() ?? DEFAULT_URL;
   if (raw === '') return null;
   if (usable(raw)) return raw.replace(/\/+$/, '');
   if (refused !== raw) {

package/runtime/node_modules/@metro-labs/daemon/src/mcp-server/connector-tools.ts

@@ -0,0 +1,114 @@
+import { isRecord } from '@metro-labs/core/is-record';
+import { errMsg, log } from '@metro-labs/core/log';
+import { TOOL_CALL, TOOL_SEARCH } from '@metro-labs/http/mcp-server-protocol';
+import { mcpServerTools, type McpServerTool } from '@metro-labs/http/mcp-server-tools';
+import { askServer, type ServerAnswer, type ServerDeps } from './rpc.js';
+
+export const CONNECTOR_TOOLS: ReadonlySet<string> = new Set([TOOL_SEARCH, TOOL_CALL]);
+
+export const CALL_TIMEOUT_MS = 120_000;
+const LIST_TIMEOUT_MS = 15_000;
+const REFRESH_MS = 5 * 60_000;
+
+export const NOT_SET_UP = 'Connectors are not set up on this agent: enroll it in its organization on the Server page of metro.box, then try again.';
+export const UNAVAILABLE = 'mcp.metro.box is unavailable, try again.';
+
+export interface ConnectorResult {
+  [key: string]: unknown;
+  content: unknown[];
+  isError?: boolean;
+}
+
+const FALLBACK = mcpServerTools(null);
+let current: McpServerTool[] = FALLBACK;
+let version = 0;
+const listeners = new Set<() => void>();
+
+export const connectorTools = (): McpServerTool[] => current;
+
+export const connectorToolsVersion = (): number => version;
+
+export function onConnectorToolsChanged(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+function toolOf(raw: unknown, fallback: McpServerTool): McpServerTool | null {
+  if (!isRecord(raw) || typeof raw.description !== 'string' || !isRecord(raw.inputSchema)) return null;
+  return {
+    name: fallback.name,
+    title: typeof raw.title === 'string' ? raw.title : fallback.title,
+    description: raw.description,
+    inputSchema: raw.inputSchema,
+    annotations: isRecord(raw.annotations) ? raw.annotations : fallback.annotations,
+  };
+}
+
+function servedTools(result: unknown): McpServerTool[] | null {
+  const tools: unknown[] = isRecord(result) && Array.isArray(result.tools) ? result.tools : [];
+  const picked = FALLBACK.map((fallback) => toolOf(tools.find((tool) => isRecord(tool) && tool.name === fallback.name), fallback));
+  return picked.every((tool): tool is McpServerTool => tool !== null) ? picked : null;
+}
+
+function changed(): void {
+  for (const listener of listeners)
+    try {
+      listener();
+    } catch (err) {
+      log.warn({ err: errMsg(err) }, 'mcp-server: a tool list listener failed');
+    }
+}
+
+export async function refreshConnectorTools(deps: ServerDeps = {}): Promise<boolean> {
+  const answer = await askServer('tools/list', {}, LIST_TIMEOUT_MS, deps);
+  const tools = answer.ok ? servedTools(answer.result) : null;
+  if (tools === null) {
+    if (!answer.ok && answer.reason !== 'unset') log.debug({ reason: answer.reason }, 'mcp-server: the connector tool list could not be read');
+    return false;
+  }
+  if (JSON.stringify(tools) === JSON.stringify(current)) return false;
+  current = tools;
+  version += 1;
+  log.info({ version }, 'mcp-server: the connector tools changed, the session is told');
+  changed();
+  return true;
+}
+
+let timer: ReturnType<typeof setInterval> | null = null;
+
+export function watchConnectorTools(everyMs = REFRESH_MS): () => void {
+  const tick = (): void => {
+    refreshConnectorTools().catch((err: unknown) => {
+      log.warn({ err: errMsg(err) }, 'mcp-server: the connector tool refresh failed');
+    });
+  };
+  if (timer === null) {
+    tick();
+    timer = setInterval(tick, everyMs);
+    timer.unref();
+  }
+  return () => {
+    if (timer !== null) clearInterval(timer);
+    timer = null;
+  };
+}
+
+const errorResult = (text: string): ConnectorResult => ({ content: [{ type: 'text', text }], isError: true });
+
+function resultOf(name: string, answer: ServerAnswer): ConnectorResult {
+  if (answer.ok) {
+    if (isRecord(answer.result) && Array.isArray(answer.result.content)) return answer.result as ConnectorResult;
+    log.warn({ tool: name }, 'mcp-server: mcp.metro.box answered a tool call without content');
+    return errorResult(UNAVAILABLE);
+  }
+  if (answer.reason === 'unset') return errorResult(NOT_SET_UP);
+  if (answer.reason === 'refused') return errorResult(`mcp.metro.box refused the call: ${answer.message}`);
+  log.warn({ tool: name, detail: answer.detail }, 'mcp-server: a connector tool call did not reach mcp.metro.box');
+  return errorResult(UNAVAILABLE);
+}
+
+export async function callConnectorTool(name: string, args: Record<string, unknown>, deps: ServerDeps = {}): Promise<ConnectorResult> {
+  return resultOf(name, await askServer('tools/call', { name, arguments: args }, CALL_TIMEOUT_MS, deps));
+}

package/runtime/node_modules/@metro-labs/daemon/src/mcp-server/link.ts

@@ -24,6 +24,7 @@ export interface McpLinkDeps {
   key: () => AgentKey | null;
   dir: () => string;
   hold: HoldApproval;
+  registered?: () => void;
   fetch?: AgentFetch;
   timing?: Partial<McpTiming>;
 }
@@ -61,6 +62,10 @@ export class McpServerLink {
     await this.running;
   }
 
+  reregister(): void {
+    this.registered = null;
+  }
+
   async answer(id: string, decision: McpDecision): Promise<AnswerOutcome> {
     for (let attempt = 0; !this.stopped; attempt += 1) {
       if (attempt > 0) await this.pause(this.delay(attempt));
@@ -124,6 +129,7 @@ export class McpServerLink {
     await agentCall(this.api, key, MCP_PATHS.token, { tokenHash: token.hash }, { signal: this.abort.signal });
     this.registered = binding;
     log.info({ server: this.deps.url, keyId: key.keyId }, 'mcp-server: the MCP token is registered');
+    this.deps.registered?.();
   }
 
   private async poll(key: AgentKey): Promise<void> {
@@ -168,17 +174,22 @@ let active: McpServerLink | null = null;
 export interface McpServerWatch {
   owner: () => string | null;
   hold: HoldApproval;
+  registered?: () => void;
 }
 
 export function watchMcpServer(watch: McpServerWatch, env: NodeJS.ProcessEnv = process.env): boolean {
   const url = mcpServerUrl(env);
   if (url === null || active !== null) return false;
-  active = new McpServerLink({ url, owner: watch.owner, key: () => readAgentKey(), dir: agentsDir, hold: watch.hold });
+  active = new McpServerLink({ url, owner: watch.owner, key: () => readAgentKey(), dir: agentsDir, hold: watch.hold, ...(watch.registered === undefined ? {} : { registered: watch.registered }) });
   active.start();
   log.info({ server: url }, 'mcp-server: connector approvals relay from this server once the agent is enrolled');
   return true;
 }
 
+export function reregisterMcpToken(): void {
+  active?.reregister();
+}
+
 export async function stopMcpServer(): Promise<void> {
   const link = active;
   active = null;

package/runtime/node_modules/@metro-labs/daemon/src/mcp-server/rpc.ts

@@ -0,0 +1,67 @@
+import { isRecord } from '@metro-labs/core/is-record';
+import { errMsg } from '@metro-labs/core/log';
+import { agentsDir } from '../agents/files.js';
+import { mcpServerUrl } from './config.js';
+import { reregisterMcpToken } from './link.js';
+import { readMcpToken } from './token.js';
+
+export interface ServerDeps {
+  url?: string | null;
+  token?: string | null;
+  fetch?: (url: string, init: RequestInit) => Promise<Response>;
+  reregister?: () => void;
+}
+
+export type ServerAnswer =
+  | { ok: true; result: unknown }
+  | { ok: false; reason: 'unset' }
+  | { ok: false; reason: 'unavailable'; detail: string }
+  | { ok: false; reason: 'refused'; message: string };
+
+let nextId = 1;
+
+const unavailable = (detail: string): ServerAnswer => ({ ok: false, reason: 'unavailable', detail });
+
+async function bodyOf(res: Response): Promise<ServerAnswer> {
+  let body: unknown;
+  try {
+    body = JSON.parse(await res.text());
+  } catch (err) {
+    return unavailable(`unreadable answer: ${errMsg(err)}`);
+  }
+  if (isRecord(body) && isRecord(body.error))
+    return { ok: false, reason: 'refused', message: typeof body.error.message === 'string' ? body.error.message.slice(0, 500) : 'refused' };
+  return isRecord(body) && Object.hasOwn(body, 'result') ? { ok: true, result: body.result } : unavailable('no JSON-RPC result');
+}
+
+interface Target {
+  url: string;
+  token: string;
+}
+
+function targetOf(deps: ServerDeps): Target | null {
+  const url = deps.url === undefined ? mcpServerUrl() : deps.url;
+  const token = deps.token === undefined ? readMcpToken(agentsDir()) : deps.token;
+  return url === null || token === null ? null : { url, token };
+}
+
+export async function askServer(method: string, params: Record<string, unknown>, timeoutMs: number, deps: ServerDeps = {}): Promise<ServerAnswer> {
+  const target = targetOf(deps);
+  if (target === null) return { ok: false, reason: 'unset' };
+  const { url, token } = target;
+  let res: Response;
+  try {
+    res = await (deps.fetch ?? fetch)(`${url}/`, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json', accept: 'application/json, text/event-stream' },
+      body: JSON.stringify({ jsonrpc: '2.0', id: nextId++, method, params }),
+      redirect: 'manual',
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (err) {
+    return unavailable(errMsg(err));
+  }
+  if (res.status === 401) (deps.reregister ?? reregisterMcpToken)();
+  if (!res.ok) return unavailable(`HTTP ${String(res.status)}`);
+  return bodyOf(res);
+}

package/runtime/node_modules/@metro-labs/daemon/src/policy/policy.ts

@@ -13,9 +13,11 @@ export interface ToolPolicy {
   tools?: Record<string, Access>;
 }
 
-export type PolicyTarget =
-  | { kind: 'channel'; station: string; account: string }
-  | { kind: 'connector'; id: string };
+export interface PolicyTarget {
+  kind: 'channel';
+  station: string;
+  account: string;
+}
 
 export interface PolicyTool {
   name: string;
@@ -28,8 +30,7 @@ const RANK: Record<Access, number> = { allow: 0, ask: 1, deny: 2 };
 
 const isAccess = (value: unknown): value is Access => typeof value === 'string' && (ACCESS as readonly string[]).includes(value);
 
-export const targetKey = (target: PolicyTarget): string =>
-  target.kind === 'channel' ? `channel:${target.station}/${target.account}` : `connector:${target.id}`;
+export const targetKey = (target: PolicyTarget): string => `channel:${target.station}/${target.account}`;
 
 export function decide(policy: ToolPolicy | undefined, tool: PolicyTool): Access {
   const byTool = policy?.tools !== undefined && Object.hasOwn(policy.tools, tool.name) ? policy.tools[tool.name] : undefined;

package/runtime/node_modules/@metro-labs/daemon/src/routes/http.ts

@@ -1,6 +1,5 @@
 import { handleSessionApis, type SessionApis } from './session-apis.js';
 import { handleGatewayRequest } from '../gateway/gateway.js';
-import { handleRelayRequest } from '../connectors/relay.js';
 import { handleThreemaCallback } from './threema-callback.js';
 import { BodyTooLargeError, readBody, WEBHOOK_BODY_MAX } from './body.js';
 
@@ -346,7 +345,6 @@ async function handlePreMcpRoutes(
   if (handleEarlyRoutes(req, res, apis)) return true;
   if (handleUploadRequest(req, res)) return true;
   if (handleAttachRequest(req, res)) return true;
-  if (apis.relayApi && handleRelayRequest(req, res, apis.relayApi)) return true;
   if (await handleWebhookRoute(req, res, emit)) return true;
   if (await handleThreemaCallback(req, res)) return true;
   return monitor && handleMonitorRequest(req, res);

package/runtime/node_modules/@metro-labs/daemon/src/routes/local-mode.ts

@@ -6,16 +6,12 @@ import { assertAttachOwner, finishGmailUpgrade, startGmailAttach } from './gmail
 import { detachWithGmailRevocation } from './gmail-detach.js';
 import { recentSenders } from '../agents/senders.js';
 import { forwardTrainCall } from '../stations/train-call.js';
-import { invalidateOrgConnectorSync, orgConnectorRelaySession, orgConnectorSyncStatus, setOrgConnectorSync } from '../connectors/org-sync-watch.js';
 import type { AgentApiDeps } from '../agents/api.js';
 import { ATTACHABLE, type AccountApiDeps } from '../agents/accounts-api.js';
 import type { SessionApis } from './session-apis.js';
 import type { ModeInfo } from '@metro-labs/http/mode-api';
 import { loadedAgentOf, type AgentBundle, type BundleApiDeps } from '../agents/bundle.js';
 import { METRO_VERSION } from '@metro-labs/core/version';
-import { authenticate } from '../mcp/request-identity.js';
-import type { RelayApiDeps } from '../connectors/relay.js';
-import { connectorGates } from '../connectors/gates.js';
 import {
   setLocalOwner,
   localAttachAccount,
@@ -78,7 +74,6 @@ function agentApi(deps: LocalModeDeps): AgentApiDeps {
     ...(deps.toolGroups === undefined ? {} : { toolGroups: deps.toolGroups }),
     attachable: ATTACHABLE.filter((s) => s !== 'webhook'),
     features: ['gmail-managed'],
-    connectorIds: connectorIdsOfLocalAgents,
     prepareAccount: deps.prepareAccount,
     attachAccount: localAttachAccount,
     detachAccount: detachWithGmailRevocation,
@@ -93,20 +88,6 @@ function agentApi(deps: LocalModeDeps): AgentApiDeps {
   };
 }
 
-function connectorIdsOfLocalAgents(ids: string[]): Promise<Map<string, string[]>> {
-  const all = connectorGates().map((gate) => gate.id);
-  return Promise.resolve(new Map(ids.map((id) => [id, all] as const)));
-}
-
-const relayApi: RelayApiDeps = {
-  open: orgConnectorRelaySession,
-  identify: (req) => {
-    const who = authenticate(req);
-    return who?.kind === 'agent' ? { subject: 'agent-key', agentId: who.agentId } : null;
-  },
-};
-
-
 function bundleApi(deps: LocalModeDeps): BundleApiDeps {
   return {
     bundle: (agentId) => {
@@ -155,17 +136,11 @@ export function localSessionApis(deps: LocalModeDeps): SessionApis {
   return {
     agentApi: agentApi(deps),
     bundleApi: bundleApi(deps),
-    connectorSyncApi: { status: orgConnectorSyncStatus, set: setOrgConnectorSync },
-    enrollApi: { owner: () => localOwner(), invalidate: invalidateOrgConnectorSync },
-    relayApi,
+    enrollApi: { owner: () => localOwner() },
     claudeApi: { liveEvents: deps.liveEvents },
     updateApi: { restart: deps.restart },
     controlApi: { restart: deps.restart, stop: deps.stop },
-    ownerApi: { setOwner: (owner) => {
-      const saved = setLocalOwner(owner);
-      invalidateOrgConnectorSync();
-      return saved;
-    } },
+    ownerApi: { setOwner: setLocalOwner },
     machineApi: {},
     modelApi: { switchModel: deps.switchModel, owner: localOwner },
     gateway: { config: readModelConfig },

package/runtime/node_modules/@metro-labs/daemon/src/routes/session-apis.ts

@@ -2,8 +2,6 @@ import type { IncomingMessage, ServerResponse } from 'node:http';
 import { handleSessionApiRequest } from './session.js';
 import { handleApprovalsRequest } from '../approvals/api.js';
 import { handleAgentApiRequest, type AgentApiDeps } from '../agents/api.js';
-import type { RelayApiDeps } from '../connectors/relay.js';
-import { handleConnectorSyncRequest, type ConnectorSyncApiDeps } from '../connectors/org-sync-api.js';
 import { handleEnrollRequest, type EnrollApiDeps } from '../connectors/enroll-api.js';
 import { handleClaudeRequest, type ClaudeApiDeps } from '../claude/api.js';
 import type { ModeInfo } from '@metro-labs/http/mode-api';
@@ -33,8 +31,6 @@ export interface SessionApis {
   terminalApi?: TerminalApiDeps;
   claudeApi?: ClaudeApiDeps;
   enrollApi?: EnrollApiDeps;
-  connectorSyncApi?: ConnectorSyncApiDeps;
-  relayApi?: RelayApiDeps;
   mode?: () => ModeInfo;
 }
 
@@ -51,7 +47,6 @@ export function handleSessionApis(
     () => handleRunEventsRequest(req, res),
     () => handleApprovalsRequest(req, res),
     ...when(apis.enrollApi, (d) => handleEnrollRequest(req, res, d)),
-    ...when(apis.connectorSyncApi, (d) => handleConnectorSyncRequest(req, res, d)),
     ...when(apis.bundleApi, (d) => handleBundleRequest(req, res, d)),
     ...when(apis.updateApi, (d) => handleUpdateRequest(req, res, d)),
     ...when(apis.controlApi, (d) => handleControlRequest(req, res, d)),

package/runtime/node_modules/@metro-labs/http/package.json

@@ -22,10 +22,10 @@
     "./connector-discovery": "./src/connector-discovery.ts",
     "./connector-oauth": "./src/connector-oauth.ts",
     "./connector-input": "./src/connector-input.ts",
-    "./connector-delivery": "./src/connector-delivery.ts",
-    "./connector-migration": "./src/connector-migration.ts",
+    "./connector-policy": "./src/connector-policy.ts",
     "./connector-grant": "./src/connector-grant.ts",
-    "./mcp-server-protocol": "./src/mcp-server-protocol.ts"
+    "./mcp-server-protocol": "./src/mcp-server-protocol.ts",
+    "./mcp-server-tools": "./src/mcp-server-tools.ts"
   },
   "scripts": {
     "build": "tsc",

package/runtime/node_modules/@metro-labs/http/src/connector-grant.ts

@@ -1,59 +1,8 @@
-import { deliveryRecord } from './connector-delivery-validation.js';
-import type { OAuthAuth } from './connector-mcp.js';
 import { boundOAuthResource, parsePublicConnectorUrl } from './connector-public-url.js';
 
-export interface PortableGrant extends OAuthAuth {
-  resource: string;
-  tokenEndpointAuthMethod: 'none' | 'client_secret_post';
-}
-
-const invalid = (): never => { throw new Error('This OAuth grant cannot be transferred. Its client authentication or provider binding is unsupported. Sign in separately.'); };
-
-function text(raw: unknown, max = 16384): string {
-  if (typeof raw !== 'string' || raw.length === 0 || raw.length > max || /[^\x21-\x7e]/.test(raw)) return invalid();
-  return raw;
-}
-
-function endpoint(raw: unknown): string {
-  const value = text(raw, 2048);
-  parsePublicConnectorUrl(value);
-  return value;
-}
-
 export function grantResource(target: string, raw: unknown): string {
   const transport = parsePublicConnectorUrl(target);
   const resource = parsePublicConnectorUrl(raw);
   if (resource.toString() === transport.toString() && typeof raw === 'string') return raw;
   return boundOAuthResource(target, raw);
 }
-
-function binding(value: Record<string, unknown>): Pick<PortableGrant, 'clientId' | 'clientSecret' | 'tokenEndpointAuthMethod'> {
-  const clientSecret = value.clientSecret === undefined ? undefined : text(value.clientSecret);
-  const method = value.tokenEndpointAuthMethod ?? (clientSecret === undefined ? 'none' : 'client_secret_post');
-  if (method !== 'none' && method !== 'client_secret_post') return invalid();
-  if ((method === 'client_secret_post') !== (clientSecret !== undefined)) return invalid();
-  return { clientId: text(value.clientId), tokenEndpointAuthMethod: method, ...(clientSecret === undefined ? {} : { clientSecret }) };
-}
-
-function expiry(raw: unknown): Pick<PortableGrant, 'expiresAt'> {
-  if (raw === undefined) return {};
-  if (typeof raw !== 'number' || !Number.isSafeInteger(raw) || raw < 0) return invalid();
-  return { expiresAt: raw };
-}
-
-function scopeOf(raw: unknown): Pick<PortableGrant, 'scope'> {
-  if (raw === undefined) return {};
-  if (typeof raw !== 'string' || raw.length > 16384 || /[^\x20-\x7e]/.test(raw)) return invalid();
-  return { scope: raw };
-}
-
-export function portableGrant(raw: unknown, target: string): PortableGrant {
-  const value = deliveryRecord(raw, ['kind', 'accessToken', 'refreshToken', 'expiresAt', 'clientId', 'clientSecret', 'issuer', 'tokenEndpoint', 'scope', 'resource', 'tokenEndpointAuthMethod']);
-  if (value.kind !== 'oauth') return invalid();
-  return {
-    kind: 'oauth', accessToken: text(value.accessToken, 16377), issuer: endpoint(value.issuer), tokenEndpoint: endpoint(value.tokenEndpoint),
-    resource: grantResource(target, value.resource ?? parsePublicConnectorUrl(target).toString()),
-    ...binding(value), ...expiry(value.expiresAt), ...scopeOf(value.scope),
-    ...(value.refreshToken === undefined ? {} : { refreshToken: text(value.refreshToken) }),
-  };
-}

package/runtime/node_modules/@metro-labs/http/src/mcp-server-protocol.ts

@@ -7,6 +7,11 @@ export const MCP_CALLS_MAX = 10;
 export const MCP_QUERY_MAX = 500;
 export const MCP_APPROVAL_WAIT_MS = 25_000;
 export const MCP_APPROVAL_ID_RE = /^[a-km-z]{5}$/;
+export const TOOL_SEARCH = 'tool_search';
+export const TOOL_CALL = 'tool_call';
+export const TOOL_CALL_EXAMPLE = '{"calls":[{"tool":"notion.search","arguments":{"query":"roadmap"}}]}';
+
+const EXPECTED = ` Expected: ${TOOL_CALL_EXAMPLE}, with names as tool_search returns them.`;
 export const MCP_TOKEN_RE = /^mcp_[A-Za-z0-9_-]{43}$/;
 
 export type McpErrorCode = 'blocked' | 'needs_approval' | 'denied' | 'not_found' | 'signin' | 'unavailable' | 'vendor_error' | 'invalid';
@@ -40,23 +45,23 @@ export function splitMcpTool(name: string): { connector: string; tool: string }
 }
 
 export function mcpFindRequestOf(raw: unknown): McpFindRequest {
-  if (!isRecord(raw) || typeof raw.query !== 'string' || raw.query.trim() === '' || raw.query.length > MCP_QUERY_MAX) throw new Error('find_tools needs a query of 1 to 500 characters.');
+  if (!isRecord(raw) || typeof raw.query !== 'string' || raw.query.trim() === '' || raw.query.length > MCP_QUERY_MAX) throw new Error('tool_search needs a query of 1 to 500 characters.');
   const wanted = raw.max_results ?? MCP_FIND_DEFAULT;
   if (typeof wanted !== 'number' || !Number.isInteger(wanted) || wanted < 1) throw new Error('max_results must be a whole number from 1.');
   return { query: raw.query.trim(), max_results: Math.min(wanted, MCP_FIND_MAX) };
 }
 
 function callOf(raw: unknown): McpCall {
-  if (!isRecord(raw) || typeof raw.tool !== 'string' || splitMcpTool(raw.tool) === null) throw new Error('Each call needs a tool named <connector>.<tool>, as find_tools returns it.');
+  if (!isRecord(raw) || typeof raw.tool !== 'string' || splitMcpTool(raw.tool) === null) throw new Error(`Each call needs a tool named <connector>.<tool>, as tool_search returns it.${EXPECTED}`);
   const args = raw.arguments ?? {};
-  if (!isRecord(args)) throw new Error(`The arguments of ${raw.tool} must be an object.`);
+  if (!isRecord(args)) throw new Error(`The arguments of ${raw.tool} must be an object.${EXPECTED}`);
   if (raw.approval !== undefined && (typeof raw.approval !== 'string' || !MCP_APPROVAL_ID_RE.test(raw.approval))) throw new Error('approval must be the 5-letter id the approval request gave.');
   return { tool: raw.tool, arguments: args, ...(typeof raw.approval === 'string' ? { approval: raw.approval } : {}) };
 }
 
 export function mcpCallsOf(raw: unknown): McpCall[] {
   const calls = isRecord(raw) ? raw.calls : undefined;
-  if (!Array.isArray(calls) || calls.length === 0 || calls.length > MCP_CALLS_MAX) throw new Error(`call_tool needs 1 to ${String(MCP_CALLS_MAX)} calls.`);
+  if (!Array.isArray(calls) || calls.length === 0 || calls.length > MCP_CALLS_MAX) throw new Error(`tool_call needs 1 to ${String(MCP_CALLS_MAX)} calls in "calls".${EXPECTED}`);
   return calls.map(callOf);
 }
 

package/runtime/node_modules/@metro-labs/http/src/mcp-server-tools.ts

@@ -0,0 +1,93 @@
+import { MCP_CALLS_MAX, MCP_FIND_DEFAULT, MCP_FIND_MAX, TOOL_CALL, TOOL_CALL_EXAMPLE, TOOL_SEARCH } from './mcp-server-protocol.js';
+
+export interface McpServerTool {
+  name: string;
+  title: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  annotations: Record<string, unknown>;
+}
+
+const searchSchema = {
+  type: 'object',
+  properties: {
+    query: {
+      type: 'string',
+      description: 'What to look for: "select:<connector>.<tool>" (comma separated) loads exact tools, keywords rank tools, "+word" requires that word in the tool name.',
+    },
+    max_results: { type: 'number', description: `Maximum number of results to return (default: ${String(MCP_FIND_DEFAULT)}, at most ${String(MCP_FIND_MAX)})`, default: MCP_FIND_DEFAULT },
+  },
+  required: ['query'],
+  additionalProperties: false,
+};
+
+const callSchema = {
+  type: 'object',
+  properties: {
+    calls: {
+      type: 'array',
+      minItems: 1,
+      maxItems: MCP_CALLS_MAX,
+      description: `1 to ${String(MCP_CALLS_MAX)} independent calls. They run in parallel and are answered in order.`,
+      items: {
+        type: 'object',
+        properties: {
+          tool: { type: 'string', description: 'The tool name exactly as tool_search returned it: <connector>.<tool>.' },
+          arguments: { type: 'object', description: 'The tool\'s arguments, matching the parameters tool_search returned.', additionalProperties: true },
+          approval: { type: 'string', pattern: '^[a-km-z]{5}$', description: 'The 5-letter approval id, only when repeating a call the owner approved.' },
+        },
+        required: ['tool'],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ['calls'],
+  additionalProperties: false,
+};
+
+function connectorsLine(keys: string[] | null): string {
+  if (keys === null) return 'The connectors of this agent are named here once Metro reaches mcp.metro.box.';
+  return keys.length === 0 ? 'This agent has no connectors it may use yet.' : `This agent's connectors: ${keys.join(', ')}.`;
+}
+
+export const toolSearchDescription = (keys: string[] | null): string =>
+  [
+    'Search the tools of every connector assigned to this agent: third-party services such as Notion, n8n, Linear or Gmail, run by mcp.metro.box. Same design as Claude Code\'s ToolSearch, for connectors.',
+    connectorsLine(keys),
+    'Three query forms, one example each:',
+    '- "select:notion.search" loads exact tools by name (comma separated for several).',
+    '- "notion create page" ranks tools by the words in their name and description.',
+    '- "+linear issue" requires "linear" in the tool name and ranks by the other words.',
+    'Results are full definitions (name, description and the JSON schema of the arguments) in a <functions> block. Each name is <connector>.<tool>: pass it exactly as "tool" to tool_call. Tools the owner blocked are never returned.',
+  ].join('\n');
+
+export const TOOL_CALL_DESCRIPTION = [
+  'Run connector tools that tool_search found. Always find a tool with tool_search first: its exact name and argument schema come from there.',
+  `Shape: ${TOOL_CALL_EXAMPLE}`,
+  `Up to ${String(MCP_CALLS_MAX)} independent calls run in parallel in one tool_call and are answered in order. Each result starts with "[n] <connector>.<tool>", then the tool's own content, or one line saying why it did not run:`,
+  '- not_found: no such connector or tool here. Run tool_search, then use a name it returned.',
+  '- needs_approval: the owner was asked in chat and on metro.box. Tell the person what is waiting, wait for the channel message "Approved: <tool> (<id>)", then call again with the same tool and arguments plus "approval": "<id>". An approval works once.',
+  '- denied or blocked: the owner refused or blocked this call. Do not retry it.',
+  '- signin: the connector must be signed in again. Tell the owner to do it on the organization\'s Connectors page on metro.box.',
+  '- unavailable: the connector or Metro could not be reached. Try again later.',
+  '- vendor_error: the connector answered with its own error, shown as it came.',
+].join('\n');
+
+export function mcpServerTools(keys: string[] | null): McpServerTool[] {
+  return [
+    {
+      name: TOOL_SEARCH,
+      title: 'Search connector tools',
+      description: toolSearchDescription(keys),
+      inputSchema: searchSchema,
+      annotations: { title: 'Search connector tools', readOnlyHint: true, openWorldHint: false },
+    },
+    {
+      name: TOOL_CALL,
+      title: 'Call connector tools',
+      description: TOOL_CALL_DESCRIPTION,
+      inputSchema: callSchema,
+      annotations: { title: 'Call connector tools', readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    },
+  ];
+}