@stage-labs/metro 0.1.0-beta.7 → 0.1.0-beta.71

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

@@ -0,0 +1,330 @@
+import { errMsg, log } from './log.js';
+import {
+  ConnectorNotMcp,
+  ConnectorUnauthorized,
+  refused,
+  safeIconSrc,
+} from './connector-url.js';
+import { toToolList, type ToolInfo } from './connector-tools.js';
+
+export {
+  ConnectorUnauthorized,
+  ConnectorVerifyError,
+  connectorUrlText,
+  parseConnectorUrl,
+} from './connector-url.js';
+import { isRecord } from './is-record.js';
+
+export interface OAuthTokens {
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt?: number;
+}
+
+export interface OAuthAuth extends OAuthTokens {
+  kind: 'oauth';
+  issuer: string;
+  tokenEndpoint: string;
+  clientId: string;
+  clientSecret?: string;
+}
+
+export type ConnectorAuth =
+  | { kind: 'none' }
+  | { kind: 'header'; name: string; value: string }
+  | OAuthAuth;
+
+export interface VerifiedServer {
+  server: string;
+  version: string;
+  protocol: string;
+  icon: string;
+  tools: number;
+  catalog: ToolInfo[];
+}
+
+export interface VerifiedRecord extends VerifiedServer {
+  at: string;
+}
+
+const PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18'] as const;
+const MAX_TOOL_PAGES = 10;
+
+function notMcp(url: URL): ConnectorNotMcp {
+  return new ConnectorNotMcp(
+    `${url.hostname} answered, but it does not speak MCP.`,
+    400,
+  );
+}
+const PROBE_TIMEOUT_MS = 10_000;
+const ACCEPT = 'application/json, text/event-stream';
+
+async function discard(res: Response): Promise<void> {
+  await res.body?.cancel().catch((err: unknown) => {
+    log.debug(
+      { err: errMsg(err) },
+      'connector-verify: could not discard a response body',
+    );
+  });
+}
+
+function authHeaders(auth: ConnectorAuth): Record<string, string> {
+  if (auth.kind === 'header') return { [auth.name]: auth.value };
+  if (auth.kind === 'oauth')
+    return { authorization: `Bearer ${auth.accessToken}` };
+  return {};
+}
+
+async function frame(
+  url: URL,
+  auth: ConnectorAuth,
+  extra: Record<string, string>,
+  body: unknown,
+  signal: AbortSignal,
+): Promise<Response> {
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      method: 'POST',
+      redirect: 'manual',
+      signal,
+      headers: {
+        'content-type': 'application/json',
+        accept: ACCEPT,
+        ...authHeaders(auth),
+        ...extra,
+      },
+      body: JSON.stringify(body),
+    });
+  } catch {
+    throw refused(`Metro could not reach ${url.hostname}.`);
+  }
+  if (res.status >= 300 && res.status < 400) {
+    await discard(res);
+    throw refused('that url redirects — use the url it redirects to');
+  }
+  return res;
+}
+
+function sseData(body: string): string {
+  for (const line of body.replace(/\r\n/g, '\n').split('\n'))
+    if (line.startsWith('data:')) return line.slice(5).trim();
+  return '';
+}
+
+async function payloadOf(res: Response): Promise<string> {
+  const contentType = res.headers.get('content-type') ?? '';
+  const text = await res.text().catch(() => '');
+  return contentType.includes('text/event-stream') ? sseData(text) : text;
+}
+
+async function resultOrNull(
+  res: Response,
+): Promise<Record<string, unknown> | null> {
+  const payload = await payloadOf(res);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(payload);
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed) || !isRecord(parsed.result)) return null;
+  return parsed.result;
+}
+
+function initializeBody(version: string): unknown {
+  return {
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'initialize',
+    params: {
+      protocolVersion: version,
+      capabilities: {},
+      clientInfo: { name: 'metro', version: '0.1.0' },
+    },
+  };
+}
+
+function iconOf(info: Record<string, unknown>): string {
+  const icons = info.icons;
+  if (!Array.isArray(icons)) return '';
+  for (const entry of icons) {
+    if (!isRecord(entry)) continue;
+    const src = safeIconSrc(entry.src);
+    if (src !== '') return src;
+  }
+  return '';
+}
+
+function serverFrom(url: URL, result: Record<string, unknown>): VerifiedServer {
+  const protocol = result.protocolVersion;
+  if (typeof protocol !== 'string') throw notMcp(url);
+  const info = isRecord(result.serverInfo) ? result.serverInfo : {};
+  const title = typeof info.title === 'string' ? info.title : '';
+  return {
+    server:
+      title !== ''
+        ? title
+        : typeof info.name === 'string'
+          ? info.name
+          : url.hostname,
+    version: typeof info.version === 'string' ? info.version : '',
+    protocol,
+    icon: iconOf(info),
+    tools: 0,
+    catalog: [],
+  };
+}
+
+async function initialize(
+  url: URL,
+  auth: ConnectorAuth,
+  signal: AbortSignal,
+  version: string,
+): Promise<{ session: string | null; server: VerifiedServer }> {
+  const res = await frame(url, auth, {}, initializeBody(version), signal);
+  if (res.status === 401 || res.status === 403) {
+    await discard(res);
+    throw new ConnectorUnauthorized(
+      auth.kind === 'none'
+        ? `${url.hostname} requires authorization.`
+        : `${url.hostname} rejected that credential.`,
+      400,
+    );
+  }
+  if (res.status === 404 || res.status === 405) {
+    await discard(res);
+    throw refused(
+      `${url.hostname} did not accept an MCP initialize over HTTP POST. ` +
+        'If it is a legacy SSE server, Metro cannot verify it yet.',
+    );
+  }
+  if (!res.ok) {
+    await discard(res);
+    throw notMcp(url);
+  }
+  const result = await resultOrNull(res);
+  if (result === null) throw notMcp(url);
+  return {
+    session: res.headers.get('mcp-session-id'),
+    server: serverFrom(url, result),
+  };
+}
+
+function sessionHeaders(
+  session: string | null,
+  version: string,
+): Record<string, string> {
+  const headers: Record<string, string> = {
+    'mcp-protocol-version': version,
+  };
+  if (session !== null && session !== '') headers['mcp-session-id'] = session;
+  return headers;
+}
+
+async function announce(
+  url: URL,
+  auth: ConnectorAuth,
+  headers: Record<string, string>,
+  signal: AbortSignal,
+): Promise<void> {
+  const res = await frame(
+    url,
+    auth,
+    headers,
+    { jsonrpc: '2.0', method: 'notifications/initialized' },
+    signal,
+  );
+  await discard(res);
+}
+
+async function toolPage(
+  url: URL,
+  auth: ConnectorAuth,
+  headers: Record<string, string>,
+  signal: AbortSignal,
+  cursor: string,
+): Promise<Record<string, unknown> | null> {
+  const params = cursor === '' ? {} : { cursor };
+  const res = await frame(
+    url,
+    auth,
+    headers,
+    { jsonrpc: '2.0', id: 2, method: 'tools/list', params },
+    signal,
+  );
+  if (!res.ok) {
+    await discard(res);
+    return null;
+  }
+  return resultOrNull(res);
+}
+
+async function listTools(
+  url: URL,
+  auth: ConnectorAuth,
+  headers: Record<string, string>,
+  signal: AbortSignal,
+): Promise<ToolInfo[]> {
+  const tools: ToolInfo[] = [];
+  let cursor = '';
+  for (let page = 0; page < MAX_TOOL_PAGES; page += 1) {
+    const result = await toolPage(url, auth, headers, signal, cursor);
+    if (result === null) break;
+    tools.push(...toToolList(result.tools));
+    const next = result.nextCursor;
+    if (typeof next !== 'string' || next === '' || next === cursor) break;
+    cursor = next;
+  }
+  return tools;
+}
+
+async function terminate(
+  url: URL,
+  auth: ConnectorAuth,
+  headers: Record<string, string>,
+  signal: AbortSignal,
+): Promise<void> {
+  const res = await fetch(url, {
+    method: 'DELETE',
+    redirect: 'manual',
+    signal,
+    headers: { ...authHeaders(auth), ...headers },
+  });
+  await discard(res);
+}
+
+async function probeWith(
+  url: URL,
+  auth: ConnectorAuth,
+  version: string,
+): Promise<VerifiedServer> {
+  const signal = AbortSignal.timeout(PROBE_TIMEOUT_MS);
+  const { session, server } = await initialize(url, auth, signal, version);
+  const headers = sessionHeaders(session, server.protocol);
+  await announce(url, auth, headers, signal);
+  const catalog = await listTools(url, auth, headers, signal);
+  await terminate(url, auth, headers, signal).catch((err: unknown) => {
+    log.debug(
+      { host: url.hostname, err: errMsg(err) },
+      'connector-verify: the remote declined to end the session',
+    );
+  });
+  return { ...server, tools: catalog.length, catalog };
+}
+
+export async function verifyRemoteMcp(
+  url: URL,
+  auth: ConnectorAuth,
+): Promise<VerifiedServer> {
+  let last: unknown;
+  for (const version of PROTOCOL_VERSIONS) {
+    try {
+      return await probeWith(url, auth, version);
+    } catch (err) {
+      if (!(err instanceof ConnectorNotMcp)) throw err;
+      last = err;
+    }
+  }
+  throw last;
+}

package/runtime/node_modules/@metro-labs/mcp/src/daemon/control-api.ts

@@ -0,0 +1,64 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { ApiError } from './api-error.js';
+import { apiFailure, apiSession, cors, sendJson } from './api-http.js';
+import { errMsg, log } from './log.js';
+
+const STOP = '/api/stop';
+const RESTART = '/api/restart';
+const EXIT_DELAY_MS = 500;
+
+export interface ControlApiDeps {
+  authorize: (subject: string) => void;
+  restart: () => void;
+  stop: () => void;
+  served?: () => boolean;
+}
+
+interface Action {
+  run: () => void;
+  body: Record<string, boolean>;
+}
+
+const servedByCli = (): boolean => (process.env.METRO_CLI_BIN?.trim() ?? '') !== '';
+
+function actionFor(path: string, deps: ControlApiDeps): Action | null {
+  if (path === STOP) return { run: deps.stop, body: { stopping: true } };
+  if (path === RESTART) return { run: deps.restart, body: { restarting: true } };
+  return null;
+}
+
+export function handleControlRequest(req: IncomingMessage, res: ServerResponse, deps: ControlApiDeps): boolean {
+  const path = (req.url ?? '').split('?')[0] ?? '';
+  const action = actionFor(path, deps);
+  if (action === null) return false;
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204, cors(req)).end();
+    return true;
+  }
+  if (req.method !== 'POST') {
+    sendJson(req, res, 405, { error: 'method not allowed' });
+    return true;
+  }
+  Promise.resolve()
+    .then(async () => {
+      const session = await apiSession(req);
+      if (!session) throw new ApiError('unauthorized', 401);
+      deps.authorize(session.subject);
+      if (!(deps.served ?? servedByCli)())
+        throw new ApiError(
+          'this daemon was not started by metro serve, so nothing on the machine would bring it back: use the shell instead',
+          400,
+        );
+      log.info({ path, subject: session.subject }, 'control-api: requested from the page');
+      setTimeout(action.run, EXIT_DELAY_MS).unref();
+      sendJson(req, res, 200, action.body);
+    })
+    .catch((err: unknown) => {
+      if (err instanceof ApiError) apiFailure(req, res, err, 'control-api');
+      else {
+        log.warn({ err: errMsg(err) }, 'control-api: request failed');
+        if (!res.headersSent) sendJson(req, res, 500, { error: 'control api failed' });
+      }
+    });
+  return true;
+}

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

@@ -0,0 +1,29 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+export function applyMcpCors(
+  req: IncomingMessage,
+  res: ServerResponse,
+): void {
+  const origin = req.headers.origin;
+  res.setHeader(
+    'Access-Control-Allow-Origin',
+    origin !== undefined && origin !== '' ? origin : '*',
+  );
+  res.setHeader('Vary', 'Origin');
+  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+  res.setHeader(
+    'Access-Control-Allow-Headers',
+    'Authorization, Content-Type, Accept, Mcp-Session-Id, Mcp-Protocol-Version, Last-Event-ID',
+  );
+  res.setHeader('Access-Control-Expose-Headers', 'Mcp-Session-Id');
+  res.setHeader('Access-Control-Max-Age', '86400');
+}
+
+export function handleMcpPreflight(
+  req: IncomingMessage,
+  res: ServerResponse,
+): boolean {
+  if (req.method !== 'OPTIONS') return false;
+  res.writeHead(204).end();
+  return true;
+}

package/runtime/node_modules/@metro-labs/mcp/src/daemon/crash-guard.ts

@@ -0,0 +1,49 @@
+import { errMsg, log, logFatalSync } from './log.js';
+
+export type CrashKind = 'unhandledRejection' | 'uncaughtException';
+
+const seen: Record<CrashKind, number> = {
+  unhandledRejection: 0,
+  uncaughtException: 0,
+};
+
+let ready = false;
+let installed = false;
+
+export function markDaemonReady(): void {
+  ready = true;
+}
+
+export function crashCount(kind: CrashKind): number {
+  return seen[kind];
+}
+
+function fields(kind: CrashKind, err: unknown): Record<string, unknown> {
+  return {
+    crash: kind,
+    seen: seen[kind],
+    err: errMsg(err),
+    errType: err instanceof Error ? err.name : typeof err,
+    stack: err instanceof Error ? err.stack : undefined,
+  };
+}
+
+function reportCrash(kind: CrashKind, err: unknown): void {
+  seen[kind] += 1;
+  if (!ready) {
+    logFatalSync(fields(kind, err), 'daemon: failed before it was ready');
+    process.exit(1);
+  }
+  log.error(fields(kind, err), 'daemon: kept running through a crash');
+}
+
+export function installCrashGuard(): void {
+  if (installed) return;
+  installed = true;
+  process.on('unhandledRejection', (reason: unknown) => {
+    reportCrash('unhandledRejection', reason);
+  });
+  process.on('uncaughtException', (err: unknown) => {
+    reportCrash('uncaughtException', err);
+  });
+}

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

@@ -0,0 +1,120 @@
+import { randomBytes } from 'node:crypto';
+import { Line } from '../stations/lines.js';
+
+export { userSelf, daemonSelf } from './identity.js';
+
+export type StructuredEvent =
+  | { type: 'msg' }
+  | { type: 'react'; emoji?: string; targetId?: string }
+  | { type: 'edit'; targetId?: string }
+  | { type: 'delete'; targetId?: string }
+  | { type: 'reply'; replyTo?: string }
+  | { type: 'system'; source?: string; eventName?: string };
+
+export interface MetroEvent {
+  id: string;
+  ts: string;
+  station: string;
+  line: Line;
+  lineName?: string;
+  from: Line;
+  fromName?: string;
+  fromDisplayName?: string;
+  to: Line;
+  text?: string;
+  messageId?: string;
+  replyTo?: string;
+  isPrivate?: boolean;
+  mentionsSelf?: boolean;
+  replyToSelf?: boolean;
+  payload?: unknown;
+  display?: string;
+  event?: StructuredEvent;
+  agent?: string;
+  seq?: number;
+}
+
+function isExternalWebhook(e: MetroEvent): boolean {
+  return e.station === 'webhook' && !Line.isLocal(e.from);
+}
+
+function webhookEventName(e: MetroEvent): string | undefined {
+  const headers = (e.payload as { headers?: Record<string, string> } | undefined)
+    ?.headers;
+  return headers?.['x-github-event'] ?? headers?.['x-intercom-topic'];
+}
+
+export function classifyEvent(e: MetroEvent): StructuredEvent {
+  if (isExternalWebhook(e)) {
+    return {
+      type: 'system',
+      source: 'webhook',
+      eventName: webhookEventName(e),
+    };
+  }
+  const emoji =
+    (e.payload as { emoji?: string } | undefined)?.emoji ??
+    e.text?.match(/^\[react (.+)\]$/)?.[1];
+  if (emoji) return { type: 'react', emoji, targetId: e.replyTo };
+  if (e.replyTo) return { type: 'reply', replyTo: e.replyTo };
+  return { type: 'msg' };
+}
+
+export function formatDisplay(e: MetroEvent): string {
+  const headerFor = (icon: string, parts: (string | undefined)[]): string =>
+    `**${icon} ${parts.filter(Boolean).join(' · ')}**`;
+  const body = e.text ?? '';
+  if (isExternalWebhook(e)) {
+    const ev = webhookEventName(e);
+    return `${headerFor('🪝', ['webhook', e.lineName, ev])}\n> ${body}`;
+  }
+  if (Line.isLocal(e.from)) {
+    return `${headerFor('📤', [e.station, '→', e.fromName ?? e.to])}\n> ${body}`;
+  }
+  return `${headerFor('📩', [e.station, e.fromName ?? e.from, e.lineName])}\n> ${body}`;
+}
+
+export const mintId = (): string =>
+  `msg_${randomBytes(6).toString('base64url')}`;
+
+export type BusListener = (event: MetroEvent, busSeq: number) => void;
+
+export interface BufferedEvent {
+  busSeq: number;
+  event: MetroEvent;
+}
+
+const BUS_BUFFER_MAX = 500;
+
+const listeners = new Set<BusListener>();
+const buffer: BufferedEvent[] = [];
+let busSeq = 0;
+
+export function publishEvent(event: MetroEvent): void {
+  busSeq += 1;
+  const seq = busSeq;
+  buffer.push({ busSeq: seq, event });
+  if (buffer.length > BUS_BUFFER_MAX) buffer.shift();
+  for (const fn of [...listeners]) {
+    try {
+      fn(event, seq);
+    } catch (err) {
+      console.error('[metro-bus] listener threw for busSeq', seq, err);
+    }
+  }
+}
+
+export function currentBusSeq(): number {
+  return busSeq;
+}
+
+export function bufferedSince(afterBusSeq: number): BufferedEvent[] {
+  return buffer.filter((b) => b.busSeq > afterBusSeq);
+}
+
+export function subscribeEvents(fn: BusListener): () => void {
+  listeners.add(fn);
+  return () => {
+    listeners.delete(fn);
+  };
+}