@slashfi/agents-sdk 0.21.0 → 0.22.0

package/src/adk.ts

@@ -0,0 +1,398 @@
+#!/usr/bin/env bun
+/**
+ * ADK CLI — Agent Development Kit
+ *
+ * Unified CLI for building, testing, and publishing agent definitions.
+ *
+ * Commands:
+ *   codegen     Generate agent definitions from an MCP server (full codegen)
+ *   introspect  Introspect an MCP server → agent.json (lightweight)
+ *   pack        Generate publishable @agentdef/* package from agent.json
+ *   publish     Pack + npm publish to @agentdef/*
+ *   use         Execute a tool on a generated agent
+ *   list        List all generated agents
+ *
+ * @example
+ * ```bash
+ * # Full codegen from MCP server
+ * adk codegen --server 'npx @mcp/notion' --name notion --out ./agents/@notion
+ *
+ * # Lightweight introspect → agent.json
+ * adk introspect --server 'npx @notionhq/notion-mcp-server' --name notion
+ *
+ * # Build + publish
+ * adk pack
+ * adk publish
+ *
+ * # Use a tool
+ * adk use notion search_pages '{"query": "hello"}'
+ * adk use notion --list
+ * ```
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { codegen, listAgentTools, useAgent } from "./codegen.js";
+import type { CodegenManifest } from "./codegen.js";
+import { pack, publish } from "./pack.js";
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+// ============================================
+// Helpers
+// ============================================
+
+function getArg(flag: string): string | undefined {
+  const idx = args.indexOf(flag);
+  if (idx === -1 || idx + 1 >= args.length) return undefined;
+  return args[idx + 1];
+}
+
+function hasFlag(flag: string): boolean {
+  return args.includes(flag);
+}
+
+function getAgentsDir(): string {
+  return resolve(process.env.AGENTS_SDK_DIR ?? "./agents");
+}
+
+function findAgentDir(name: string): string | null {
+  const agentsDir = getAgentsDir();
+
+  const exactPath = resolve(name);
+  if (existsSync(join(exactPath, ".codegen-manifest.json"))) return exactPath;
+
+  const withAt = join(agentsDir, `@${name}`);
+  if (existsSync(join(withAt, ".codegen-manifest.json"))) return withAt;
+
+  const withoutAt = join(agentsDir, name);
+  if (existsSync(join(withoutAt, ".codegen-manifest.json"))) return withoutAt;
+
+  return null;
+}
+
+function printUsage() {
+  console.log(`
+adk — Agent Development Kit
+
+Usage:
+  adk codegen [options]              Generate agent from MCP server (full codegen)
+  adk introspect [options]           Introspect MCP server → agent.json
+  adk pack [options]                 Generate publishable package from agent.json
+  adk publish [options]              Pack + npm publish to @agentdef/*
+  adk use <agent> [options]          Execute a tool on a generated agent
+  adk list                           List all generated agents
+
+Codegen options:
+  --server <source>     MCP server (command string or URL)
+  --name <name>         Agent name (default: derived from server)
+  --out <dir>           Output directory (default: ./agents/@<name>)
+  --path <path>         Agent path override
+  --no-cli              Skip CLI generation
+  --no-types            Skip TypeScript interface generation
+  --visibility <level>  Agent visibility (public|internal|private)
+
+Introspect options:
+  --server <cmd>        MCP server command to introspect
+  --name <name>         Agent name for output
+  --out <path>          Output path (default: ./<name>.json)
+
+Pack / Publish options:
+  --agent <path>        Path to agent.json (default: ./agent.json)
+  --out <dir>           Output directory (default: ./dist)
+  --scope <scope>       npm scope (default: @agentdef)
+  --previous <path>     Previous agent.json for diff
+  --dry-run             Don't actually publish (publish only)
+  --tag <tag>           npm dist-tag (default: latest)
+  --access <level>      npm access: public | restricted (default: public)
+
+Use options:
+  adk use <agent> <tool> [params_json]
+  adk use <agent> --list              List tools on the agent
+
+Examples:
+  adk codegen --server 'npx @mcp/notion' --name notion
+  adk introspect --server 'npx @notionhq/notion-mcp-server' --name notion
+  adk pack --agent ./agent.json
+  adk publish --dry-run
+  adk use notion search_pages '{"query": "hello"}'
+`);
+}
+
+// ============================================
+// Commands
+// ============================================
+
+async function runCodegen() {
+  const server = getArg("--server");
+  const name = getArg("--name");
+  const outDir = getArg("--out");
+  const agentPath = getArg("--path");
+  const visibility = getArg("--visibility") as
+    | "public"
+    | "internal"
+    | "private"
+    | undefined;
+  const noCli = hasFlag("--no-cli");
+  const noTypes = hasFlag("--no-types");
+
+  if (!server) {
+    console.error(
+      "Error: --server is required.\n" +
+        "  Example: adk codegen --server 'npx @mcp/notion' --name notion",
+    );
+    process.exit(1);
+  }
+
+  const resolvedOutDir =
+    outDir ??
+    join(
+      getAgentsDir(),
+      `@${(name ?? "mcp-agent").toLowerCase().replace(/[^a-z0-9-]/g, "-")}`,
+    );
+
+  console.log(`Connecting to MCP server: ${server}`);
+  console.log(`Output: ${resolvedOutDir}\n`);
+
+  try {
+    const result = await codegen({
+      server,
+      outDir: resolvedOutDir,
+      agentPath,
+      name,
+      cli: !noCli,
+      types: !noTypes,
+      visibility,
+    });
+
+    console.log(
+      `\x1b[32m\u2713\x1b[0m Generated ${result.toolCount} tools from ${result.serverInfo.name ?? "MCP server"}`,
+    );
+    console.log("\nFiles:");
+    for (const f of result.files) {
+      console.log(`  ${f}`);
+    }
+    console.log(
+      `\nUse: adk use ${name ?? result.serverInfo.name ?? "<agent>"} --list`,
+    );
+  } catch (err) {
+    console.error(
+      `\x1b[31mError:\x1b[0m ${err instanceof Error ? err.message : String(err)}`,
+    );
+    process.exit(1);
+  }
+}
+
+async function runIntrospect() {
+  const server = getArg("--server");
+  const name = getArg("--name");
+  const out = getArg("--out") || (name ? `./${name}.json` : undefined);
+
+  if (!server || !name) {
+    console.error(
+      "Usage: adk introspect --server <cmd> --name <name> [--out <path>]",
+    );
+    process.exit(1);
+  }
+
+  const { introspectMcp } = await import("./introspect.js");
+  await introspectMcp({ server, name, out });
+}
+
+function runPack() {
+  const agentFile = getArg("--agent") || "./agent.json";
+  const outDir = getArg("--out") || "./dist";
+  const scope = getArg("--scope") || "@agentdef";
+  const previousAgentFile = getArg("--previous");
+
+  if (!existsSync(resolve(agentFile))) {
+    console.error(`agent.json not found at ${resolve(agentFile)}`);
+    console.error("Run 'adk introspect' first, or specify --agent <path>");
+    process.exit(1);
+  }
+
+  const result = pack({ agentFile, outDir, scope, previousAgentFile });
+  console.log(`\n\u2705 Packed ${result.packageName}@${result.version}`);
+  console.log(`   Hash: ${result.hash}`);
+  console.log(`   Tools: ${result.meta.toolCount}`);
+  console.log(`   Size: ${(result.meta.sizeBytes / 1024).toFixed(1)}KB`);
+  console.log(`   Output: ${result.packageDir}`);
+  if (result.meta.changes) {
+    const c = result.meta.changes;
+    if (c.toolsAdded.length > 0)
+      console.log(`   Added: ${c.toolsAdded.join(", ")}`);
+    if (c.toolsRemoved.length > 0)
+      console.log(`   Removed: ${c.toolsRemoved.join(", ")}`);
+    if (c.toolsModified.length > 0)
+      console.log(`   Modified: ${c.toolsModified.join(", ")}`);
+  }
+}
+
+function runPublish() {
+  const agentFile = getArg("--agent") || "./agent.json";
+  const outDir = getArg("--out") || "./dist";
+  const scope = getArg("--scope") || "@agentdef";
+  const previousAgentFile = getArg("--previous");
+  const dryRun = hasFlag("--dry-run");
+  const tag = getArg("--tag");
+  const access = getArg("--access") as "public" | "restricted" | undefined;
+  const registry = getArg("--registry");
+
+  if (!existsSync(resolve(agentFile))) {
+    console.error(`agent.json not found at ${resolve(agentFile)}`);
+    console.error("Run 'adk introspect' first, or specify --agent <path>");
+    process.exit(1);
+  }
+
+  try {
+    const result = publish({
+      agentFile,
+      outDir,
+      scope,
+      previousAgentFile,
+      dryRun,
+      tag,
+      access,
+      registry,
+    });
+    console.log(
+      `\n\u2705 Published ${result.packageName}@${result.version} (hash: ${result.hash})`,
+    );
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+
+async function runUse() {
+  const agentName = args[1];
+
+  if (!agentName) {
+    console.error(
+      "Error: agent name required.\n" +
+        "  Example: adk use notion search_pages '{...}'",
+    );
+    process.exit(1);
+  }
+
+  const agentDir = findAgentDir(agentName);
+  if (!agentDir) {
+    console.error(
+      `Error: agent '${agentName}' not found.\n` +
+        `  Looked in: ${getAgentsDir()}\n` +
+        `  Generate first: adk codegen --server '...' --name ${agentName}`,
+    );
+    process.exit(1);
+  }
+
+  if (hasFlag("--list")) {
+    const tools = listAgentTools(agentDir);
+    console.log(`Tools for ${agentName}:\n`);
+    for (const t of tools) {
+      console.log(`  ${t.name.padEnd(30)} ${t.description ?? ""}`);
+    }
+    return;
+  }
+
+  const toolName = args[2];
+  if (!toolName) {
+    console.error(
+      `Error: tool name required.\n  Example: adk use ${agentName} <tool> [params]\n  List tools: adk use ${agentName} --list`,
+    );
+    process.exit(1);
+  }
+
+  const paramsStr = args[3];
+  const params = paramsStr ? JSON.parse(paramsStr) : {};
+
+  try {
+    const result = await useAgent({
+      agentDir,
+      tool: toolName,
+      params,
+    });
+    console.log(JSON.stringify(result, null, 2));
+  } catch (err) {
+    console.error(
+      `\x1b[31mError:\x1b[0m ${err instanceof Error ? err.message : String(err)}`,
+    );
+    process.exit(1);
+  }
+}
+
+function runList() {
+  const agentsDir = getAgentsDir();
+
+  if (!existsSync(agentsDir)) {
+    console.log("No generated agents found.");
+    return;
+  }
+
+  const entries = readdirSync(agentsDir);
+  const agents: { name: string; tools: number; server?: string }[] = [];
+
+  for (const entry of entries) {
+    const manifestPath = join(agentsDir, entry, ".codegen-manifest.json");
+    if (existsSync(manifestPath)) {
+      try {
+        const manifest: CodegenManifest = JSON.parse(
+          require("node:fs").readFileSync(manifestPath, "utf-8"),
+        );
+        agents.push({
+          name: manifest.agentPath,
+          tools: manifest.tools.length,
+          server: manifest.serverInfo.name,
+        });
+      } catch {
+        agents.push({ name: entry, tools: 0 });
+      }
+    }
+  }
+
+  if (agents.length === 0) {
+    console.log("No generated agents found.");
+    return;
+  }
+
+  console.log("Generated agents:\n");
+  for (const a of agents) {
+    console.log(
+      `  ${a.name.padEnd(25)} ${String(a.tools).padEnd(5)} tools${a.server ? `  (${a.server})` : ""}`,
+    );
+  }
+}
+
+// ============================================
+// Main
+// ============================================
+
+switch (command) {
+  case "codegen":
+    await runCodegen();
+    break;
+  case "introspect":
+    await runIntrospect();
+    break;
+  case "pack":
+    runPack();
+    break;
+  case "publish":
+    runPublish();
+    break;
+  case "use":
+    await runUse();
+    break;
+  case "list":
+    runList();
+    break;
+  case "--help":
+  case "-h":
+  case undefined:
+    printUsage();
+    break;
+  default:
+    console.error(`Unknown command: ${command}`);
+    printUsage();
+    process.exit(1);
+}

package/src/index.ts

@@ -314,3 +314,29 @@ export type {
   AgentClient,
   CreateClientOptions,
 } from "./client.js";
+
+// ============================================
+// JSONC Parser
+// ============================================
+
+export { parseJsonc, readJsoncFile } from "./jsonc.js";
+
+// ============================================
+// Pack & Publish
+// ============================================
+
+export { pack, publish } from "./pack.js";
+export type {
+  PackOptions,
+  PackResult,
+  PublishOptions,
+  VersionMeta,
+  VersionChanges,
+} from "./pack.js";
+
+// ============================================
+// Introspect
+// ============================================
+
+export { introspectMcp } from "./introspect.js";
+export type { IntrospectOptions } from "./introspect.js";

package/src/introspect.ts

@@ -0,0 +1,171 @@
+/**
+ * MCP Introspection
+ *
+ * Connects to an MCP server, introspects its tools,
+ * and outputs a SerializedAgentDefinition (agent.json).
+ *
+ * Deduplicates shared $defs across tools.
+ */
+
+import { spawn } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+export interface IntrospectOptions {
+  server: string;
+  name: string;
+  out?: string;
+  env?: Record<string, string>;
+}
+
+function deduplicateDefs(tools: Record<string, unknown>[]): {
+  tools: Record<string, unknown>[];
+  sharedDefs: Record<string, unknown>;
+} {
+  const defsByContent = new Map<string, { name: string; schema: unknown }>();
+
+  for (const tool of tools) {
+    const schema = tool.inputSchema as Record<string, unknown> | undefined;
+    const defs = schema?.$defs;
+    if (!defs || typeof defs !== "object") continue;
+    for (const [defName, defSchema] of Object.entries(
+      defs as Record<string, unknown>,
+    )) {
+      const key = JSON.stringify(defSchema);
+      if (!defsByContent.has(key)) {
+        defsByContent.set(key, { name: defName, schema: defSchema });
+      }
+    }
+  }
+
+  const sharedDefs: Record<string, unknown> = {};
+  for (const { name, schema } of Array.from(defsByContent.values())) {
+    sharedDefs[name] = schema;
+  }
+
+  const cleanedTools = tools.map((t) => {
+    const schema = { ...(t.inputSchema as Record<string, unknown>) };
+    schema.$defs = undefined;
+    return { ...t, inputSchema: schema };
+  });
+
+  return { tools: cleanedTools, sharedDefs };
+}
+
+export async function introspectMcp(options: IntrospectOptions): Promise<void> {
+  const { server, name, out } = options;
+
+  const parts = server.split(/\s+/);
+  const proc = spawn(parts[0], parts.slice(1), {
+    stdio: ["pipe", "pipe", "pipe"],
+    env: { ...process.env, ...options.env },
+  });
+
+  let buffer = "";
+  let messageId = 0;
+
+  function sendJsonRpc(
+    method: string,
+    params: Record<string, unknown> = {},
+  ): number {
+    const id = ++messageId;
+    const msg = JSON.stringify({ jsonrpc: "2.0", id, method, params });
+    proc.stdin?.write(`${msg}\n`);
+    return id;
+  }
+
+  function waitForResponse(targetId: number): Promise<Record<string, unknown>> {
+    return new Promise((res, reject) => {
+      const timeout = setTimeout(() => reject(new Error("Timeout")), 30000);
+      const handler = (chunk: Buffer) => {
+        buffer += chunk.toString();
+        const lines = buffer.split("\n");
+        buffer = lines.pop() || "";
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed) continue;
+          try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed.id === targetId) {
+              clearTimeout(timeout);
+              proc.stdout?.removeListener("data", handler);
+              if (parsed.error) reject(new Error(JSON.stringify(parsed.error)));
+              else res(parsed.result);
+            }
+          } catch {
+            /* ignore non-JSON */
+          }
+        }
+      };
+      proc.stdout?.on("data", handler);
+    });
+  }
+
+  try {
+    console.log(`Connecting to MCP server: ${server}`);
+
+    const initId = sendJsonRpc("initialize", {
+      protocolVersion: "2024-11-05",
+      capabilities: {},
+      clientInfo: { name: "adk-introspect", version: "1.0.0" },
+    });
+    const initResult = (await waitForResponse(initId)) as Record<
+      string,
+      unknown
+    >;
+    const serverInfo = initResult.serverInfo as
+      | Record<string, string>
+      | undefined;
+    console.log(`Server: ${serverInfo?.name} v${serverInfo?.version}`);
+
+    proc.stdin?.write(
+      `${JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" })}\n`,
+    );
+
+    const toolsId = sendJsonRpc("tools/list", {});
+    const toolsResult = (await waitForResponse(toolsId)) as Record<
+      string,
+      unknown
+    >;
+    const rawTools = (
+      (toolsResult.tools || []) as Record<string, unknown>[]
+    ).map((t) => ({
+      name: t.name as string,
+      description: (t.description as string) || "",
+      inputSchema: (t.inputSchema as Record<string, unknown>) || {
+        type: "object",
+        properties: {},
+      },
+    }));
+    console.log(`Discovered ${rawTools.length} tools`);
+
+    const { tools, sharedDefs } = deduplicateDefs(rawTools);
+    const defsCount = Object.keys(sharedDefs).length;
+    if (defsCount > 0) {
+      console.log(`Hoisted ${defsCount} shared $defs`);
+    }
+
+    const definition: Record<string, unknown> = {
+      path: name,
+      name: serverInfo?.name || name,
+      description: `Agent for ${serverInfo?.name || name}`,
+      version: serverInfo?.version || "1.0.0",
+      visibility: "public",
+      serverSource: server,
+      serverInfo,
+      ...(defsCount > 0 ? { $defs: sharedDefs } : {}),
+      tools,
+      generatedAt: new Date().toISOString(),
+      sdkVersion: "0.22.0",
+    };
+
+    const outPath = out || `./${name}.json`;
+    const resolved = resolve(outPath);
+    mkdirSync(dirname(resolved), { recursive: true });
+    writeFileSync(resolved, `${JSON.stringify(definition, null, 2)}\n`);
+    const sizeKB = (JSON.stringify(definition).length / 1024).toFixed(1);
+    console.log(`\nWrote ${resolved} (${sizeKB}KB, ${tools.length} tools)`);
+  } finally {
+    proc.kill();
+  }
+}

package/src/jsonc.ts

@@ -0,0 +1,83 @@
+/**
+ * JSONC Parser
+ *
+ * Parses JSON with comments (single-line and multi-line)
+ * so agent.json files can be annotated.
+ */
+
+import { readFileSync } from "node:fs";
+
+/**
+ * Strip comments from JSONC content and parse as JSON.
+ */
+export function parseJsonc(content: string): unknown {
+  let result = "";
+  let i = 0;
+  let inString = false;
+  let stringChar = "";
+
+  while (i < content.length) {
+    if (inString) {
+      if (content[i] === "\\" && i + 1 < content.length) {
+        result += content[i] + content[i + 1];
+        i += 2;
+        continue;
+      }
+      if (content[i] === stringChar) {
+        inString = false;
+      }
+      result += content[i];
+      i++;
+      continue;
+    }
+
+    if (content[i] === '"') {
+      inString = true;
+      stringChar = content[i];
+      result += content[i];
+      i++;
+      continue;
+    }
+
+    // Single-line comment
+    if (
+      content[i] === "/" &&
+      i + 1 < content.length &&
+      content[i + 1] === "/"
+    ) {
+      while (i < content.length && content[i] !== "\n") i++;
+      continue;
+    }
+
+    // Multi-line comment
+    if (
+      content[i] === "/" &&
+      i + 1 < content.length &&
+      content[i + 1] === "*"
+    ) {
+      i += 2;
+      while (
+        i + 1 < content.length &&
+        !(content[i] === "*" && content[i + 1] === "/")
+      )
+        i++;
+      i += 2;
+      continue;
+    }
+
+    result += content[i];
+    i++;
+  }
+
+  // Handle trailing commas
+  const cleaned = result.replace(/,\s*([}\]])/g, "$1");
+  return JSON.parse(cleaned);
+}
+
+/**
+ * Read and parse a JSONC file.
+ */
+export function readJsoncFile(path: string): unknown {
+  const content = readFileSync(path, "utf-8");
+  return parseJsonc(content);
+}