@adtl/gateway 0.2.0 → 0.3.0

package/src/gateway.ts

@@ -5,6 +5,11 @@
  * tools/list  → every upstream's tools, renamed <upstream>__<tool>
  * tools/call  → request interceptors (adtl.policy) → upstream → response
  *               interceptors (adtl.label) → agent
+ * prompts/*   → like tools: renamed <upstream>__<prompt>, results labeled
+ * resources/* → URIs pass through unchanged and are routed to the upstream
+ *               that lists them (or whose template matches). Results are
+ *               labeled. A URI more than one upstream could serve is refused,
+ *               since ADTL could not tell which server to label it as.
  *
  * When a call is stopped, the agent receives a normal tool result with
  * `isError: true` explaining why, so the model can tell the user.
@@ -20,10 +25,24 @@
 import { randomUUID } from "node:crypto";
 import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { UriTemplate } from "@modelcontextprotocol/sdk/shared/uriTemplate.js";
 import {
   CallToolRequestSchema,
+  ErrorCode,
+  GetPromptRequestSchema,
+  ListPromptsRequestSchema,
+  ListResourcesRequestSchema,
+  ListResourceTemplatesRequestSchema,
   ListToolsRequestSchema,
+  McpError,
+  ReadResourceRequestSchema,
   type CallToolResult,
+  type GetPromptResult,
+  type Prompt,
+  type ReadResourceResult,
+  type Resource,
+  type ResourceTemplate,
+  type ServerCapabilities,
   type Tool,
 } from "@modelcontextprotocol/sdk/types.js";
 import type { InvocationContext } from "@adtl/interceptors";
@@ -32,7 +51,7 @@ import type { AuditEntry, AuditSink } from "./audit.js";
 import { TOOL_SEPARATOR } from "./config.js";
 import type { Blocked, ChainOutcome, InterceptorInvoker } from "./invoker.js";
 
-export const GATEWAY_VERSION = "0.2.0";
+export const GATEWAY_VERSION = "0.3.0";
 
 /** `_meta` key on gateway-generated error results describing why a call was stopped. */
 export const GATEWAY_DECISION_KEY = "adtl/gateway";
@@ -43,6 +62,21 @@ interface Route {
   annotations?: Tool["annotations"];
 }
 
+interface PromptRoute {
+  upstream: string;
+  prompt: string;
+}
+
+interface TemplateRoute {
+  upstream: string;
+  template: UriTemplate;
+}
+
+interface Page<T> {
+  items: T[];
+  nextCursor?: string | undefined;
+}
+
 export interface GatewayLogger {
   info(msg: string): void;
   warn(msg: string): void;
@@ -110,6 +144,10 @@ export class AdtlGateway {
   private readonly log: GatewayLogger;
   private readonly approvals: ApprovalBroker | undefined;
   private routes = new Map<string, Route>();
+  private promptRoutes = new Map<string, PromptRoute>();
+  /** Resource URI → the upstreams that list it. */
+  private resourceRoutes = new Map<string, Set<string>>();
+  private templateRoutes: TemplateRoute[] = [];
 
   constructor(opts: AdtlGatewayOptions) {
     this.upstreams = opts.upstreams;
@@ -122,10 +160,15 @@ export class AdtlGateway {
 
   /** The downstream MCP server the agent connects to. */
   createServer(): Server {
+    // Offer resources and prompts only if some upstream does (the SDK refuses handlers for undeclared capabilities).
+    const offers = (c: "resources" | "prompts") => [...this.upstreams.values()].some((u) => u.getServerCapabilities()?.[c]);
+    const capabilities: ServerCapabilities = { tools: {} };
+    if (offers("resources")) capabilities.resources = {};
+    if (offers("prompts")) capabilities.prompts = {};
     const server = new Server(
       { name: "adtl-gateway", version: GATEWAY_VERSION },
       {
-        capabilities: { tools: {} },
+        capabilities,
         instructions:
           "Tools from several MCP servers, named <server>__<tool>. ADTL checks each call against trust labels; " +
           "if a call is stopped, the result explains why.",
@@ -141,32 +184,214 @@ export class AdtlGateway {
               extra.sendNotification({ method: "notifications/progress", params: { progressToken, progress, message } });
       return this.callTool(req.params.name, req.params.arguments ?? {}, progress ? { progress } : {});
     });
+    if (capabilities.resources) {
+      server.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources: await this.listResources() }));
+      server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
+        resourceTemplates: await this.listResourceTemplates(),
+      }));
+      server.setRequestHandler(ReadResourceRequestSchema, async (req) => this.readResource(req.params.uri));
+    }
+    if (capabilities.prompts) {
+      server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: await this.listPrompts() }));
+      server.setRequestHandler(GetPromptRequestSchema, async (req) => this.getPrompt(req.params.name, req.params.arguments));
+    }
     return server;
   }
 
-  async listTools(): Promise<Tool[]> {
-    const routes = new Map<string, Route>();
-    const tools: Tool[] = [];
+  /** Every upstream's items from one list method, following cursors. Upstreams that fail are skipped with a warning. */
+  private async listAll<T>(
+    method: string,
+    capability: "tools" | "resources" | "prompts",
+    page: (client: Client, cursor?: string) => Promise<Page<T>>,
+  ): Promise<{ upstream: string; item: T }[]> {
+    const out: { upstream: string; item: T }[] = [];
     for (const [upstream, client] of this.upstreams) {
+      if (capability !== "tools" && !client.getServerCapabilities()?.[capability]) continue;
       let cursor: string | undefined;
       try {
         do {
-          const page = await client.listTools(cursor ? { cursor } : {});
-          for (const t of page.tools) {
-            const name = `${upstream}${TOOL_SEPARATOR}${t.name}`;
-            routes.set(name, { upstream, tool: t.name, ...(t.annotations ? { annotations: t.annotations } : {}) });
-            tools.push({ ...t, name });
-          }
-          cursor = page.nextCursor;
+          const p = await page(client, cursor);
+          for (const item of p.items) out.push({ upstream, item });
+          cursor = p.nextCursor;
         } while (cursor);
       } catch (err) {
-        this.log.warn(`tools/list failed for ${upstream}: ${(err as Error).message}`);
+        this.log.warn(`${method} failed for ${upstream}: ${(err as Error).message}`);
       }
     }
+    return out;
+  }
+
+  async listTools(): Promise<Tool[]> {
+    const all = await this.listAll("tools/list", "tools", async (c, cursor) => {
+      const p = await c.listTools(cursor ? { cursor } : {});
+      return { items: p.tools, nextCursor: p.nextCursor };
+    });
+    const routes = new Map<string, Route>();
+    const tools = all.map(({ upstream, item: t }) => {
+      const name = `${upstream}${TOOL_SEPARATOR}${t.name}`;
+      routes.set(name, { upstream, tool: t.name, ...(t.annotations ? { annotations: t.annotations } : {}) });
+      return { ...t, name };
+    });
     this.routes = routes;
     return tools;
   }
 
+  async listPrompts(): Promise<Prompt[]> {
+    const all = await this.listAll("prompts/list", "prompts", async (c, cursor) => {
+      const p = await c.listPrompts(cursor ? { cursor } : {});
+      return { items: p.prompts, nextCursor: p.nextCursor };
+    });
+    const routes = new Map<string, PromptRoute>();
+    const prompts = all.map(({ upstream, item: p }) => {
+      const name = `${upstream}${TOOL_SEPARATOR}${p.name}`;
+      routes.set(name, { upstream, prompt: p.name });
+      return { ...p, name };
+    });
+    this.promptRoutes = routes;
+    return prompts;
+  }
+
+  async listResources(): Promise<Resource[]> {
+    const all = await this.listAll("resources/list", "resources", async (c, cursor) => {
+      const p = await c.listResources(cursor ? { cursor } : {});
+      return { items: p.resources, nextCursor: p.nextCursor };
+    });
+    const routes = new Map<string, Set<string>>();
+    for (const { upstream, item } of all) {
+      const ups = routes.get(item.uri) ?? new Set<string>();
+      ups.add(upstream);
+      routes.set(item.uri, ups);
+    }
+    for (const [uri, ups] of routes) {
+      if (ups.size > 1) this.log.warn(`resource ${uri} is offered by ${[...ups].join(", ")}; reading it will be refused`);
+    }
+    this.resourceRoutes = routes;
+    return all.map((a) => a.item);
+  }
+
+  async listResourceTemplates(): Promise<ResourceTemplate[]> {
+    const all = await this.listAll("resources/templates/list", "resources", async (c, cursor) => {
+      const p = await c.listResourceTemplates(cursor ? { cursor } : {});
+      return { items: p.resourceTemplates, nextCursor: p.nextCursor };
+    });
+    const routes: TemplateRoute[] = [];
+    for (const { upstream, item } of all) {
+      try {
+        routes.push({ upstream, template: new UriTemplate(item.uriTemplate) });
+      } catch (err) {
+        this.log.warn(`ignoring resource template ${item.uriTemplate} from ${upstream}: ${(err as Error).message}`);
+      }
+    }
+    this.templateRoutes = routes;
+    return all.map((a) => a.item);
+  }
+
+  /** The one upstream that serves `uri`: an exact listing wins, then template matches. */
+  private async resourceUpstream(uri: string): Promise<string> {
+    if (!this.resourceRoutes.has(uri)) await this.listResources();
+    let candidates = [...(this.resourceRoutes.get(uri) ?? [])];
+    if (candidates.length === 0) {
+      if (this.templateRoutes.length === 0) await this.listResourceTemplates();
+      candidates = [...new Set(this.templateRoutes.filter((t) => t.template.match(uri) !== null).map((t) => t.upstream))];
+    }
+    if (candidates.length === 0) throw new McpError(ErrorCode.InvalidParams, `Unknown resource: ${uri}`);
+    if (candidates.length > 1) {
+      throw new McpError(
+        ErrorCode.InvalidParams,
+        `Resource ${uri} could come from more than one server (${candidates.join(", ")}). ` +
+          `ADTL can't tell which server to label it as, so it was not read.`,
+      );
+    }
+    return candidates[0]!;
+  }
+
+  async readResource(uri: string): Promise<ReadResourceResult> {
+    const upstream = await this.resourceUpstream(uri);
+    const client = this.upstreams.get(upstream)!;
+    return this.forwardLabeled("resources/read", upstream, { resource: uri }, { uri }, (params) =>
+      client.readResource(params as { uri: string }),
+    );
+  }
+
+  async getPrompt(name: string, args?: Record<string, string>): Promise<GetPromptResult> {
+    let route = this.promptRoutes.get(name);
+    if (!route) {
+      await this.listPrompts();
+      route = this.promptRoutes.get(name);
+    }
+    if (!route) throw new McpError(ErrorCode.InvalidParams, `Unknown prompt: ${name}`);
+    const client = this.upstreams.get(route.upstream)!;
+    return this.forwardLabeled(
+      "prompts/get",
+      route.upstream,
+      { prompt: route.prompt },
+      { name: route.prompt, ...(args ? { arguments: args } : {}) },
+      (params) => client.getPrompt(params as { name: string; arguments?: Record<string, string> }),
+    );
+  }
+
+  /**
+   * Forward a resources/read or prompts/get request through the interceptor
+   * chain: request interceptors → upstream → response interceptors (adtl.label).
+   * These requests have no tool result to carry an error, so a stopped request
+   * becomes a JSON-RPC error.
+   */
+  private async forwardLabeled<R extends object>(
+    event: "resources/read" | "prompts/get",
+    upstream: string,
+    target: { resource: string } | { prompt: string },
+    params: Record<string, unknown>,
+    send: (params: Record<string, unknown>) => Promise<R>,
+  ): Promise<R> {
+    const started = performance.now();
+    const context: InvocationContext = {
+      sessionId: this.sessionId,
+      timestamp: new Date().toISOString(),
+      principal: { type: "anonymous" },
+    };
+    const config = { server: upstream };
+    const audit = this.invoker.modeOverride === "audit" ? { mode: "audit" as const } : {};
+    const finish = (entry: Pick<AuditEntry, "outcome"> & Partial<AuditEntry>) =>
+      this.audit?.write({
+        ts: context.timestamp!,
+        sessionId: this.sessionId,
+        event,
+        server: upstream,
+        ...target,
+        ...entry,
+        durationMs: Math.round(performance.now() - started),
+      });
+    const what = "resource" in target ? `resource ${target.resource}` : `prompt ${upstream}${TOOL_SEPARATOR}${target.prompt}`;
+
+    const req = await this.invoker.runRequest({ event, payload: { method: event, params }, config, context });
+    if (req.blocked) {
+      finish({ outcome: "blocked", decision: req.blocked.decision, reason: req.blocked.reason, warnings: req.warnings });
+      this.log.info(`${req.blocked.decision} ${what}: ${req.blocked.reason}`);
+      throw new McpError(ErrorCode.InvalidRequest, `ADTL blocked this request: ${req.blocked.reason}`);
+    }
+    const forwarded = (req.payload as { params: Record<string, unknown> }).params;
+
+    let result: R;
+    try {
+      result = await send(forwarded);
+    } catch (err) {
+      finish({ outcome: "upstream_error", reason: (err as Error).message, ...audit, warnings: req.warnings });
+      throw err;
+    }
+
+    const res = await this.invoker.runResponse({ event, payload: { method: event, params: forwarded, result }, config, context });
+    const warnings = [...req.warnings, ...res.warnings];
+    if (res.blocked) {
+      // Fail closed: unlabeled content must not reach the agent.
+      finish({ outcome: "blocked", decision: res.blocked.decision, reason: res.blocked.reason, warnings });
+      this.log.warn(`${what} withheld: ${res.blocked.reason}`);
+      throw new McpError(ErrorCode.InternalError, `ADTL could not label this content, so it was withheld: ${res.blocked.reason}`);
+    }
+    const label = infoOf(res, "adtl.label");
+    finish({ outcome: "forwarded", ...audit, label: label.label, sessionLabel: label.sessionLabel, warnings });
+    return (res.payload as { result: R }).result;
+  }
+
   async callTool(name: string, args: Record<string, unknown>, opts: CallOptions = {}): Promise<CallToolResult> {
     const started = performance.now();
     let route = this.routes.get(name);

package/src/index.ts

@@ -6,3 +6,4 @@ export * from "./ntfy.js";
 export * from "./email.js";
 export * from "./gateway.js";
 export * from "./startup.js";
+export * from "./init/index.js";

package/src/init/index.ts

@@ -0,0 +1,3 @@
+export { PRESETS, choosePreset, type Preset } from "./presets.js";
+export { mergeIntoDocument, ruleFromHints, suggest, type MergeReport, type ServerScan, type ServerSuggestion, type ToolSuggestion } from "./suggest.js";
+export { runInit, type InitOptions, type InitResult } from "./run.js";

package/src/init/presets.ts

@@ -0,0 +1,64 @@
+/**
+ * Presets for well-known MCP servers, used by `adtl-gateway init`.
+ *
+ * A preset says what a server's reads and writes mean, and the server's own
+ * `readOnlyHint` decides which tools are reads. That keeps a preset correct as
+ * the server adds tools (the GitHub server has about 90 and adds more).
+ *
+ * Presets are only a starting point: `init` writes one explicit line per tool
+ * into adtl.yaml, and the gateway owner reviews and edits them.
+ */
+import type { ToolRule } from "@adtl/labels";
+
+export interface Preset {
+  id: string;
+  /** `serverInfo.name` values the server reports at initialize. */
+  serverNames: string[];
+  /** Server defaults: resources, prompts, and tools added after `init` ran. */
+  defaults: ToolRule;
+  /** Tools with `readOnlyHint: true`. */
+  read: ToolRule;
+  /** All other tools. Fields left out fall back to `defaults`. */
+  write: ToolRule;
+  /** Exact per-tool overrides. */
+  tools?: Record<string, ToolRule>;
+  /** One line written above the server in adtl.yaml. */
+  note: string;
+}
+
+export const PRESETS: Preset[] = [
+  {
+    id: "github",
+    serverNames: ["github-mcp-server"],
+    // Issues, PRs, comments and code can be written by anyone who can open an issue.
+    defaults: { integrity: "untrusted", confidentiality: "private", egress: "public" },
+    read: { integrity: "untrusted", confidentiality: "private", egress: "internal" },
+    write: { egress: "public" },
+    note: "preset github: content is untrusted (anyone can write issues), private repos make it private; writes are public",
+  },
+  {
+    id: "filesystem",
+    serverNames: ["secure-filesystem-server"],
+    defaults: { integrity: "trusted", confidentiality: "private", egress: "internal" },
+    read: { integrity: "trusted", confidentiality: "private", egress: "none" },
+    write: { egress: "internal" },
+    note: "preset filesystem: files are trusted; set integrity: untrusted if these folders hold downloads or cloned repos",
+  },
+  {
+    id: "fetch",
+    serverNames: ["mcp-fetch"],
+    // The URL itself can carry data out, so even a read is external egress.
+    defaults: { integrity: "untrusted", confidentiality: "public", egress: "external" },
+    read: { integrity: "untrusted", confidentiality: "public", egress: "external" },
+    write: { integrity: "untrusted", confidentiality: "public", egress: "external" },
+    note: "preset fetch: web pages are untrusted; a fetched URL can carry data out, so fetch is external egress",
+  },
+];
+
+/** The preset for an upstream: by the name the server reports, then by the upstream id. */
+export function choosePreset(upstreamId: string, serverName: string | undefined, presets = PRESETS): Preset | undefined {
+  return (
+    (serverName !== undefined ? presets.find((p) => p.serverNames.includes(serverName)) : undefined) ??
+    presets.find((p) => p.id === upstreamId)
+  );
+}

package/src/init/run.ts

@@ -0,0 +1,79 @@
+/**
+ * `adtl-gateway init`: connect to every upstream in adtl.yaml, list its
+ * tools, and draft a labeling rule for each tool not configured yet.
+ *
+ * Without `write`, the updated file is only returned (the CLI prints it).
+ * With `write`, the original is kept as `<file>.bak` and the file is updated
+ * in place. Existing entries and comments are never changed.
+ */
+import { readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { parseDocument } from "yaml";
+import { expandUpstream } from "../config.js";
+import { connectUpstream, loadGatewayConfig } from "../startup.js";
+import { mergeIntoDocument, suggest, type MergeReport, type ServerScan } from "./suggest.js";
+
+export interface InitOptions {
+  path: string;
+  write?: boolean;
+  env?: NodeJS.ProcessEnv;
+}
+
+export interface InitResult {
+  /** The updated adtl.yaml. */
+  text: string;
+  reports: MergeReport[];
+  /** Upstreams that could not be scanned; left untouched in the file. */
+  failed: { id: string; error: string }[];
+}
+
+async function listAllTools(client: Client): Promise<Tool[]> {
+  const tools: Tool[] = [];
+  let cursor: string | undefined;
+  do {
+    const page = await client.listTools(cursor ? { cursor } : {});
+    tools.push(...page.tools);
+    cursor = page.nextCursor;
+  } while (cursor);
+  return tools;
+}
+
+async function scan(id: string, connect: () => Promise<Client>): Promise<ServerScan> {
+  const client = await connect();
+  try {
+    const name = client.getServerVersion()?.name;
+    const tools = await listAllTools(client);
+    return { id, ...(name ? { serverName: name } : {}), tools: tools.map((t) => ({ name: t.name, annotations: t.annotations })) };
+  } finally {
+    await client.close().catch(() => undefined);
+  }
+}
+
+export async function runInit(opts: InitOptions): Promise<InitResult> {
+  const env = opts.env ?? process.env;
+  const loaded = await loadGatewayConfig(opts.path);
+  const baseDir = dirname(loaded.path);
+  const original = await readFile(loaded.path, "utf8");
+
+  const ids = Object.keys(loaded.gateway.upstreams);
+  const settled = await Promise.allSettled(
+    ids.map((id) => scan(id, () => connectUpstream(id, expandUpstream(id, loaded.gateway.upstreams[id]!, env), baseDir))),
+  );
+  const scans: ServerScan[] = [];
+  const failed: InitResult["failed"] = [];
+  settled.forEach((s, i) => {
+    if (s.status === "fulfilled") scans.push(s.value);
+    else failed.push({ id: ids[i]!, error: (s.reason as Error).message });
+  });
+
+  const doc = parseDocument(original);
+  const reports = mergeIntoDocument(doc, scans.map((s) => suggest(s)));
+  const text = doc.toString();
+  if (opts.write && text !== original) {
+    await writeFile(`${loaded.path}.bak`, original, "utf8");
+    await writeFile(loaded.path, text, "utf8");
+  }
+  return { text, reports, failed };
+}

package/src/init/suggest.ts

@@ -0,0 +1,127 @@
+/**
+ * Draft ADTL rules for an upstream's tools, and merge them into adtl.yaml.
+ *
+ * Without a preset, rules come from the MCP tool annotations. Those are the
+ * server's own claims, so they only decide egress; integrity is always
+ * untrusted and confidentiality private until the owner says otherwise.
+ * Missing hints take the MCP spec defaults (readOnlyHint false, openWorldHint true).
+ *
+ * Merging never changes an entry that is already in the file: the owner's
+ * choices win, and `init` can be re-run to pick up new tools.
+ */
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { ToolRule } from "@adtl/labels";
+import { isMap, isScalar, type Document, type YAMLMap } from "yaml";
+import { choosePreset, PRESETS, type Preset } from "./presets.js";
+
+export interface ServerScan {
+  /** Upstream id in gateway.upstreams. */
+  id: string;
+  /** `serverInfo.name` the server reported. */
+  serverName?: string;
+  tools: Pick<Tool, "name" | "annotations">[];
+}
+
+export interface ToolSuggestion {
+  name: string;
+  rule: ToolRule;
+  /** Short reason, written as a comment next to the rule. */
+  why: string;
+}
+
+export interface ServerSuggestion {
+  id: string;
+  preset?: Preset;
+  defaults: ToolRule;
+  tools: ToolSuggestion[];
+}
+
+const UNKNOWN_DEFAULTS: ToolRule = { integrity: "untrusted", confidentiality: "private" };
+
+/** A rule from the tool's MCP annotations alone. */
+export function ruleFromHints(annotations: Tool["annotations"]): Omit<ToolSuggestion, "name"> {
+  const readOnly = annotations?.readOnlyHint === true;
+  const openWorld = annotations?.openWorldHint !== false;
+  const egress = readOnly ? (openWorld ? "external" : "none") : openWorld ? "public" : "internal";
+  const why = `hints: ${readOnly ? "read-only" : "writes"}, ${openWorld ? "open world" : "closed world"} (review)`;
+  return { rule: { integrity: "untrusted", confidentiality: "private", egress }, why };
+}
+
+export function suggest(scan: ServerScan, presets = PRESETS): ServerSuggestion {
+  const preset = choosePreset(scan.id, scan.serverName, presets);
+  const tools = scan.tools.map(({ name, annotations }): ToolSuggestion => {
+    if (!preset) return { name, ...ruleFromHints(annotations) };
+    const override = preset.tools?.[name];
+    if (override) return { name, rule: override, why: `preset ${preset.id}` };
+    const read = annotations?.readOnlyHint === true;
+    return { name, rule: read ? preset.read : preset.write, why: `preset ${preset.id}: ${read ? "read" : "write"}` };
+  });
+  return { id: scan.id, ...(preset ? { preset } : {}), defaults: preset?.defaults ?? UNKNOWN_DEFAULTS, tools };
+}
+
+export interface MergeReport {
+  id: string;
+  preset?: string;
+  added: string[];
+  /** Tools already configured; left as they were. */
+  kept: string[];
+  /** Configured tools the server no longer offers. Left in place, reported only. */
+  stale: string[];
+  addedDefaults: boolean;
+}
+
+function mapAt(doc: Document, parent: YAMLMap, key: string, commentBefore?: string): YAMLMap {
+  const existing = parent.get(key, true);
+  if (isMap(existing)) return existing;
+  const map = doc.createNode({}) as YAMLMap;
+  const k = doc.createNode(key);
+  if (commentBefore && isScalar(k)) k.commentBefore = ` ${commentBefore}`;
+  parent.add(doc.createPair(k, map));
+  return map;
+}
+
+/** Add the suggestions to the document's `servers:` section, keeping every existing entry. */
+export function mergeIntoDocument(doc: Document, suggestions: ServerSuggestion[]): MergeReport[] {
+  let servers = doc.get("servers", true);
+  if (!isMap(servers)) {
+    servers = doc.createNode({}) as YAMLMap;
+    // Put servers: first, ahead of policy: and gateway:.
+    const root = doc.contents;
+    if (isMap(root)) root.items.unshift(doc.createPair("servers", servers));
+    else doc.contents = doc.createNode({ servers }) as never;
+  }
+  const serversMap = servers as YAMLMap;
+
+  return suggestions.map((s) => {
+    const report: MergeReport = { id: s.id, added: [], kept: [], stale: [], addedDefaults: false };
+    if (s.preset) report.preset = s.preset.id;
+    const isNew = !serversMap.has(s.id);
+    const server = mapAt(doc, serversMap, s.id, isNew ? (s.preset?.note ?? "from MCP tool hints: review every line") : undefined);
+
+    if (!server.has("defaults")) {
+      const d = doc.createNode(s.defaults, { flow: true });
+      d.comment = " resources, prompts, and tools not listed below";
+      server.items.unshift(doc.createPair("defaults", d));
+      report.addedDefaults = true;
+    }
+
+    const tools = mapAt(doc, server, "tools");
+    tools.flow = false;
+    const offered = new Set(s.tools.map((t) => t.name));
+    for (const t of s.tools) {
+      if (tools.has(t.name)) {
+        report.kept.push(t.name);
+        continue;
+      }
+      const v = doc.createNode(t.rule, { flow: true });
+      v.comment = ` ${t.why}`;
+      tools.set(t.name, v);
+      report.added.push(t.name);
+    }
+    for (const item of tools.items) {
+      const name = isScalar(item.key) ? String(item.key.value) : String(item.key);
+      if (!offered.has(name)) report.stale.push(name);
+    }
+    return report;
+  });
+}

package/src/startup.ts

@@ -88,7 +88,7 @@ function stdioTransport(u: StdioUpstream, baseDir: string): StdioClientTransport
   });
 }
 
-async function connect(id: string, u: Upstream, baseDir: string): Promise<Client> {
+export async function connectUpstream(id: string, u: Upstream, baseDir: string): Promise<Client> {
   const client = new Client({ name: `adtl-gateway→${id}`, version: GATEWAY_VERSION });
   const transport = isHttpUpstream(u)
     ? new StreamableHTTPClientTransport(new URL(u.url), { requestInit: { headers: u.headers } })
@@ -137,7 +137,7 @@ export async function startGateway(
     const icfg: StdioUpstream = loaded.gateway.interceptors
       ? expandUpstream("interceptors", loaded.gateway.interceptors, env)
       : { command: process.execPath, args: [bundledInterceptorsCli(), "--config", loaded.path], env: {} };
-    const interceptors = await connect("interceptors", icfg, baseDir);
+    const interceptors = await connectUpstream("interceptors", icfg, baseDir);
     clients.push(interceptors);
     if (!interceptors.getServerCapabilities()?.extensions?.[INTERCEPTORS_EXTENSION]) {
       throw new GatewayConfigError(`The interceptor server does not declare the ${INTERCEPTORS_EXTENSION} extension`);
@@ -158,7 +158,7 @@ export async function startGateway(
     const upstreams = new Map<string, Client>();
     const ids = Object.keys(loaded.gateway.upstreams);
     const settled = await Promise.allSettled(
-      ids.map((id) => connect(id, expandUpstream(id, loaded.gateway.upstreams[id]!, env), baseDir)),
+      ids.map((id) => connectUpstream(id, expandUpstream(id, loaded.gateway.upstreams[id]!, env), baseDir)),
     );
     settled.forEach((s, i) => {
       const id = ids[i]!;