@adtl/gateway 0.3.1 → 0.3.2

package/src/init/fromMcpJson.ts

@@ -0,0 +1,165 @@
+/**
+ * `adtl-gateway init --from .mcp.json`: import an MCP client's server list
+ * (Claude Code's .mcp.json, or any file with `mcpServers`, such as Claude
+ * Desktop's config) into `gateway.upstreams`, and point the client at the
+ * gateway instead.
+ *
+ * - stdio servers keep their command, args and env; HTTP servers their url
+ *   and headers. `${VAR}` and `${VAR:-default}` work the same in adtl.yaml.
+ * - SSE servers are left in the client config: the gateway speaks Streamable HTTP only.
+ * - An entry that already runs the gateway is recognized and kept.
+ * - Upstreams already in adtl.yaml are never changed.
+ *
+ * The new client config has the imported servers replaced by one entry that
+ * runs the gateway; everything else in the file is kept.
+ */
+import { dirname, relative, resolve } from "node:path";
+import { isMap, type Document } from "yaml";
+import type { Upstream } from "../config.js";
+import { GATEWAY_VERSION } from "../gateway.js";
+
+export const DEFAULT_GATEWAY_NAME = "adtl";
+
+export interface McpImport {
+  /** Servers moved into gateway.upstreams: name in the client config → upstream id. */
+  imported: { name: string; id: string }[];
+  /** Servers already in adtl.yaml under the same id; left as they are. */
+  kept: { name: string; id: string }[];
+  /** Servers left in the client config, with why. */
+  skipped: { name: string; reason: string }[];
+  /** The client config as it should be once the gateway replaces the imported servers. */
+  text: string;
+  changed: boolean;
+}
+
+type Entry = Record<string, unknown>;
+
+function isRecord(v: unknown): v is Entry {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function strings(v: unknown): string[] | undefined {
+  return Array.isArray(v) && v.every((x) => typeof x === "string") ? (v as string[]) : undefined;
+}
+
+function stringRecord(v: unknown): Record<string, string> | undefined {
+  if (!isRecord(v)) return undefined;
+  return Object.values(v).every((x) => typeof x === "string") ? (v as Record<string, string>) : undefined;
+}
+
+/** True if this client entry already runs adtl-gateway. */
+export function isGatewayEntry(entry: Entry): boolean {
+  const words = [entry.command, ...(strings(entry.args) ?? [])].filter((w): w is string => typeof w === "string");
+  return words.some((w) => /(^|[/\\@])adtl-gateway$|@adtl\/gateway(@[^/\s]*)?$|packages[/\\]gateway[/\\]dist[/\\]cli\.js$/.test(w));
+}
+
+/** A valid upstream id (letters, digits, '-') for a client server name, unique among `taken`. */
+export function upstreamId(name: string, taken: Set<string>): string {
+  const base = name.replace(/[^A-Za-z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "server";
+  let id = base;
+  for (let n = 2; taken.has(id); n++) id = `${base}-${n}`;
+  taken.add(id);
+  return id;
+}
+
+/** The upstream for one client entry, or why it can't be one. */
+export function toUpstream(entry: Entry, mcpDir: string, configDir: string): Upstream | { skip: string } {
+  const type = typeof entry.type === "string" ? entry.type : undefined;
+  if (type === "sse") return { skip: "the gateway doesn't support SSE servers; it speaks Streamable HTTP" };
+  if (type === "http" || (type === undefined && typeof entry.url === "string")) {
+    if (typeof entry.url !== "string") return { skip: "HTTP server without a url" };
+    const headers = stringRecord(entry.headers);
+    return { url: entry.url, headers: headers ?? {} };
+  }
+  if (type !== undefined && type !== "stdio") return { skip: `unknown server type "${type}"` };
+  if (typeof entry.command !== "string" || entry.command === "") return { skip: "no command or url" };
+  // Clients start stdio servers in the project directory; the gateway resolves cwd against adtl.yaml's.
+  const cwd = relative(configDir, mcpDir);
+  const args = strings(entry.args) ?? [];
+  const env = stringRecord(entry.env) ?? {};
+  return {
+    command: entry.command,
+    args,
+    env,
+    ...(cwd !== "" ? { cwd } : {}),
+  };
+}
+
+/** What runs the gateway from the client config, with adtl.yaml given relative to the client config's directory. */
+export function gatewayEntry(configPath: string, mcpDir: string): Entry {
+  return { command: "npx", args: ["-y", `@adtl/gateway@${GATEWAY_VERSION}`, "--config", relative(mcpDir, configPath) || configPath] };
+}
+
+/**
+ * Add the client's servers to `doc` (adtl.yaml) under gateway.upstreams, and
+ * return the client config rewritten to use the gateway.
+ */
+export function importMcpServers(
+  mcpText: string,
+  mcpPath: string,
+  doc: Document,
+  configPath: string,
+  gatewayName = DEFAULT_GATEWAY_NAME,
+): McpImport {
+  let json: unknown;
+  try {
+    json = JSON.parse(mcpText);
+  } catch (err) {
+    throw new Error(`${mcpPath}: not valid JSON: ${(err as Error).message}`);
+  }
+  if (!isRecord(json) || !isRecord(json.mcpServers)) throw new Error(`${mcpPath}: no "mcpServers" object`);
+
+  const mcpDir = dirname(resolve(mcpPath));
+  const configDir = dirname(resolve(configPath));
+  const existing = doc.getIn(["gateway", "upstreams"]);
+  const taken = new Set<string>(isMap(existing) ? existing.items.map((p) => String((p.key as { value?: unknown })?.value ?? p.key)) : []);
+  const alreadyThere = new Set(taken);
+
+  const result: McpImport = { imported: [], kept: [], skipped: [], text: mcpText, changed: false };
+  const servers: Record<string, unknown> = {};
+  let gatewayKey: string | undefined;
+
+  for (const [name, entry] of Object.entries(json.mcpServers)) {
+    if (!isRecord(entry)) {
+      result.skipped.push({ name, reason: "not an object" });
+      servers[name] = entry;
+      continue;
+    }
+    if (isGatewayEntry(entry)) {
+      gatewayKey ??= name;
+      servers[name] = entry;
+      continue;
+    }
+    const upstream = toUpstream(entry, mcpDir, configDir);
+    if ("skip" in upstream) {
+      result.skipped.push({ name, reason: upstream.skip });
+      servers[name] = entry;
+      continue;
+    }
+    const plain = name.replace(/[^A-Za-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+    if (alreadyThere.has(plain)) {
+      result.kept.push({ name, id: plain });
+      continue;
+    }
+    const id = upstreamId(name, taken);
+    // Leave out empty fields; the gateway fills them in.
+    const written = Object.fromEntries(
+      Object.entries(upstream).filter(([, v]) => !(Array.isArray(v) ? v.length === 0 : isRecord(v) && Object.keys(v).length === 0)),
+    );
+    doc.setIn(["gateway", "upstreams", id], doc.createNode(written));
+    result.imported.push({ name, id });
+  }
+  // Block style, so long paths and secrets references stay readable (a new config starts with `upstreams: {}`).
+  const upstreams = doc.getIn(["gateway", "upstreams"]);
+  if (isMap(upstreams) && result.imported.length) upstreams.flow = false;
+
+  if (result.imported.length === 0 && result.kept.length === 0) return result;
+  if (gatewayKey === undefined) {
+    let key = gatewayName;
+    for (let n = 2; key in servers; n++) key = `${gatewayName}-${n}`;
+    servers[key] = gatewayEntry(resolve(configPath), mcpDir);
+  }
+  result.text = `${JSON.stringify({ ...json, mcpServers: servers }, null, 2)}\n`;
+  result.changed = result.text !== mcpText;
+  return result;
+}

package/src/init/index.ts

@@ -1,3 +1,5 @@
 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";
+export { DEFAULT_GATEWAY_NAME, gatewayEntry, importMcpServers, isGatewayEntry, toUpstream, upstreamId, type McpImport } from "./fromMcpJson.js";
+export { NEW_CONFIG } from "./run.js";

package/src/init/run.ts

@@ -2,31 +2,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.
  *
+ * With `from` (e.g. `.mcp.json`), the client's MCP servers are first imported
+ * into gateway.upstreams (see fromMcpJson.ts), and adtl.yaml is created if it
+ * doesn't exist 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.
+ * in place; with `from`, the client config is rewritten to use the gateway,
+ * also keeping a `.bak`. Existing entries and comments are never changed.
  */
 import { readFile, writeFile } from "node:fs/promises";
-import { dirname } from "node:path";
+import { dirname, resolve } 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 { GatewayConfigError, connectUpstream, parseGatewayConfigText } from "../startup.js";
+import { importMcpServers, type McpImport } from "./fromMcpJson.js";
 import { mergeIntoDocument, suggest, type MergeReport, type ServerScan } from "./suggest.js";
 
 export interface InitOptions {
   path: string;
   write?: boolean;
   env?: NodeJS.ProcessEnv;
+  /** An MCP client config with `mcpServers` (e.g. Claude Code's .mcp.json) to import upstreams from. */
+  from?: string;
+  /** Name for the gateway's entry in that client config. Default `adtl`. */
+  gatewayName?: string;
 }
 
+/** Don't fold long values (paths, commands) across lines. */
+const YAML_OPTIONS = { lineWidth: 0 } as const;
+
+/** Starting point when `--from` creates adtl.yaml. */
+export const NEW_CONFIG = `# ADTL config, drafted by \`adtl-gateway init --from\`. Review every rule marked "review".
+#
+# For every tool, say what its result is (integrity, confidentiality) and where
+# calling it can send data (egress). Anything left out gets the defaults below.
+
+defaults:
+  integrity: untrusted
+  confidentiality: private
+
+policy:
+  default: allow
+  rules:
+    - name: no-public-write-after-untrusted
+      when:
+        session.integrity: untrusted
+        tool.egress: [public, external, unknown]
+      then: ask
+      reason: Session has read untrusted content; confirm before sending data out
+
+    - name: private-stays-private
+      when:
+        session.confidentiality: [private, secret]
+        tool.egress: public
+      then: block
+      reason: Private data must not reach a public tool
+
+gateway:
+  upstreams: {}
+`;
+
 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 }[];
+  /** With `from`: what was imported, and the rewritten client config. */
+  mcp?: McpImport & { path: string };
+  /** True if adtl.yaml didn't exist and was drafted from scratch. */
+  created?: boolean;
 }
 
 async function listAllTools(client: Client): Promise<Tool[]> {
@@ -53,10 +101,35 @@ async function scan(id: string, connect: () => Promise<Client>): Promise<ServerS
 
 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 path = resolve(opts.path);
+  let original: string | undefined;
+  try {
+    original = await readFile(path, "utf8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT" || !opts.from) {
+      throw new GatewayConfigError(`Cannot read config file ${path}: ${(err as Error).message}`);
+    }
+  }
+  const doc = parseDocument(original ?? NEW_CONFIG);
 
+  let mcp: InitResult["mcp"];
+  if (opts.from) {
+    const mcpPath = resolve(opts.from);
+    let mcpText: string;
+    try {
+      mcpText = await readFile(mcpPath, "utf8");
+    } catch (err) {
+      throw new GatewayConfigError(`Cannot read ${mcpPath}: ${(err as Error).message}`);
+    }
+    try {
+      mcp = { path: mcpPath, ...importMcpServers(mcpText, mcpPath, doc, path, opts.gatewayName) };
+    } catch (err) {
+      throw new GatewayConfigError((err as Error).message);
+    }
+  }
+
+  const loaded = parseGatewayConfigText(doc.toString(YAML_OPTIONS), path);
+  const baseDir = dirname(loaded.path);
   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))),
@@ -68,12 +141,18 @@ export async function runInit(opts: InitOptions): Promise<InitResult> {
     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");
+  const text = doc.toString(YAML_OPTIONS);
+  if (opts.write) {
+    if (original === undefined) await writeFile(path, text, "utf8");
+    else if (text !== original) {
+      await writeFile(`${path}.bak`, original, "utf8");
+      await writeFile(path, text, "utf8");
+    }
+    if (mcp?.changed) {
+      await writeFile(`${mcp.path}.bak`, await readFile(mcp.path, "utf8"), "utf8");
+      await writeFile(mcp.path, mcp.text, "utf8");
+    }
   }
-  return { text, reports, failed };
+  return { text, reports, failed, ...(mcp ? { mcp } : {}), ...(original === undefined ? { created: true } : {}) };
 }

package/src/startup.ts

@@ -49,6 +49,12 @@ export async function loadGatewayConfig(path: string): Promise<LoadedConfig> {
   } catch (err) {
     throw new GatewayConfigError(`Cannot read config file ${abs}: ${(err as Error).message}`);
   }
+  return parseGatewayConfigText(text, abs);
+}
+
+/** Validate adtl.yaml text; `path` is where it lives (relative paths in it resolve against its directory). */
+export function parseGatewayConfigText(text: string, path: string): LoadedConfig {
+  const abs = resolve(path);
   let labels: AdtlConfig;
   try {
     labels = parseConfigText(text, abs);