@adtl/gateway 0.2.0 → 0.3.1

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

@@ -9,7 +9,7 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport, getDefaultEnvironment } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { INTERCEPTORS_EXTENSION, LABEL_INTERCEPTOR, POLICY_INTERCEPTOR, parseConfigText } from "@adtl/interceptors";
-import type { AdtlConfig } from "@adtl/labels";
+import { defaultSessionsDir, type AdtlConfig } from "@adtl/labels";
 import { parse as parseYaml } from "yaml";
 import { ZodError } from "zod";
 import { ApprovalBroker, type Notifier } from "./approvals.js";
@@ -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 } })
@@ -117,6 +117,16 @@ export function createApprovals(cfg: GatewayConfig, env: NodeJS.ProcessEnv, log:
   return new ApprovalBroker({ notifiers, timeoutMs: a.timeoutSeconds * 1000, log });
 }
 
+/**
+ * Under Claude Code, which passes `CLAUDE_CODE_SESSION_ID` to stdio MCP
+ * servers, the gateway uses that id and keeps session labels in files, so the
+ * Claude Code hooks (`adtl-gateway hook`) add to the same session label.
+ */
+export function sharedSession(env: NodeJS.ProcessEnv): { sessionId: string; dir: string } | undefined {
+  const sessionId = env.CLAUDE_CODE_SESSION_ID?.trim();
+  return sessionId ? { sessionId, dir: defaultSessionsDir(env) } : undefined;
+}
+
 export interface StartedGateway {
   gateway: AdtlGateway;
   close(): Promise<void>;
@@ -134,10 +144,16 @@ export async function startGateway(
 
   try {
     // 1. Interceptor server (out of process, per the Interceptors WG).
-    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 shared = sharedSession(env);
+    const custom = loaded.gateway.interceptors && expandUpstream("interceptors", loaded.gateway.interceptors, env);
+    const icfg: StdioUpstream = custom
+      ? { ...custom, env: { ...custom.env, ...(shared ? { ADTL_SESSIONS_DIR: shared.dir } : {}) } }
+      : {
+          command: process.execPath,
+          args: [bundledInterceptorsCli(), "--config", loaded.path, ...(shared ? ["--sessions-dir", shared.dir] : [])],
+          env: {},
+        };
+    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`);
@@ -152,13 +168,14 @@ export async function startGateway(
     const audit = loaded.gateway.mode === "audit";
     const invoker = new InterceptorInvoker(bound, loaded.gateway.interceptorTimeoutMs, audit ? "audit" : undefined);
     log.info(`interceptors: ${names.join(", ")}`);
+    if (shared) log.info(`sharing session labels with Claude Code hooks (${shared.dir})`);
     if (audit) log.warn("audit mode: calls are logged but never stopped or changed");
 
     // 2. Upstream servers. One failing upstream does not stop the others.
     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]!;
@@ -178,6 +195,7 @@ export async function startGateway(
     const auditLog = loaded.gateway.audit ? new JsonlAuditLog(resolve(baseDir, loaded.gateway.audit)) : undefined;
     const approvals = createApprovals(loaded.gateway, env, log);
     const gateway = new AdtlGateway({
+      ...(shared ? { sessionId: shared.sessionId } : {}),
       upstreams,
       invoker,
       ...(auditLog ? { audit: auditLog } : {}),