@slashfi/agents-sdk 0.18.0 → 0.20.0

package/dist/cli.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env bun
+/**
+ * agents-sdk CLI
+ *
+ * Unified command-line interface for the agents SDK.
+ *
+ * Commands:
+ *   codegen  - Generate agent definitions from an MCP server
+ *   use      - Execute a tool on a codegenned agent
+ *
+ * @example
+ * ```bash
+ * # Generate from MCP server
+ * agents-sdk codegen --server 'npx @mcp/notion' --name notion --out ./agents/@notion
+ *
+ * # Use a tool
+ * agents-sdk use notion search_pages '{"query": "hello"}'
+ *
+ * # List tools on a codegenned agent
+ * agents-sdk use notion --list
+ * ```
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;GAoBG"}

package/dist/cli.js

@@ -0,0 +1,234 @@
+#!/usr/bin/env bun
+/**
+ * agents-sdk CLI
+ *
+ * Unified command-line interface for the agents SDK.
+ *
+ * Commands:
+ *   codegen  - Generate agent definitions from an MCP server
+ *   use      - Execute a tool on a codegenned agent
+ *
+ * @example
+ * ```bash
+ * # Generate from MCP server
+ * agents-sdk codegen --server 'npx @mcp/notion' --name notion --out ./agents/@notion
+ *
+ * # Use a tool
+ * agents-sdk use notion search_pages '{"query": "hello"}'
+ *
+ * # List tools on a codegenned agent
+ * agents-sdk use notion --list
+ * ```
+ */
+import { resolve, join } from "node:path";
+import { existsSync, readdirSync } from "node:fs";
+import { codegen, useAgent, listAgentTools } from "./codegen.js";
+const args = process.argv.slice(2);
+const command = args[0];
+// ============================================
+// Helpers
+// ============================================
+function parseFlag(args, flag) {
+    const idx = args.indexOf(flag);
+    if (idx === -1 || idx + 1 >= args.length)
+        return undefined;
+    return args[idx + 1];
+}
+function hasFlag(args, flag) {
+    return args.includes(flag);
+}
+/** Default directory for codegenned agents */
+function getAgentsDir() {
+    return resolve(process.env.AGENTS_SDK_DIR ?? "./agents");
+}
+/** Find an agent directory by name */
+function findAgentDir(name) {
+    const agentsDir = getAgentsDir();
+    // Try exact path first
+    const exactPath = resolve(name);
+    if (existsSync(join(exactPath, ".codegen-manifest.json"))) {
+        return exactPath;
+    }
+    // Try under agents dir with @ prefix
+    const withAt = join(agentsDir, `@${name}`);
+    if (existsSync(join(withAt, ".codegen-manifest.json"))) {
+        return withAt;
+    }
+    // Try under agents dir without @ prefix
+    const withoutAt = join(agentsDir, name);
+    if (existsSync(join(withoutAt, ".codegen-manifest.json"))) {
+        return withoutAt;
+    }
+    return null;
+}
+function printUsage() {
+    console.log(`agents-sdk - SDK for building AI agents
+
+Usage:
+  agents-sdk codegen [options]     Generate agent from MCP server
+  agents-sdk use <agent> [options] Execute a tool on a generated agent
+  agents-sdk 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)
+
+Use options:
+  agents-sdk use <agent> <tool> [params_json]
+  agents-sdk use <agent> --list   List tools on the agent
+
+Examples:
+  agents-sdk codegen --server 'npx @mcp/notion' --name notion
+  agents-sdk use notion search_pages '{"query": "hello"}'
+  agents-sdk use notion --list
+`);
+}
+// ============================================
+// Commands
+// ============================================
+async function runCodegen(args) {
+    const server = parseFlag(args, "--server");
+    const name = parseFlag(args, "--name");
+    const outDir = parseFlag(args, "--out");
+    const agentPath = parseFlag(args, "--path");
+    const visibility = parseFlag(args, "--visibility");
+    const noCli = hasFlag(args, "--no-cli");
+    const noTypes = hasFlag(args, "--no-types");
+    if (!server) {
+        console.error("Error: --server is required.\n" +
+            "  Example: agents-sdk 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: agents-sdk 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 runUse(args) {
+    const agentName = args[1];
+    if (!agentName) {
+        console.error("Error: agent name required.\n" +
+            "  Example: agents-sdk use notion search_pages '{...}'");
+        process.exit(1);
+    }
+    const agentDir = findAgentDir(agentName);
+    if (!agentDir) {
+        console.error(`Error: No generated agent '${agentName}' found.\n` +
+            `  Looked in: ${getAgentsDir()}\n` +
+            `  Run: agents-sdk codegen --server '...' --name ${agentName}`);
+        process.exit(1);
+    }
+    // --list: show available tools
+    if (hasFlag(args, "--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: agents-sdk use ${agentName} <tool> [params]\n` +
+            `  List tools: agents-sdk 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 = [];
+    for (const entry of entries) {
+        const manifestPath = join(agentsDir, entry, ".codegen-manifest.json");
+        if (existsSync(manifestPath)) {
+            try {
+                const manifest = 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(args);
+        break;
+    case "use":
+        await runUse(args);
+        break;
+    case "list":
+        runList();
+        break;
+    case "--help":
+    case "-h":
+    case undefined:
+        printUsage();
+        break;
+    default:
+        console.error(`Unknown command: ${command}`);
+        printUsage();
+        process.exit(1);
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/codegen.d.ts

@@ -0,0 +1,137 @@
+/**
+ * MCP Codegen
+ *
+ * Connects to any MCP server, introspects its tools via `tools/list`,
+ * and generates readable agent-definition source files.
+ *
+ * Supports three transport modes:
+ * - stdio: spawn a process (e.g., `npx @modelcontextprotocol/server-notion`)
+ * - sse: connect to an SSE endpoint
+ * - http: connect to an HTTP JSON-RPC endpoint
+ *
+ * @example
+ * ```typescript
+ * import { codegen } from '@slashfi/agents-sdk';
+ *
+ * await codegen({
+ *   server: 'npx @modelcontextprotocol/server-notion',
+ *   outDir: './generated/notion',
+ *   agentPath: '@notion',
+ * });
+ * ```
+ *
+ * @example CLI
+ * ```bash
+ * agents-sdk codegen --server 'npx @mcp/notion' --name notion
+ * agents-sdk use notion search_pages '{"query": "hello"}'
+ * agents-sdk use notion --list
+ * ```
+ */
+import type { JsonSchema } from "./types.js";
+/** MCP tool definition as returned by tools/list */
+export interface McpToolDefinition {
+    name: string;
+    description?: string;
+    inputSchema?: JsonSchema;
+}
+/** MCP server info from initialize response */
+export interface McpServerInfo {
+    name?: string;
+    version?: string;
+    protocolVersion?: string;
+}
+/** Transport for communicating with an MCP server */
+export interface McpTransport {
+    send(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    /** Send a JSON-RPC notification (no id, no response expected) */
+    notify(method: string, params?: Record<string, unknown>): Promise<void>;
+    close(): Promise<void>;
+}
+/** Server source — string command, URL, or explicit config */
+export type ServerSource = string | {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+} | {
+    url: string;
+    headers?: Record<string, string>;
+} | {
+    spawn: string;
+    args?: string[];
+    env?: Record<string, string>;
+    port?: number;
+    endpoint?: string;
+};
+/** Options for the codegen function */
+export interface CodegenOptions {
+    /** MCP server source — command string, URL, or config object */
+    server: ServerSource;
+    /** Output directory for generated files */
+    outDir: string;
+    /** Agent path override (default: derived from server name) */
+    agentPath?: string;
+    /** Agent display name */
+    name?: string;
+    /** SDK import path (default: '@slashfi/agents-sdk') */
+    sdkImport?: string;
+    /** Whether to generate a CLI entrypoint (default: true) */
+    cli?: boolean;
+    /** Whether to generate TypeScript interfaces from schemas (default: true) */
+    types?: boolean;
+    /** Visibility for the generated agent (default: 'public') */
+    visibility?: "public" | "internal" | "private";
+}
+/** Result of codegen */
+export interface CodegenResult {
+    /** Path to the output directory */
+    outDir: string;
+    /** Server info from the MCP initialize handshake */
+    serverInfo: McpServerInfo;
+    /** Number of tools generated */
+    toolCount: number;
+    /** Names of generated tool files */
+    toolFiles: string[];
+    /** All generated file paths */
+    files: string[];
+}
+/** Convert tool name to a valid TypeScript identifier (camelCase) */
+export declare function toIdentifier(name: string): string;
+/** Convert tool name to PascalCase for type names */
+export declare function toPascalCase(name: string): string;
+/** Serialize a JSON schema to a readable TypeScript literal string */
+export declare function schemaToString(schema: JsonSchema, indent?: number): string;
+/** Generate a TypeScript interface from a JSON Schema */
+export declare function schemaToInterface(name: string, schema: JsonSchema): string;
+/** Manifest stored in outDir for `agents-sdk use` */
+export interface CodegenManifest {
+    agentPath: string;
+    serverSource: ServerSource;
+    serverInfo: McpServerInfo;
+    tools: {
+        name: string;
+        description?: string;
+    }[];
+    generatedAt: string;
+}
+/**
+ * Connect to an MCP server, introspect its tools, and generate
+ * agent-definition source files.
+ */
+export declare function codegen(options: CodegenOptions): Promise<CodegenResult>;
+/**
+ * Execute a tool on a previously codegenned agent by reconnecting
+ * to the MCP server and calling the tool.
+ */
+export declare function useAgent(options: {
+    /** Path to the generated agent directory (contains .codegen-manifest.json) */
+    agentDir: string;
+    /** Tool name to execute */
+    tool: string;
+    /** Tool parameters */
+    params?: Record<string, unknown>;
+}): Promise<unknown>;
+/**
+ * List tools available on a codegenned agent.
+ */
+export declare function listAgentTools(agentDir: string): CodegenManifest["tools"];
+//# sourceMappingURL=codegen.d.ts.map

package/dist/codegen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegen.d.ts","sourceRoot":"","sources":["../src/codegen.ts"],"names":[],"mappings":"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"}