agency-lang 0.0.99 → 0.0.101

package/dist/lib/backends/typescriptBuilder.d.ts

@@ -29,14 +29,18 @@ export declare class TypeScriptBuilder {
     private _sourceMapBuilder;
     private programInfo;
     private moduleId;
+    private outputFile;
     /**
      * @param config - Agency compiler configuration (model defaults, logging, etc.)
      * @param info - Pre-collected program metadata (function definitions, graph nodes, imports, type hints)
      * @param moduleId - Unique identifier for this module (e.g., "foo.agency"), used to
      *   namespace global variables in the GlobalStore so that different modules' globals
      *   don't collide. Must be consistent between the defining module and any importers.
+     * @param outputFile - Absolute path where the generated code will be written.
+     *   Used to compute relative import paths for stdlib. If not provided, falls
+     *   back to resolving moduleId against cwd.
      */
-    constructor(config: AgencyConfig | undefined, info: ProgramInfo, moduleId: string);
+    constructor(config: AgencyConfig | undefined, info: ProgramInfo, moduleId: string, outputFile?: string);
     private configDefaults;
     /** Convert a TsNode to string (for use in template-based methods) */
     private str;

package/dist/lib/backends/typescriptBuilder.js

@@ -1,3 +1,4 @@
+import path from "path";
 import { formatTypeHint } from "../cli/util.js";
 import { BUILTIN_FUNCTIONS, BUILTIN_TOOLS, BUILTIN_VARIABLES, TYPES_THAT_DONT_TRIGGER_NEW_PART, } from "../config.js";
 import { expressionToString } from "../utils/node.js";
@@ -75,17 +76,22 @@ export class TypeScriptBuilder {
     _sourceMapBuilder = new SourceMapBuilder();
     programInfo;
     moduleId;
+    outputFile;
     /**
      * @param config - Agency compiler configuration (model defaults, logging, etc.)
      * @param info - Pre-collected program metadata (function definitions, graph nodes, imports, type hints)
      * @param moduleId - Unique identifier for this module (e.g., "foo.agency"), used to
      *   namespace global variables in the GlobalStore so that different modules' globals
      *   don't collide. Must be consistent between the defining module and any importers.
+     * @param outputFile - Absolute path where the generated code will be written.
+     *   Used to compute relative import paths for stdlib. If not provided, falls
+     *   back to resolving moduleId against cwd.
      */
-    constructor(config, info, moduleId) {
+    constructor(config, info, moduleId, outputFile) {
         this.agencyConfig = mergeDeep(this.configDefaults(), config || {});
         this.programInfo = info;
         this.moduleId = moduleId;
+        this.outputFile = outputFile;
     }
     configDefaults() {
         return {
@@ -1041,7 +1047,7 @@ export class TypeScriptBuilder {
         return ts.runnerIfElse({ id, branches, elseBranch });
     }
     processImportStatement(node) {
-        const from = toCompiledImportPath(node.modulePath);
+        const from = toCompiledImportPath(node.modulePath, this.outputFile ?? path.resolve(this.moduleId));
         const imports = node.importedNames.map((nameType) => {
             switch (nameType.type) {
                 case "namedImport":
@@ -1092,7 +1098,7 @@ export class TypeScriptBuilder {
         return ts.importDecl({
             importKind: "named",
             names: importNames,
-            from: toCompiledImportPath(node.agencyFile),
+            from: toCompiledImportPath(node.agencyFile, this.outputFile ?? path.resolve(this.moduleId)),
         });
     }
     // ------- TsRaw wrapper methods (template-heavy) -------
@@ -1862,6 +1868,7 @@ export class TypeScriptBuilder {
         const configArg = node.arguments[1];
         let clientConfig;
         let configToolNames = [];
+        let configToolExprs = [];
         if (configArg && configArg.type === "agencyObject") {
             // Extract tools from config object
             const toolsEntry = configArg.entries.find((e) => !("type" in e && e.type === "splat") &&
@@ -1881,6 +1888,10 @@ export class TypeScriptBuilder {
                             configToolNames.push(toolArg.value);
                         }
                     }
+                    else if (item.type === "splat") {
+                        // Pass-through: spread MCP tool arrays (or any other spread) directly
+                        configToolExprs.push(ts.spread(this.processNode(item.value)));
+                    }
                 }
             }
             // Build clientConfig without known keys
@@ -1912,12 +1923,14 @@ export class TypeScriptBuilder {
         const toolNodes = allToolNames.map((name) => $(ts.id("tool"))
             .call([ts.str(name)])
             .done());
+        // Merge registry-resolved tools with pass-through expressions (spreads of MCP tools, etc.)
+        const allToolNodes = [...toolNodes, ...configToolExprs];
         // Merge tools into clientConfig
         let mergedConfig;
-        if (allToolNames.length > 0) {
+        if (allToolNodes.length > 0) {
             // Spread user config and add tools
             mergedConfig = ts.obj([
-                ts.set("tools", ts.arr(toolNodes)),
+                ts.set("tools", ts.arr(allToolNodes)),
                 ts.setSpread(clientConfig),
             ]);
         }
@@ -2418,10 +2431,14 @@ export class TypeScriptBuilder {
             traceConfigFields.traceFile = ts.str(this.agencyConfig.traceFile);
         }
         runtimeCtxArgs.traceConfig = ts.obj(traceConfigFields);
-        let runtimeCtx = ts.statements([
+        const runtimeCtxStatements = [
             ts.constDecl("__globalCtx", ts.new(ts.id("RuntimeContext"), [ts.obj(runtimeCtxArgs)])),
             ts.constDecl("graph", $(ts.runtime.globalCtx).prop("graph").done()),
-        ]);
+        ];
+        if (this.agencyConfig.mcpServers) {
+            runtimeCtxStatements.push(ts.raw(`__globalCtx.createMcpManager(${JSON.stringify(this.agencyConfig.mcpServers)});`));
+        }
+        let runtimeCtx = ts.statements(runtimeCtxStatements);
         return renderImports.default({
             runtimeContextCode: printTs(runtimeCtx),
         });

package/dist/lib/backends/typescriptGenerator/builtins.js

@@ -1,6 +1,7 @@
 import * as builtinFunctionsInput from "../../templates/backends/typescriptGenerator/builtinFunctions/input.js";
 import * as builtinFunctionsRead from "../../templates/backends/typescriptGenerator/builtinFunctions/read.js";
 import * as builtinFunctionsFetchJSON from "../../templates/backends/typescriptGenerator/builtinFunctions/fetchJSON.js";
+import * as builtinFunctionsMcp from "../../templates/backends/typescriptGenerator/builtinFunctions/mcp.js";
 import { BUILTIN_FUNCTIONS } from "../../config.js";
 /**
  * Maps an Agency function name to its TypeScript equivalent
@@ -46,5 +47,7 @@ export function generateBuiltinHelpers(functionsUsed) {
         helpers.push(sleepFunc);
       }
      */
+    const mcpFunc = builtinFunctionsMcp.default({});
+    helpers.push(mcpFunc);
     return helpers.join("\n\n");
 }

package/dist/lib/backends/typescriptGenerator.d.ts

@@ -1,4 +1,4 @@
 import { AgencyProgram } from "../types.js";
 import { type ProgramInfo } from "../programInfo.js";
 import { AgencyConfig } from "../config.js";
-export declare function generateTypeScript(program: AgencyProgram, config?: AgencyConfig, info?: ProgramInfo, moduleId?: string): string;
+export declare function generateTypeScript(program: AgencyProgram, config?: AgencyConfig, info?: ProgramInfo, moduleId?: string, outputFile?: string): string;

package/dist/lib/backends/typescriptGenerator.js

@@ -2,14 +2,14 @@ import { TypescriptPreprocessor } from "../preprocessors/typescriptPreprocessor.
 import { collectProgramInfo } from "../programInfo.js";
 import { TypeScriptBuilder } from "./typescriptBuilder.js";
 import { printTs } from "../ir/prettyPrint.js";
-export function generateTypeScript(program, config, info, moduleId) {
+export function generateTypeScript(program, config, info, moduleId, outputFile) {
     if (!moduleId) {
         throw new Error("moduleId is required for generateTypeScript");
     }
     const programInfo = info ?? collectProgramInfo(program);
     const preprocessor = new TypescriptPreprocessor(program, config, programInfo);
     const preprocessedProgram = preprocessor.preprocess();
-    const builder = new TypeScriptBuilder(config, programInfo, moduleId);
+    const builder = new TypeScriptBuilder(config, programInfo, moduleId, outputFile);
     const ir = builder.build(preprocessedProgram);
     return printTs(ir);
 }

package/dist/lib/cli/commands.js

@@ -1,4 +1,5 @@
 import { generateAgency } from "../backends/agencyGenerator.js";
+import { AgencyConfigSchema } from "../config.js";
 import { generateTypeScript } from "../index.js";
 import { resolveImports } from "../preprocessors/importResolver.js";
 import { collectProgramInfo } from "../programInfo.js";
@@ -26,6 +27,15 @@ export function loadConfig(configPath, verbose = false) {
         try {
             const configContent = fs.readFileSync(finalConfigPath, "utf-8");
             config = JSON.parse(configContent);
+            const parseResult = AgencyConfigSchema.safeParse(config);
+            if (!parseResult.success) {
+                console.error(`Invalid agency.json config:`);
+                for (const issue of parseResult.error.issues) {
+                    console.error(`  - ${issue.path.join(".")}: ${issue.message}`);
+                }
+                process.exit(1);
+            }
+            config = parseResult.data;
             if (config.verbose) {
                 console.log(`Loaded config from ${finalConfigPath}`);
             }
@@ -154,9 +164,16 @@ export function compile(config, inputFile, _outputFile, options) {
             nonAgencyImports.push(node.modulePath);
         }
     });
-    strategy.prepareDependencies(nonAgencyImports, absoluteInputFile);
+    try {
+        strategy.prepareDependencies(nonAgencyImports, absoluteInputFile);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
     const moduleId = path.relative(process.cwd(), absoluteInputFile);
-    const generatedCode = generateTypeScript(resolvedProgram, config, info, moduleId);
+    const absoluteOutputFile = path.resolve(outputFile);
+    const generatedCode = generateTypeScript(resolvedProgram, config, info, moduleId, absoluteOutputFile);
     if (options?.ts) {
         // TypeScript output — add @ts-nocheck so type errors don't block compilation
         fs.writeFileSync(outputFile, "// @ts-nocheck\n" + generatedCode, "utf-8");

package/dist/lib/cli/debug.js

@@ -83,7 +83,14 @@ export async function debug(config, _inputFile, options = {}) {
         let absOutput;
         if (distDir) {
             // distDir mode: import pre-compiled JS from the dist directory
-            const compiledPath = resolveCompiledFile(distDir, inputFile);
+            let compiledPath;
+            try {
+                compiledPath = resolveCompiledFile(distDir, inputFile);
+            }
+            catch (error) {
+                console.error(error instanceof Error ? error.message : String(error));
+                process.exit(1);
+            }
             // Warn if source is newer than compiled output
             const sourceMtime = fs.statSync(inputFile).mtimeMs;
             const compiledMtime = fs.statSync(compiledPath).mtimeMs;

package/dist/lib/config.d.ts

@@ -1,4 +1,6 @@
 import { AgencyNode } from "./types.js";
+import { z } from "zod";
+import type { McpServerConfig } from "./runtime/mcp/types.js";
 export declare const TYPES_THAT_DONT_TRIGGER_NEW_PART: AgencyNode["type"][];
 /**
  * Maps Agency built-in function names to TypeScript equivalents.
@@ -117,4 +119,66 @@ export interface AgencyConfig {
         /** Base URL for source links in generated docs */
         baseUrl?: string;
     };
+    /** MCP server configurations */
+    mcpServers?: Record<string, McpServerConfig>;
 }
+export declare const AgencyConfigSchema: z.ZodObject<{
+    verbose: z.ZodOptional<z.ZodBoolean>;
+    outDir: z.ZodOptional<z.ZodString>;
+    excludeNodeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    excludeBuiltinFunctions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    allowedFetchDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    disallowedFetchDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tarsecTraceHost: z.ZodOptional<z.ZodString>;
+    maxToolCallRounds: z.ZodOptional<z.ZodNumber>;
+    log: z.ZodOptional<z.ZodObject<{
+        host: z.ZodOptional<z.ZodString>;
+        projectId: z.ZodOptional<z.ZodString>;
+        debugMode: z.ZodOptional<z.ZodBoolean>;
+        apiKey: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    client: z.ZodOptional<z.ZodObject<{
+        logLevel: z.ZodOptional<z.ZodEnum<{
+            error: "error";
+            warn: "warn";
+            info: "info";
+            debug: "debug";
+        }>>;
+        defaultModel: z.ZodOptional<z.ZodString>;
+        openAiApiKey: z.ZodOptional<z.ZodString>;
+        googleApiKey: z.ZodOptional<z.ZodString>;
+        statelog: z.ZodOptional<z.ZodObject<{
+            host: z.ZodOptional<z.ZodString>;
+            projectId: z.ZodOptional<z.ZodString>;
+            apiKey: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    strictTypes: z.ZodOptional<z.ZodBoolean>;
+    typeCheck: z.ZodOptional<z.ZodBoolean>;
+    typeCheckStrict: z.ZodOptional<z.ZodBoolean>;
+    restrictImports: z.ZodOptional<z.ZodBoolean>;
+    debugger: z.ZodOptional<z.ZodBoolean>;
+    instrument: z.ZodOptional<z.ZodBoolean>;
+    checkpoints: z.ZodOptional<z.ZodObject<{
+        maxRestores: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    trace: z.ZodOptional<z.ZodBoolean>;
+    traceFile: z.ZodOptional<z.ZodString>;
+    traceDir: z.ZodOptional<z.ZodString>;
+    distDir: z.ZodOptional<z.ZodString>;
+    test: z.ZodOptional<z.ZodObject<{
+        parallel: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    doc: z.ZodOptional<z.ZodObject<{
+        outDir: z.ZodOptional<z.ZodString>;
+        baseUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    mcpServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+        command: z.ZodString;
+        args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"http">;
+        url: z.ZodString;
+    }, z.core.$strict>]>>>;
+}, z.core.$loose>;

package/dist/lib/config.js

@@ -1,3 +1,4 @@
+import { z } from "zod";
 export const TYPES_THAT_DONT_TRIGGER_NEW_PART = [
     "typeAlias",
     "usesTool",
@@ -16,3 +17,46 @@ export const BUILTIN_TOOLS = [
     "readSkill",
 ];
 export const BUILTIN_VARIABLES = ["color"];
+// --- Zod schema for runtime validation of agency.json ---
+const McpStdioServerSchema = z.object({
+    command: z.string(),
+    args: z.array(z.string()).optional(),
+    env: z.record(z.string(), z.string()).optional(),
+}).strict();
+const McpHttpServerSchema = z.object({
+    type: z.literal("http"),
+    url: z.string(),
+}).strict();
+const McpServerSchema = z.union([McpStdioServerSchema, McpHttpServerSchema]);
+export const AgencyConfigSchema = z.object({
+    verbose: z.boolean(),
+    outDir: z.string(),
+    excludeNodeTypes: z.array(z.string()),
+    excludeBuiltinFunctions: z.array(z.string()),
+    allowedFetchDomains: z.array(z.string()),
+    disallowedFetchDomains: z.array(z.string()),
+    tarsecTraceHost: z.string(),
+    maxToolCallRounds: z.number(),
+    log: z.object({ host: z.string(), projectId: z.string(), debugMode: z.boolean(), apiKey: z.string() }).partial(),
+    client: z.object({
+        logLevel: z.enum(["error", "warn", "info", "debug"]),
+        defaultModel: z.string(),
+        openAiApiKey: z.string(),
+        googleApiKey: z.string(),
+        statelog: z.object({ host: z.string(), projectId: z.string(), apiKey: z.string() }).partial(),
+    }).partial(),
+    strictTypes: z.boolean(),
+    typeCheck: z.boolean(),
+    typeCheckStrict: z.boolean(),
+    restrictImports: z.boolean(),
+    debugger: z.boolean(),
+    instrument: z.boolean(),
+    checkpoints: z.object({ maxRestores: z.number() }).partial(),
+    trace: z.boolean(),
+    traceFile: z.string(),
+    traceDir: z.string(),
+    distDir: z.string(),
+    test: z.object({ parallel: z.number() }).partial(),
+    doc: z.object({ outDir: z.string(), baseUrl: z.string() }).partial(),
+    mcpServers: z.record(z.string(), McpServerSchema),
+}).partial().passthrough();

package/dist/lib/config.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/config.test.js

@@ -0,0 +1,64 @@
+import { describe, it, expect } from "vitest";
+import { AgencyConfigSchema } from "./config.js";
+describe("AgencyConfigSchema", () => {
+    it("should accept an empty config", () => {
+        const result = AgencyConfigSchema.safeParse({});
+        expect(result.success).toBe(true);
+    });
+    it("should accept a config with existing fields", () => {
+        const result = AgencyConfigSchema.safeParse({
+            verbose: true,
+            outDir: "dist",
+            maxToolCallRounds: 5,
+        });
+        expect(result.success).toBe(true);
+    });
+    it("should accept a config with stdio MCP server", () => {
+        const result = AgencyConfigSchema.safeParse({
+            mcpServers: {
+                filesystem: {
+                    command: "npx",
+                    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+                    env: { FOO: "bar" },
+                },
+            },
+        });
+        expect(result.success).toBe(true);
+    });
+    it("should accept a config with HTTP MCP server", () => {
+        const result = AgencyConfigSchema.safeParse({
+            mcpServers: {
+                weather: {
+                    type: "http",
+                    url: "https://weather-mcp.example.com/mcp",
+                },
+            },
+        });
+        expect(result.success).toBe(true);
+    });
+    it("should accept a config with mixed MCP servers", () => {
+        const result = AgencyConfigSchema.safeParse({
+            mcpServers: {
+                filesystem: { command: "npx", args: ["server"] },
+                weather: { type: "http", url: "https://example.com/mcp" },
+            },
+        });
+        expect(result.success).toBe(true);
+    });
+    it("should reject an HTTP server missing url", () => {
+        const result = AgencyConfigSchema.safeParse({
+            mcpServers: {
+                bad: { type: "http" },
+            },
+        });
+        expect(result.success).toBe(false);
+    });
+    it("should reject a stdio server missing command", () => {
+        const result = AgencyConfigSchema.safeParse({
+            mcpServers: {
+                bad: { args: ["foo"] },
+            },
+        });
+        expect(result.success).toBe(false);
+    });
+});

package/dist/lib/debugger/uiState.js

@@ -46,10 +46,11 @@ export class UIState {
         // If the moduleId refers to a stdlib file, resolve against the actual
         // stdlib directory (handles npm-installed packages where stdlib lives
         // in node_modules/agency-lang/stdlib/)
-        if (moduleId.includes("stdlib")) {
-            const basename = path.basename(moduleId);
+        const stdlibMatch = moduleId.match(/(?:^|[/\\])stdlib[/\\](.+)$/);
+        if (stdlibMatch) {
+            const stdlibRelativePath = stdlibMatch[1];
             for (const ext of extensions) {
-                const candidate = path.join(getStdlibDir(), basename).replace(/\.agency$/, ext);
+                const candidate = path.join(getStdlibDir(), stdlibRelativePath).replace(/\.agency$/, ext);
                 if (fs.existsSync(candidate))
                     return candidate;
             }

package/dist/lib/importPaths.d.ts

@@ -68,7 +68,11 @@ export declare function resolveAgencyImportPath(importPath: string, fromFile: st
  * Convert an Agency import path to the path that should appear in generated
  * TypeScript import statements.
  *
- * - "std::foo"      -> absolute path to <stdlib-dir>/foo.js
+ * - "std::foo"      -> relative path to <stdlib-dir>/foo.js from the source file
  * - "./foo.agency"  -> "./foo.js" (relative, just extension swap)
+ *
+ * @param fromFile - Absolute path of the source file containing the import.
+ *   Used to compute relative paths for stdlib imports. If not provided,
+ *   falls back to absolute paths.
  */
-export declare function toCompiledImportPath(importPath: string): string;
+export declare function toCompiledImportPath(importPath: string, fromFile?: string): string;

package/dist/lib/importPaths.js

@@ -220,12 +220,23 @@ export function resolveAgencyImportPath(importPath, fromFile) {
  * Convert an Agency import path to the path that should appear in generated
  * TypeScript import statements.
  *
- * - "std::foo"      -> absolute path to <stdlib-dir>/foo.js
+ * - "std::foo"      -> relative path to <stdlib-dir>/foo.js from the source file
  * - "./foo.agency"  -> "./foo.js" (relative, just extension swap)
+ *
+ * @param fromFile - Absolute path of the source file containing the import.
+ *   Used to compute relative paths for stdlib imports. If not provided,
+ *   falls back to absolute paths.
  */
-export function toCompiledImportPath(importPath) {
+export function toCompiledImportPath(importPath, fromFile) {
     if (isStdlibImport(importPath)) {
-        return path.join(STDLIB_DIR, normalizeStdlibPath(importPath) + ".js");
+        const absTarget = path.join(STDLIB_DIR, normalizeStdlibPath(importPath) + ".js");
+        if (fromFile) {
+            let rel = path.relative(path.dirname(fromFile), absTarget).replace(/\\/g, "/");
+            if (!rel.startsWith("."))
+                rel = "./" + rel;
+            return rel;
+        }
+        return absTarget;
     }
     if (isPkgImport(importPath)) {
         // Emit bare specifier — Node resolves it at runtime via node_modules

package/dist/lib/importStrategy.d.ts

@@ -34,4 +34,7 @@ export declare class RunStrategy extends CompileStrategy {
     constructor();
     rewriteImport(modulePath: string, sourceFile: string): string;
     prepareDependencies(imports: string[], sourceFile: string): void;
+    private ensureJsExists;
+    /** Extract relative .js imports from TypeScript source code. */
+    private getLocalJsImports;
 }

package/dist/lib/importStrategy.js

@@ -37,28 +37,53 @@ export class RunStrategy extends CompileStrategy {
         return modulePath.replace(/\.ts$/, ".js");
     }
     prepareDependencies(imports, sourceFile) {
+        const visited = new Set();
         for (const imp of imports) {
             if (!imp.startsWith("./") && !imp.startsWith("../"))
                 continue;
             if (!imp.endsWith(".js"))
                 continue;
             const resolved = path.resolve(path.dirname(sourceFile), imp);
-            if (fs.existsSync(resolved))
-                continue;
-            const tsPath = resolved.replace(/\.js$/, ".ts");
-            if (fs.existsSync(tsPath)) {
-                const tsCode = fs.readFileSync(tsPath, "utf-8");
-                const result = transformSync(tsCode, {
-                    loader: "ts",
-                    format: "esm",
-                    supported: { "top-level-await": true },
-                });
-                fs.writeFileSync(resolved, result.code);
-            }
-            else {
-                throw new Error(`Cannot resolve import '${imp}' from '${sourceFile}'.\n` +
-                    `Tried: ${resolved}, ${tsPath} — neither file exists.`);
+            this.ensureJsExists(resolved, sourceFile, visited);
+        }
+    }
+    ensureJsExists(jsPath, importer, visited) {
+        const normalized = path.normalize(jsPath);
+        if (visited.has(normalized))
+            return;
+        visited.add(normalized);
+        if (fs.existsSync(normalized))
+            return;
+        const tsPath = normalized.replace(/\.js$/, ".ts");
+        if (!fs.existsSync(tsPath)) {
+            throw new Error(`Cannot resolve import '${path.relative(path.dirname(importer), normalized)}' from '${importer}'.\n` +
+                `Tried: ${normalized}, ${tsPath} — neither file exists.`);
+        }
+        // Recursively ensure this file's dependencies exist first
+        const tsCode = fs.readFileSync(tsPath, "utf-8");
+        for (const nestedImp of this.getLocalJsImports(tsCode)) {
+            const nestedResolved = path.resolve(path.dirname(tsPath), nestedImp);
+            this.ensureJsExists(nestedResolved, tsPath, visited);
+        }
+        // Then compile this file
+        const result = transformSync(tsCode, {
+            loader: "ts",
+            format: "esm",
+            supported: { "top-level-await": true },
+        });
+        fs.writeFileSync(normalized, result.code);
+    }
+    /** Extract relative .js imports from TypeScript source code. */
+    getLocalJsImports(code) {
+        const imports = [];
+        const pattern = /\bimport\s+(?:[^'"]+?\s+from\s+)?["']([^"']+)["']/g;
+        let match;
+        while ((match = pattern.exec(code)) !== null) {
+            const specifier = match[1];
+            if ((specifier.startsWith("./") || specifier.startsWith("../")) && specifier.endsWith(".js")) {
+                imports.push(specifier);
             }
         }
+        return imports;
     }
 }

package/dist/lib/runtime/index.d.ts

@@ -35,3 +35,5 @@ export { DebuggerState } from "../debugger/debuggerState.js";
 export { success, failure, isSuccess, isFailure, __pipeBind, __tryCall, __catchResult, } from "./result.js";
 export type { ResultValue, ResultSuccess, ResultFailure } from "./result.js";
 export { Schema, __validateType } from "./schema.js";
+export { McpManager } from "./mcp/mcpManager.js";
+export type { McpServerConfig, McpTool } from "./mcp/types.js";

package/dist/lib/runtime/index.js

@@ -24,3 +24,4 @@ export { debugStep } from "./debugger.js";
 export { DebuggerState } from "../debugger/debuggerState.js";
 export { success, failure, isSuccess, isFailure, __pipeBind, __tryCall, __catchResult, } from "./result.js";
 export { Schema, __validateType } from "./schema.js";
+export { McpManager } from "./mcp/mcpManager.js";

package/dist/lib/runtime/mcp/__tests__/testServer.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/runtime/mcp/__tests__/testServer.js

@@ -0,0 +1,14 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const server = new McpServer({
+    name: "test-server",
+    version: "1.0.0",
+});
+server.tool("add", "Add two numbers together", { a: z.number(), b: z.number() }, async ({ a, b }) => {
+    return {
+        content: [{ type: "text", text: String(a + b) }],
+    };
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/lib/runtime/mcp/mcp.integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/runtime/mcp/mcp.integration.test.js

@@ -0,0 +1,37 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { McpManager } from "./mcpManager.js";
+import { mcpToolToRegistryEntry } from "./toolAdapter.js";
+import path from "path";
+import { fileURLToPath } from "url";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEST_SERVER_PATH = path.join(__dirname, "__tests__", "testServer.ts");
+describe("MCP integration", () => {
+    let manager;
+    afterEach(async () => {
+        if (manager) {
+            await manager.disconnectAll();
+        }
+    });
+    it("tools survive JSON serialization round-trip and remain callable", async () => {
+        manager = new McpManager({
+            test: {
+                command: "npx",
+                args: ["tsx", TEST_SERVER_PATH],
+            },
+        });
+        const result = await manager.getTools("test");
+        expect(result.success).toBe(true);
+        if (!result.success)
+            throw new Error("unreachable");
+        const tools = result.value;
+        const serialized = JSON.stringify(tools);
+        const deserialized = JSON.parse(serialized);
+        expect(deserialized[0].__mcpTool).toBe(true);
+        expect(deserialized[0].serverName).toBe("test");
+        expect(deserialized[0].name).toBe("test__add");
+        // After deserialization, we can still build a working handler
+        const entry = mcpToolToRegistryEntry(deserialized[0], (serverName, toolName, args) => manager.callTool(serverName, toolName, args));
+        const toolResult = await entry.handler.execute(3, 4, { ctx: null });
+        expect(toolResult).toContain("7");
+    });
+});

package/dist/lib/runtime/mcp/mcpConnection.d.ts

@@ -0,0 +1,14 @@
+import type { McpServerConfig, McpTool } from "./types.js";
+export declare class McpConnection {
+    private client;
+    private serverName;
+    private config;
+    private tools;
+    private connected;
+    constructor(serverName: string, config: McpServerConfig);
+    connect(): Promise<void>;
+    getTools(): McpTool[];
+    callTool(toolName: string, args: Record<string, unknown>): Promise<string>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+}