@stage-labs/metro 0.1.0-beta.2 → 0.1.0-beta.21

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

@@ -0,0 +1,100 @@
+export const TOOL_KINDS = ['read', 'write'] as const;
+
+export type ToolKind = (typeof TOOL_KINDS)[number];
+
+export interface ToolInfo {
+  name: string;
+  title: string;
+  description: string;
+  kind: ToolKind;
+  annotated: boolean;
+  destructive: boolean;
+  idempotent: boolean;
+  openWorld: boolean;
+}
+
+const MAX_TOOLS = 500;
+const MAX_DESCRIPTION = 400;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+const str = (value: unknown, cap: number): string =>
+  typeof value === 'string' ? value.slice(0, cap) : '';
+
+const flag = (value: unknown, fallback: boolean): boolean =>
+  typeof value === 'boolean' ? value : fallback;
+
+export function classifyTool(annotations: unknown): ToolKind {
+  return isRecord(annotations) && annotations.readOnlyHint === true
+    ? 'read'
+    : 'write';
+}
+
+export function isDestructive(annotations: unknown): boolean {
+  if (!isRecord(annotations)) return true;
+  if (annotations.readOnlyHint === true) return false;
+  return annotations.destructiveHint !== false;
+}
+
+export function toToolInfo(raw: unknown): ToolInfo | null {
+  if (!isRecord(raw)) return null;
+  const name = str(raw.name, 200);
+  if (name === '') return null;
+  const annotations = isRecord(raw.annotations) ? raw.annotations : undefined;
+  return {
+    name,
+    title: str(annotations?.title ?? raw.title, 200),
+    description: str(raw.description, MAX_DESCRIPTION),
+    kind: classifyTool(raw.annotations),
+    annotated: annotations !== undefined,
+    destructive: isDestructive(raw.annotations),
+    idempotent: flag(annotations?.idempotentHint, false),
+    openWorld: flag(annotations?.openWorldHint, true),
+  };
+}
+
+export function toToolList(raw: unknown): ToolInfo[] {
+  if (!Array.isArray(raw)) return [];
+  const out: ToolInfo[] = [];
+  for (const entry of raw) {
+    if (out.length >= MAX_TOOLS) break;
+    const tool = toToolInfo(entry);
+    if (tool !== null) out.push(tool);
+  }
+  return out;
+}
+
+export function toStoredTool(raw: unknown): ToolInfo | null {
+  if (!isRecord(raw)) return null;
+  const name = str(raw.name, 200);
+  if (name === '') return null;
+  return {
+    name,
+    title: str(raw.title, 200),
+    description: str(raw.description, MAX_DESCRIPTION),
+    kind: raw.kind === 'read' ? 'read' : 'write',
+    annotated: raw.annotated === true,
+    destructive: raw.destructive !== false,
+    idempotent: raw.idempotent === true,
+    openWorld: raw.openWorld !== false,
+  };
+}
+
+export function readStoredTools(raw: unknown): ToolInfo[] {
+  if (!Array.isArray(raw)) return [];
+  const out: ToolInfo[] = [];
+  for (const entry of raw) {
+    if (out.length >= MAX_TOOLS) break;
+    const tool = toStoredTool(entry);
+    if (tool !== null) out.push(tool);
+  }
+  return out;
+}
+
+export function countByKind(tools: ToolInfo[]): Record<ToolKind, number> {
+  const counts: Record<ToolKind, number> = { read: 0, write: 0 };
+  for (const tool of tools) counts[tool.kind] += 1;
+  return counts;
+}

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

@@ -0,0 +1,57 @@
+import { ApiError } from './api-error.js';
+
+export class ConnectorVerifyError extends ApiError {}
+
+export class ConnectorUnauthorized extends ConnectorVerifyError {}
+
+export class ConnectorNotMcp extends ConnectorVerifyError {}
+
+export const POLICY_MESSAGE =
+  'Metro connects from its own server, so it cannot reach a URL on your machine. localhost and private addresses are not usable as connectors.';
+
+const IPV4 = /^\d{1,3}(?:\.\d{1,3}){3}$/;
+const PRIVATE_SUFFIX = /(?:^|\.)(?:localhost|local|internal|flycast)$/;
+
+export function refused(message: string): ConnectorVerifyError {
+  return new ConnectorVerifyError(message, 400);
+}
+
+function hostAllowed(host: string): boolean {
+  if (host === '' || host.startsWith('[')) return false;
+  if (IPV4.test(host) || !host.includes('.')) return false;
+  return !PRIVATE_SUFFIX.test(host);
+}
+
+export function parseConnectorUrl(raw: unknown): URL {
+  const text = typeof raw === 'string' ? raw.trim() : '';
+  if (text === '') throw refused('a connector url is required');
+  let url: URL;
+  try {
+    url = new URL(text);
+  } catch {
+    throw refused('that is not a valid url');
+  }
+  if (url.protocol !== 'https:')
+    throw refused('a connector url must start with https://');
+  if (url.username !== '' || url.password !== '')
+    throw refused('a connector url must not carry a user:password');
+  if (url.hash !== '')
+    throw refused('a connector url must not carry a #fragment');
+  if (!hostAllowed(url.hostname.toLowerCase())) throw refused(POLICY_MESSAGE);
+  return url;
+}
+
+export function connectorUrlText(url: URL): string {
+  const text = url.toString();
+  if (url.pathname !== '/' || url.search !== '') return text;
+  return text.endsWith('/') ? text.slice(0, -1) : text;
+}
+
+export function safeIconSrc(raw: unknown): string {
+  if (typeof raw !== 'string' || raw === '') return '';
+  try {
+    return new URL(raw).protocol === 'https:' ? raw.slice(0, 500) : '';
+  } catch {
+    return '';
+  }
+}

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

@@ -0,0 +1,333 @@
+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';
+
+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';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+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/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,117 @@
+import { randomBytes } from 'node:crypto';
+import { Line } from '../stations/lines.js';
+
+export { userSelf, daemonSelf, selfLine } 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;
+  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;
+}
+
+export 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);
+  };
+}