@execbox/core 0.6.0 → 0.7.0

package/README.md

@@ -1,6 +1,8 @@
 # @execbox/core
 
-Core execution contract for execbox. Use it to resolve host tools into callable guest namespaces, validate tool boundaries, and bridge MCP servers or clients into the same execution model.
+Provider, schema, and MCP adapter contracts for execbox. Use it to resolve host
+tools into callable guest namespaces before running code with an executor such
+as `@execbox/quickjs`.
 
 [![npm version](https://img.shields.io/npm/v/%40execbox%2Fcore?style=flat-square)](https://www.npmjs.com/package/@execbox/core)
 [![License](https://img.shields.io/github/license/aallam/execbox?style=flat-square)](https://github.com/aallam/execbox/blob/main/LICENSE)
@@ -10,11 +12,12 @@ Core execution contract for execbox. Use it to resolve host tools into callable
 
 - you want to expose host capabilities to guest code through explicit tool providers
 - you want one execution contract across inline and worker-hosted QuickJS
-- you want to wrap MCP servers or clients into callable namespaces instead of exposing raw tool loops
+- you want to wrap MCP servers or clients into callable namespaces
 
 ## Pair It With an Executor
 
-`@execbox/core` defines the provider and tool boundary, but it does not execute guest code on its own.
+`@execbox/core` defines the provider and tool boundary. Guest execution happens
+in an executor package.
 
 | Package                                                              | Start here when                                                 |
 | -------------------------------------------------------------------- | --------------------------------------------------------------- |
@@ -28,12 +31,28 @@ Most users start with QuickJS:
 npm install @execbox/core @execbox/quickjs
 ```
 
+## Provider Boundary
+
+Providers are explicit capability grants. `resolveProvider()` validates the
+namespace, normalizes tool schemas, creates guest-safe tool names, wraps tool
+execution with schema checks, and keeps original-to-safe name maps for callers
+that need to explain MCP or generated tool names.
+
+Tool inputs and results should be JSON-compatible data. Keep host-only values
+such as clients, handles, secrets, and tenant routing inside the tool
+implementation.
+
 ## Runtime Implementer Surface
 
 Most application code can skip this section.
 
 Application code should usually import from `@execbox/core` or `@execbox/core/mcp`.
-The `@execbox/core/protocol` and `@execbox/core/runtime` subpaths exist for execbox-owned runtime packages. `@execbox/core/protocol` carries the worker-hosted QuickJS message contract, while `@execbox/core/runtime` contains the manifest dispatcher, runtime option defaults, timeout helpers, log formatting, code normalization, and error normalization used to keep runtime implementations aligned.
+The `@execbox/core/protocol` and `@execbox/core/runtime` subpaths exist for
+execbox-owned runtime packages. `@execbox/core/protocol` carries the
+worker-hosted QuickJS message contract, while `@execbox/core/runtime` contains
+the manifest dispatcher, runtime option defaults, timeout helpers, log
+formatting, code normalization, and error normalization used to keep runtime
+implementations aligned.
 
 ## Smallest Working Usage
 
@@ -69,7 +88,8 @@ console.log(result);
 
 ## MCP Support
 
-Use `@execbox/core/mcp` when you want MCP on either side of the boundary:
+Use `@execbox/core/mcp` when you want MCP on either side of the provider
+boundary:
 
 - wrap an upstream MCP server or client into a provider with `createMcpToolProvider()` or `openMcpToolProvider()`
 - expose execbox code execution back out through an MCP server with `codeMcpServer()`
@@ -84,8 +104,9 @@ Use `@execbox/core/mcp` when you want MCP on either side of the boundary:
 ## Read Next
 
 - [Getting Started](https://execbox.aallam.com/getting-started)
+- [Providers & Tools](https://execbox.aallam.com/providers-and-tools)
+- [Runtime Choices](https://execbox.aallam.com/runtime-choices)
+- [MCP Integration](https://execbox.aallam.com/mcp-integration)
 - [Examples](https://execbox.aallam.com/examples)
 - [Security & Boundaries](https://execbox.aallam.com/security)
 - [Architecture Overview](https://execbox.aallam.com/architecture/)
-- [Core Architecture](https://execbox.aallam.com/architecture/execbox-core)
-- [MCP And Protocol](https://execbox.aallam.com/architecture/execbox-mcp-and-protocol)

package/dist/{errors-DlbJQYs7.d.ts → errors-BIWv-QIC.d.ts}

@@ -2,7 +2,7 @@
  * @packageDocumentation
  * Public TypeScript declarations for this package entrypoint.
  */
-import { u as ExecuteErrorCode } from "./runner-ClFrFnz9.js";
+import { u as ExecuteErrorCode } from "./runner-DXLu0eJV.js";
 
 //#region src/errors.d.ts
 
@@ -26,4 +26,4 @@ declare function isExecuteFailure(value: unknown): value is ExecuteFailure;
 declare function isJsonSerializable(value: unknown, active?: Set<object>, memo?: WeakSet<object>): boolean;
 //#endregion
 export { isExecuteFailure as n, isJsonSerializable as r, ExecuteFailure as t };
-//# sourceMappingURL=errors-DlbJQYs7.d.ts.map
+//# sourceMappingURL=errors-BIWv-QIC.d.ts.map

package/dist/{errors-DlbJQYs7.d.ts.map → errors-BIWv-QIC.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"errors-DlbJQYs7.d.ts","names":[],"sources":["../src/errors.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;AAKA,CAAA,CAAA;AACQ,OAAA,CAAA,KAAA,CADK,cAAA,CAAA,OAAA,CAAuB,KAAA,CAC5B;EAKY,IAAA,CAAA,CALZ,gBAKY;EANgB,CAAA,CAAA;;AAgBpC,CAAA,CAAA,CAAA,CAAA;EAOgB,WAAA,CAAA,IAAA,CAAA,CAjBI,gBAmBZ,CAAA,CAAA,OACF,CAAA,CAAA,MAAA,CAAA;;;;;iBAVU,gBAAA,2BAA2C;;;;iBAO3C,kBAAA,0BAER,oBACF"}
+{"version":3,"file":"errors-BIWv-QIC.d.ts","names":[],"sources":["../src/errors.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;AAKA,CAAA,CAAA;AACQ,OAAA,CAAA,KAAA,CADK,cAAA,CAAA,OAAA,CAAuB,KAAA,CAC5B;EAKY,IAAA,CAAA,CALZ,gBAKY;EANgB,CAAA,CAAA;;AAgBpC,CAAA,CAAA,CAAA,CAAA;EAOgB,WAAA,CAAA,IAAA,CAAA,CAjBI,gBAmBZ,CAAA,CAAA,OACF,CAAA,CAAA,MAAA,CAAA;;;;;iBAVU,gBAAA,2BAA2C;;;;iBAO3C,kBAAA,0BAER,oBACF"}

package/dist/{errors-B9ADBuDH.d.cts → errors-y4C-EIWT.d.cts}

@@ -2,7 +2,7 @@
  * @packageDocumentation
  * Public TypeScript declarations for this package entrypoint.
  */
-import { u as ExecuteErrorCode } from "./runner-DSgvu6Ad.cjs";
+import { u as ExecuteErrorCode } from "./runner-Cy18Z0u0.cjs";
 
 //#region src/errors.d.ts
 
@@ -26,4 +26,4 @@ declare function isExecuteFailure(value: unknown): value is ExecuteFailure;
 declare function isJsonSerializable(value: unknown, active?: Set<object>, memo?: WeakSet<object>): boolean;
 //#endregion
 export { isExecuteFailure as n, isJsonSerializable as r, ExecuteFailure as t };
-//# sourceMappingURL=errors-B9ADBuDH.d.cts.map
+//# sourceMappingURL=errors-y4C-EIWT.d.cts.map

package/dist/{errors-B9ADBuDH.d.cts.map → errors-y4C-EIWT.d.cts.map}

@@ -1 +1 @@
-{"version":3,"file":"errors-B9ADBuDH.d.cts","names":[],"sources":["../src/errors.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;AAKA,CAAA,CAAA;AACQ,OAAA,CAAA,KAAA,CADK,cAAA,CAAA,OAAA,CAAuB,KAAA,CAC5B;EAKY,IAAA,CAAA,CALZ,gBAKY;EANgB,CAAA,CAAA;;AAgBpC,CAAA,CAAA,CAAA,CAAA;EAOgB,WAAA,CAAA,IAAA,CAAA,CAjBI,gBAmBZ,CAAA,CAAA,OACF,CAAA,CAAA,MAAA,CAAA;;;;;iBAVU,gBAAA,2BAA2C;;;;iBAO3C,kBAAA,0BAER,oBACF"}
+{"version":3,"file":"errors-y4C-EIWT.d.cts","names":[],"sources":["../src/errors.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;AAKA,CAAA,CAAA;AACQ,OAAA,CAAA,KAAA,CADK,cAAA,CAAA,OAAA,CAAuB,KAAA,CAC5B;EAKY,IAAA,CAAA,CALZ,gBAKY;EANgB,CAAA,CAAA;;AAgBpC,CAAA,CAAA,CAAA,CAAA;EAOgB,WAAA,CAAA,IAAA,CAAA,CAjBI,gBAmBZ,CAAA,CAAA,OACF,CAAA,CAAA,MAAA,CAAA;;;;;iBAVU,gBAAA,2BAA2C;;;;iBAO3C,kBAAA,0BAER,oBACF"}

package/dist/{executor-B7q7K_27.d.ts → executor-BOTd9xNK.d.ts}

@@ -2,7 +2,7 @@
  * @packageDocumentation
  * Public TypeScript declarations for this package entrypoint.
  */
-import { d as ExecuteResult, m as ResolvedToolProvider, t as ExecutionOptions } from "./runner-ClFrFnz9.js";
+import { d as ExecuteResult, m as ResolvedToolProvider, t as ExecutionOptions } from "./runner-DXLu0eJV.js";
 
 //#region src/executor/executor.d.ts
 
@@ -26,4 +26,4 @@ interface Executor {
 }
 //#endregion
 export { ExecutorPoolOptions as n, Executor as t };
-//# sourceMappingURL=executor-B7q7K_27.d.ts.map
+//# sourceMappingURL=executor-BOTd9xNK.d.ts.map

package/dist/{executor-B7q7K_27.d.ts.map → executor-BOTd9xNK.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"executor-B7q7K_27.d.ts","names":[],"sources":["../src/executor/executor.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAOA,CAAA,CAAA,CAAA,QAAA,CAAA,OAAA,CAAA,QAAA,CAAA,GAAA,CAAA,QAAA,CAAA,eAAA,CAAA,IAAA,CAAA,GAAA,CAAA;AAUA,CAAA,CAAA,CAAA,IAAA,CAAA,IAAA,CAAA,MAAA,CAAA,KAAA,CAAA,KAAA,CAAA,QAAA,CAAA,CAAA,CAAA,KAAA,CAAA,KAAA,CAAA,OAAA,CAAA,GAAA,CAAA,SAAA;;AAIc,SAAA,CAdG,mBAAA,CAcH;EACD,aAAA,CAAA,CAAA,CAAA,MAAA;EAAR,OAAA,CAAA,CAAA,MAAA;EACS,OAAA,CAAA,CAAA,CAAA,MAAA;EACc,OAAA,CAAA,CAAA,CAAA,OAAA,CAAA,CAAA,CAAA,MAAA;;;;;UAPX,QAAA;mCAGF,kCACD,mBACT,QAAQ;cACC;4BACc"}
+{"version":3,"file":"executor-BOTd9xNK.d.ts","names":[],"sources":["../src/executor/executor.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAOA,CAAA,CAAA,CAAA,QAAA,CAAA,OAAA,CAAA,QAAA,CAAA,GAAA,CAAA,QAAA,CAAA,eAAA,CAAA,IAAA,CAAA,GAAA,CAAA;AAUA,CAAA,CAAA,CAAA,IAAA,CAAA,IAAA,CAAA,MAAA,CAAA,KAAA,CAAA,KAAA,CAAA,QAAA,CAAA,CAAA,CAAA,KAAA,CAAA,KAAA,CAAA,OAAA,CAAA,GAAA,CAAA,SAAA;;AAIc,SAAA,CAdG,mBAAA,CAcH;EACD,aAAA,CAAA,CAAA,CAAA,MAAA;EAAR,OAAA,CAAA,CAAA,MAAA;EACS,OAAA,CAAA,CAAA,CAAA,MAAA;EACc,OAAA,CAAA,CAAA,CAAA,OAAA,CAAA,CAAA,CAAA,MAAA;;;;;UAPX,QAAA;mCAGF,kCACD,mBACT,QAAQ;cACC;4BACc"}

package/dist/{executor-BsE5nF-j.d.cts → executor-CtbrvTQ_.d.cts}

@@ -2,7 +2,7 @@
  * @packageDocumentation
  * Public TypeScript declarations for this package entrypoint.
  */
-import { d as ExecuteResult, m as ResolvedToolProvider, t as ExecutionOptions } from "./runner-DSgvu6Ad.cjs";
+import { d as ExecuteResult, m as ResolvedToolProvider, t as ExecutionOptions } from "./runner-Cy18Z0u0.cjs";
 
 //#region src/executor/executor.d.ts
 
@@ -26,4 +26,4 @@ interface Executor {
 }
 //#endregion
 export { ExecutorPoolOptions as n, Executor as t };
-//# sourceMappingURL=executor-BsE5nF-j.d.cts.map
+//# sourceMappingURL=executor-CtbrvTQ_.d.cts.map

package/dist/{executor-BsE5nF-j.d.cts.map → executor-CtbrvTQ_.d.cts.map}

@@ -1 +1 @@
-{"version":3,"file":"executor-BsE5nF-j.d.cts","names":[],"sources":["../src/executor/executor.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAOA,CAAA,CAAA,CAAA,QAAA,CAAA,OAAA,CAAA,QAAA,CAAA,GAAA,CAAA,QAAA,CAAA,eAAA,CAAA,IAAA,CAAA,GAAA,CAAA;AAUA,CAAA,CAAA,CAAA,IAAA,CAAA,IAAA,CAAA,MAAA,CAAA,KAAA,CAAA,KAAA,CAAA,QAAA,CAAA,CAAA,CAAA,KAAA,CAAA,KAAA,CAAA,OAAA,CAAA,GAAA,CAAA,SAAA;;AAIc,SAAA,CAdG,mBAAA,CAcH;EACD,aAAA,CAAA,CAAA,CAAA,MAAA;EAAR,OAAA,CAAA,CAAA,MAAA;EACS,OAAA,CAAA,CAAA,CAAA,MAAA;EACc,OAAA,CAAA,CAAA,CAAA,OAAA,CAAA,CAAA,CAAA,MAAA;;;;;UAPX,QAAA;mCAGF,kCACD,mBACT,QAAQ;cACC;4BACc"}
+{"version":3,"file":"executor-CtbrvTQ_.d.cts","names":[],"sources":["../src/executor/executor.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAOA,CAAA,CAAA,CAAA,QAAA,CAAA,OAAA,CAAA,QAAA,CAAA,GAAA,CAAA,QAAA,CAAA,eAAA,CAAA,IAAA,CAAA,GAAA,CAAA;AAUA,CAAA,CAAA,CAAA,IAAA,CAAA,IAAA,CAAA,MAAA,CAAA,KAAA,CAAA,KAAA,CAAA,QAAA,CAAA,CAAA,CAAA,KAAA,CAAA,KAAA,CAAA,OAAA,CAAA,GAAA,CAAA,SAAA;;AAIc,SAAA,CAdG,mBAAA,CAcH;EACD,aAAA,CAAA,CAAA,CAAA,MAAA;EAAR,OAAA,CAAA,CAAA,MAAA;EACS,OAAA,CAAA,CAAA,CAAA,MAAA;EACc,OAAA,CAAA,CAAA,CAAA,OAAA,CAAA,CAAA,CAAA,MAAA;;;;;UAPX,QAAA;mCAGF,kCACD,mBACT,QAAQ;cACC;4BACc"}

package/dist/index.cjs

@@ -1,4 +1,4 @@
-const require_resolveProvider = require('./resolveProvider-CszBWDOY.cjs');
+const require_resolveProvider = require('./resolveProvider-DFAg6No5.cjs');
 const require_errors = require('./errors-xD8r6fCf.cjs');
 
 exports.ExecuteFailure = require_errors.ExecuteFailure;

package/dist/index.d.cts

@@ -2,9 +2,9 @@
  * @packageDocumentation
  * Public TypeScript declarations for this package entrypoint.
  */
-import { _ as ToolProvider, d as ExecuteResult, f as JsonSchema, g as ToolExecutionContext, h as ToolDescriptor, l as ExecuteError, m as ResolvedToolProvider, n as ExecutorRuntimeOptions, p as ResolvedToolDescriptor, t as ExecutionOptions, u as ExecuteErrorCode, v as ToolSchema } from "./runner-DSgvu6Ad.cjs";
-import { n as ExecutorPoolOptions, t as Executor } from "./executor-BsE5nF-j.cjs";
-import { n as isExecuteFailure, t as ExecuteFailure } from "./errors-B9ADBuDH.cjs";
+import { _ as ToolExecutionContext, d as ExecuteResult, f as JsonSchema, g as ToolDescriptor, h as ToolAnnotations, l as ExecuteError, m as ResolvedToolProvider, n as ExecutorRuntimeOptions, p as ResolvedToolDescriptor, t as ExecutionOptions, u as ExecuteErrorCode, v as ToolProvider, y as ToolSchema } from "./runner-Cy18Z0u0.cjs";
+import { n as ExecutorPoolOptions, t as Executor } from "./executor-CtbrvTQ_.cjs";
+import { n as isExecuteFailure, t as ExecuteFailure } from "./errors-y4C-EIWT.cjs";
 
 //#region src/provider/resolveProvider.d.ts
 /**
@@ -12,5 +12,5 @@ import { n as isExecuteFailure, t as ExecuteFailure } from "./errors-B9ADBuDH.cj
  */
 declare function resolveProvider(provider: ToolProvider): ResolvedToolProvider;
 //#endregion
-export { type ExecuteError, type ExecuteErrorCode, ExecuteFailure, type ExecuteResult, type ExecutionOptions, type Executor, type ExecutorPoolOptions, type ExecutorRuntimeOptions, type JsonSchema, type ResolvedToolDescriptor, type ResolvedToolProvider, type ToolDescriptor, type ToolExecutionContext, type ToolProvider, type ToolSchema, isExecuteFailure, resolveProvider };
+export { type ExecuteError, type ExecuteErrorCode, ExecuteFailure, type ExecuteResult, type ExecutionOptions, type Executor, type ExecutorPoolOptions, type ExecutorRuntimeOptions, type JsonSchema, type ResolvedToolDescriptor, type ResolvedToolProvider, type ToolAnnotations, type ToolDescriptor, type ToolExecutionContext, type ToolProvider, type ToolSchema, isExecuteFailure, resolveProvider };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../src/provider/resolveProvider.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;iBA4CgB,eAAA,WAA0B,eAAe"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/provider/resolveProvider.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;iBAgFgB,eAAA,WAA0B,eAAe"}

package/dist/index.d.ts

@@ -2,9 +2,9 @@
  * @packageDocumentation
  * Public TypeScript declarations for this package entrypoint.
  */
-import { _ as ToolProvider, d as ExecuteResult, f as JsonSchema, g as ToolExecutionContext, h as ToolDescriptor, l as ExecuteError, m as ResolvedToolProvider, n as ExecutorRuntimeOptions, p as ResolvedToolDescriptor, t as ExecutionOptions, u as ExecuteErrorCode, v as ToolSchema } from "./runner-ClFrFnz9.js";
-import { n as ExecutorPoolOptions, t as Executor } from "./executor-B7q7K_27.js";
-import { n as isExecuteFailure, t as ExecuteFailure } from "./errors-DlbJQYs7.js";
+import { _ as ToolExecutionContext, d as ExecuteResult, f as JsonSchema, g as ToolDescriptor, h as ToolAnnotations, l as ExecuteError, m as ResolvedToolProvider, n as ExecutorRuntimeOptions, p as ResolvedToolDescriptor, t as ExecutionOptions, u as ExecuteErrorCode, v as ToolProvider, y as ToolSchema } from "./runner-DXLu0eJV.js";
+import { n as ExecutorPoolOptions, t as Executor } from "./executor-BOTd9xNK.js";
+import { n as isExecuteFailure, t as ExecuteFailure } from "./errors-BIWv-QIC.js";
 
 //#region src/provider/resolveProvider.d.ts
 /**
@@ -12,5 +12,5 @@ import { n as isExecuteFailure, t as ExecuteFailure } from "./errors-DlbJQYs7.js
  */
 declare function resolveProvider(provider: ToolProvider): ResolvedToolProvider;
 //#endregion
-export { type ExecuteError, type ExecuteErrorCode, ExecuteFailure, type ExecuteResult, type ExecutionOptions, type Executor, type ExecutorPoolOptions, type ExecutorRuntimeOptions, type JsonSchema, type ResolvedToolDescriptor, type ResolvedToolProvider, type ToolDescriptor, type ToolExecutionContext, type ToolProvider, type ToolSchema, isExecuteFailure, resolveProvider };
+export { type ExecuteError, type ExecuteErrorCode, ExecuteFailure, type ExecuteResult, type ExecutionOptions, type Executor, type ExecutorPoolOptions, type ExecutorRuntimeOptions, type JsonSchema, type ResolvedToolDescriptor, type ResolvedToolProvider, type ToolAnnotations, type ToolDescriptor, type ToolExecutionContext, type ToolProvider, type ToolSchema, isExecuteFailure, resolveProvider };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/provider/resolveProvider.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;iBA4CgB,eAAA,WAA0B,eAAe"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/provider/resolveProvider.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;iBAgFgB,eAAA,WAA0B,eAAe"}

package/dist/index.js

@@ -1,4 +1,4 @@
 import { n as isExecuteFailure, t as ExecuteFailure } from "./errors-DdWVEGU8.js";
-import { t as resolveProvider } from "./resolveProvider-Bfj27oYs.js";
+import { t as resolveProvider } from "./resolveProvider-CMrXPuTx.js";
 
 export { ExecuteFailure, isExecuteFailure, resolveProvider };

package/dist/mcp/index.cjs

@@ -1,4 +1,4 @@
-const require_resolveProvider = require('../resolveProvider-CszBWDOY.cjs');
+const require_resolveProvider = require('../resolveProvider-DFAg6No5.cjs');
 require('../errors-xD8r6fCf.cjs');
 let zod = require("zod");
 zod = require_resolveProvider.__toESM(zod);
@@ -25,16 +25,26 @@ const MCP_CALL_TOOL_RESULT_TYPE = [
 	"};"
 ].join("\n");
 /**
+* Generates one wrapped MCP tool declaration exposed to guest code.
+*/
+function generateMcpWrappedToolType(provider, safeName) {
+	const tool = provider.tools[safeName];
+	if (!tool) throw new Error(`Unknown wrapped MCP tool: ${safeName}`);
+	return [require_resolveProvider.renderDocComment([...tool.description ? [tool.description, ""] : [], "Wrapped MCP tool. Inspect structuredContent first, then fall back to content text items."]), `function ${safeName}(input: ${require_resolveProvider.schemaToType(tool.inputSchema)}): Promise<McpCallToolResult>;`].filter(Boolean).join("\n");
+}
+/**
 * Generates the wrapped MCP tool namespace declarations exposed to guest code.
 */
 function generateMcpWrappedToolTypes(provider) {
-	const declarations = [MCP_CALL_TOOL_RESULT_TYPE];
-	for (const [safeName, tool] of Object.entries(provider.tools)) {
-		const comment = require_resolveProvider.renderDocComment([...tool.description ? [tool.description, ""] : [], "Wrapped MCP tool. Inspect structuredContent first, then fall back to content text items."]);
-		declarations.push([comment, `function ${safeName}(input: ${require_resolveProvider.schemaToType(tool.inputSchema)}): Promise<McpCallToolResult>;`].filter(Boolean).join("\n"));
-	}
+	const declarations = [MCP_CALL_TOOL_RESULT_TYPE, ...Object.keys(provider.tools).map((safeName) => generateMcpWrappedToolType(provider, safeName))];
 	return require_resolveProvider.renderNamespaceDeclaration(provider.name, declarations);
 }
+/**
+* Generates the wrapped MCP tool namespace declaration for one selected tool.
+*/
+function generateMcpWrappedSingleToolTypes(provider, safeName) {
+	return require_resolveProvider.renderNamespaceDeclaration(provider.name, [MCP_CALL_TOOL_RESULT_TYPE, generateMcpWrappedToolType(provider, safeName)]);
+}
 
 //#endregion
 //#region src/mcp/createMcpToolProvider.ts
@@ -53,6 +63,9 @@ async function closeAll(closers) {
 	const rejected = (await Promise.allSettled(closers.map((close) => close()))).find((result) => result.status === "rejected");
 	if (rejected) throw rejected.reason;
 }
+function asJsonSchema(schema) {
+	return typeof schema === "object" && schema !== null ? schema : void 0;
+}
 async function openMcpToolClient(source, clientInfo) {
 	if ("client" in source) return {
 		client: source.client,
@@ -86,11 +99,13 @@ async function openMcpToolProvider(source, options = {}) {
 	const connection = await openMcpToolClient(source, options.clientInfo ?? DEFAULT_MCP_TOOL_CLIENT_INFO);
 	try {
 		const toolsResponse = await connection.client.listTools();
+		const toolsByOriginalName = new Map(toolsResponse.tools.map((tool) => [tool.name, tool]));
 		const provider = {
 			name: options.namespace ?? "mcp",
 			tools: {}
 		};
 		for (const tool of toolsResponse.tools) provider.tools[tool.name] = {
+			annotations: tool.annotations,
 			description: tool.description,
 			execute: async (input, context) => {
 				const argumentsObject = typeof input === "object" && input !== null ? input : void 0;
@@ -102,13 +117,25 @@ async function openMcpToolProvider(source, options = {}) {
 			inputSchema: tool.inputSchema
 		};
 		const resolvedProvider = require_resolveProvider.resolveProvider(provider);
+		const toolDefinitions = Object.fromEntries(Object.entries(resolvedProvider.tools).map(([safeName, descriptor]) => {
+			const upstreamTool = toolsByOriginalName.get(descriptor.originalName);
+			return [safeName, {
+				annotations: descriptor.annotations,
+				description: descriptor.description,
+				inputSchema: descriptor.inputSchema,
+				originalName: descriptor.originalName,
+				outputSchema: asJsonSchema(upstreamTool?.outputSchema),
+				safeName: descriptor.safeName
+			}];
+		}));
 		return {
 			close: connection.close,
 			provider: {
 				...resolvedProvider,
 				types: generateMcpWrappedToolTypes(resolvedProvider)
 			},
-			serverInfo: getMcpToolSourceServerInfo(source)
+			serverInfo: getMcpToolSourceServerInfo(source),
+			toolDefinitions
 		};
 	} catch (error) {
 		await connection.close().catch(() => {});
@@ -126,6 +153,18 @@ async function createMcpToolProvider(source, options = {}) {
 //#endregion
 //#region src/mcp/codeMcpServer.ts
 const DEFAULT_MAX_TEXT_CHARS = 24e3;
+const CODE_EXECUTION_TOOL_ANNOTATIONS = {
+	destructiveHint: true,
+	idempotentHint: false,
+	openWorldHint: true,
+	readOnlyHint: false
+};
+const READ_ONLY_TOOL_ANNOTATIONS = {
+	destructiveHint: false,
+	idempotentHint: true,
+	openWorldHint: false,
+	readOnlyHint: true
+};
 const DEFAULT_MCP_CODE_WRAPPER_SERVER_INFO = {
 	name: "mcp-code-wrapper",
 	version: "0.0.0"
@@ -136,32 +175,41 @@ function truncateText(text, maxTextChars) {
 function renderText(value, maxTextChars) {
 	return truncateText(JSON.stringify(value, null, 2), maxTextChars);
 }
-function searchTools(provider, query, limit) {
+function searchTools(toolDefinitions, namespace, query, limit) {
 	const normalizedQuery = query?.toLowerCase().trim();
-	const matches = Object.entries(provider.tools).map(([safeName, descriptor]) => ({
-		description: descriptor.description,
-		inputSchema: descriptor.inputSchema,
-		originalName: descriptor.originalName,
-		outputSchema: descriptor.outputSchema,
-		safeName
-	})).filter((tool) => {
-		if (!normalizedQuery) return true;
-		return [
-			tool.originalName,
-			tool.safeName,
-			tool.description ?? ""
-		].some((field) => field.toLowerCase().includes(normalizedQuery));
-	}).slice(0, limit);
 	return {
-		namespace: provider.name,
-		originalToSafeName: provider.originalToSafeName,
-		safeToOriginalName: provider.safeToOriginalName,
-		tools: matches,
-		types: provider.types
+		namespace,
+		tools: Object.values(toolDefinitions).filter((tool) => {
+			if (!normalizedQuery) return true;
+			return [
+				tool.originalName,
+				tool.safeName,
+				tool.description ?? ""
+			].some((field) => field.toLowerCase().includes(normalizedQuery));
+		}).slice(0, limit).map((tool) => ({
+			annotations: tool.annotations,
+			description: tool.description,
+			originalName: tool.originalName,
+			safeName: tool.safeName
+		}))
+	};
+}
+function getToolDetails(provider, toolDefinitions, safeName) {
+	const tool = toolDefinitions[safeName];
+	if (!tool) throw new Error(`Unknown wrapped MCP tool: ${safeName}`);
+	return {
+		annotations: tool.annotations,
+		description: tool.description,
+		inputSchema: tool.inputSchema,
+		originalName: tool.originalName,
+		outputSchema: tool.outputSchema,
+		safeName: tool.safeName,
+		types: generateMcpWrappedSingleToolTypes(provider, safeName)
 	};
 }
 function registerExecuteTool(server, name, provider, executor, maxTextChars, description) {
 	server.registerTool.bind(server)(name, {
+		annotations: CODE_EXECUTION_TOOL_ANNOTATIONS,
 		description,
 		inputSchema: { code: zod.string() }
 	}, async (args) => {
@@ -176,15 +224,32 @@ function registerExecuteTool(server, name, provider, executor, maxTextChars, des
 		};
 	});
 }
-function registerSearchTool(server, name, provider, maxTextChars) {
+function registerSearchTool(server, name, namespace, toolDefinitions, maxTextChars) {
 	server.registerTool.bind(server)(name, {
-		description: `Search wrapped MCP tools exposed under the ${provider.name} namespace.`,
+		annotations: READ_ONLY_TOOL_ANNOTATIONS,
+		description: `Search wrapped MCP tools exposed under the ${namespace} namespace. Returns concise catalog entries only; call the details tool for schemas.`,
 		inputSchema: {
 			limit: zod.number().int().optional(),
 			query: zod.string().optional()
 		}
 	}, async (args) => {
-		const structuredContent = searchTools(provider, args.query, args.limit ?? 20);
+		const structuredContent = searchTools(toolDefinitions, namespace, args.query, args.limit ?? 20);
+		return {
+			content: [{
+				text: renderText(structuredContent, maxTextChars),
+				type: "text"
+			}],
+			structuredContent
+		};
+	});
+}
+function registerDetailsTool(server, name, provider, toolDefinitions, maxTextChars) {
+	server.registerTool.bind(server)(name, {
+		annotations: READ_ONLY_TOOL_ANNOTATIONS,
+		description: `Return the full schema and generated TypeScript declaration for one wrapped ${provider.name} MCP tool.`,
+		inputSchema: { safeName: zod.string() }
+	}, async (args) => {
+		const structuredContent = getToolDetails(provider, toolDefinitions, args.safeName);
 		return {
 			content: [{
 				text: renderText(structuredContent, maxTextChars),
@@ -211,8 +276,9 @@ function attachOwnedClose(server, closeOwnedResources) {
 */
 async function codeMcpServer(source, options) {
 	const maxTextChars = options.maxTextChars ?? DEFAULT_MAX_TEXT_CHARS;
-	const mode = options.mode ?? "both";
+	const mode = options.mode ?? "progressive";
 	const names = {
+		details: options.names?.details ?? "mcp_get_tool_details",
 		execute: options.names?.execute ?? "mcp_execute_code",
 		search: options.names?.search ?? "mcp_search_tools",
 		single: options.names?.single ?? "mcp_code"
@@ -224,9 +290,10 @@ async function codeMcpServer(source, options) {
 	const provider = handle.provider;
 	const server = new __modelcontextprotocol_sdk_server_mcp_js.McpServer(options.serverInfo ?? handle.serverInfo ?? DEFAULT_MCP_CODE_WRAPPER_SERVER_INFO);
 	try {
-		if (mode === "both" || mode === "split") {
-			registerSearchTool(server, names.search, provider, maxTextChars);
-			registerExecuteTool(server, names.execute, provider, options.executor, maxTextChars, `Execute JavaScript against the wrapped ${provider.name} MCP tool namespace.`);
+		if (mode === "both" || mode === "progressive") {
+			registerSearchTool(server, names.search, provider.name, handle.toolDefinitions, maxTextChars);
+			registerDetailsTool(server, names.details, provider, handle.toolDefinitions, maxTextChars);
+			registerExecuteTool(server, names.execute, provider, options.executor, maxTextChars, `Execute JavaScript against the wrapped ${provider.name} MCP tool namespace. Use the search and details tools before writing code.`);
 		}
 		if (mode === "both" || mode === "single") registerExecuteTool(server, names.single, provider, options.executor, maxTextChars, `Execute JavaScript against the wrapped ${provider.name} MCP tool namespace.\n\n${provider.types}`);
 		return attachOwnedClose(server, handle.close);

package/dist/mcp/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["renderDocComment","schemaToType","renderNamespaceDeclaration","InMemoryTransport","Client","closePromise: Promise<void> | undefined","provider: ToolProvider","resolveProvider","z","closePromise: Promise<void> | undefined","McpServer"],"sources":["../../src/mcp/mcpWrappedToolTypes.ts","../../src/mcp/createMcpToolProvider.ts","../../src/mcp/codeMcpServer.ts"],"sourcesContent":["import type { ResolvedToolProvider } from \"../types\";\nimport { schemaToType } from \"../typegen/jsonSchema\";\nimport {\n  renderDocComment,\n  renderNamespaceDeclaration,\n} from \"../typegen/render\";\n\nconst MCP_CALL_TOOL_RESULT_TYPE = [\n  \"type McpCallToolResult = {\",\n  \"  content: Array<{\",\n  \"    type: string;\",\n  \"    text?: string;\",\n  \"    data?: string;\",\n  \"    mimeType?: string;\",\n  \"    resource?: unknown;\",\n  \"    uri?: string;\",\n  \"    name?: string;\",\n  \"    description?: string;\",\n  \"  }>;\",\n  \"  structuredContent?: unknown;\",\n  \"  isError?: boolean;\",\n  \"  _meta?: Record<string, unknown>;\",\n  \"};\",\n].join(\"\\n\");\n\n/**\n * Generates the wrapped MCP tool namespace declarations exposed to guest code.\n */\nexport function generateMcpWrappedToolTypes(\n  provider: ResolvedToolProvider,\n): string {\n  const declarations = [MCP_CALL_TOOL_RESULT_TYPE];\n\n  for (const [safeName, tool] of Object.entries(provider.tools)) {\n    const comment = renderDocComment([\n      ...(tool.description ? [tool.description, \"\"] : []),\n      \"Wrapped MCP tool. Inspect structuredContent first, then fall back to content text items.\",\n    ]);\n\n    declarations.push(\n      [\n        comment,\n        `function ${safeName}(input: ${schemaToType(tool.inputSchema)}): Promise<McpCallToolResult>;`,\n      ]\n        .filter(Boolean)\n        .join(\"\\n\"),\n    );\n  }\n\n  return renderNamespaceDeclaration(provider.name, declarations);\n}\n","import { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\nimport { InMemoryTransport } from \"@modelcontextprotocol/sdk/inMemory.js\";\nimport type { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport type { Implementation } from \"@modelcontextprotocol/sdk/types.js\";\n\nimport { resolveProvider } from \"../provider/resolveProvider\";\nimport type { ResolvedToolProvider, ToolProvider } from \"../types\";\nimport { generateMcpWrappedToolTypes } from \"./mcpWrappedToolTypes\";\n\n/**\n * Caller-owned MCP client source used by the convenience wrapper API.\n */\nexport type McpToolClientSource = {\n  client: Client;\n  serverInfo?: Implementation;\n};\n\n/**\n * Local MCP server source that requires explicit lifecycle cleanup.\n */\nexport type McpToolServerSource = {\n  server: McpServer;\n  serverInfo?: Implementation;\n};\n\n/**\n * Source used to discover MCP tools for wrapping.\n */\nexport type McpToolSource = McpToolClientSource | McpToolServerSource;\n\nconst DEFAULT_MCP_TOOL_CLIENT_INFO = {\n  name: \"mcp-tool-client\",\n  version: \"0.0.0\",\n} satisfies Implementation;\n\n/**\n * Returns the upstream server identity when the source can provide one.\n */\nexport function getMcpToolSourceServerInfo(\n  source: McpToolSource,\n): Implementation | undefined {\n  if (source.serverInfo) {\n    return source.serverInfo;\n  }\n\n  if (\"client\" in source) {\n    return source.client.getServerVersion();\n  }\n\n  return undefined;\n}\n\n/**\n * Options for wrapping MCP tools into a code-execution provider.\n */\nexport interface CreateMcpToolProviderOptions {\n  /** Namespace exposed to guest code for the wrapped tools. */\n  namespace?: string;\n  /** Implementation metadata exposed to local `{ server }` sources as the client identity. */\n  clientInfo?: Implementation;\n}\n\n/**\n * Explicit handle for a wrapped MCP provider and any owned source connections.\n */\nexport interface McpToolProviderHandle {\n  /** Resolved provider exposed to the executor or wrapper server. */\n  provider: ResolvedToolProvider;\n  /** Best-effort upstream server identity when available. */\n  serverInfo?: Implementation;\n  /** Releases any internal MCP client/server connection opened for the provider. */\n  close: () => Promise<void>;\n}\n\ninterface OpenMcpToolClientResult {\n  client: Client;\n  close: () => Promise<void>;\n}\n\nasync function closeAll(closers: Array<() => Promise<void>>): Promise<void> {\n  const results = await Promise.allSettled(closers.map((close) => close()));\n  const rejected = results.find(\n    (result): result is PromiseRejectedResult => result.status === \"rejected\",\n  );\n\n  if (rejected) {\n    throw rejected.reason;\n  }\n}\n\nasync function openMcpToolClient(\n  source: McpToolSource,\n  clientInfo: Implementation,\n): Promise<OpenMcpToolClientResult> {\n  if (\"client\" in source) {\n    return {\n      client: source.client,\n      close: async () => {},\n    };\n  }\n\n  if (source.server.isConnected()) {\n    throw new Error(\"{ server } sources must be unconnected local MCP servers\");\n  }\n\n  const [clientTransport, serverTransport] =\n    InMemoryTransport.createLinkedPair();\n  const client = new Client(clientInfo);\n  let closePromise: Promise<void> | undefined;\n  let serverConnected = false;\n\n  try {\n    await source.server.connect(serverTransport);\n    serverConnected = true;\n    await client.connect(clientTransport);\n  } catch (error) {\n    await Promise.allSettled([\n      Promise.resolve().then(() => client.close()),\n      serverConnected\n        ? Promise.resolve().then(() => source.server.close())\n        : Promise.resolve(),\n    ]);\n    throw error;\n  }\n\n  return {\n    client,\n    close: async () => {\n      closePromise ??= closeAll([\n        () => client.close(),\n        () => source.server.close(),\n      ]);\n      return closePromise;\n    },\n  };\n}\n\n/**\n * Opens an MCP tool source as a resolved execution provider with explicit cleanup.\n */\nexport async function openMcpToolProvider(\n  source: McpToolSource,\n  options: CreateMcpToolProviderOptions = {},\n): Promise<McpToolProviderHandle> {\n  const connection = await openMcpToolClient(\n    source,\n    options.clientInfo ?? DEFAULT_MCP_TOOL_CLIENT_INFO,\n  );\n\n  try {\n    const toolsResponse = await connection.client.listTools();\n    const provider: ToolProvider = {\n      name: options.namespace ?? \"mcp\",\n      tools: {},\n    };\n\n    for (const tool of toolsResponse.tools) {\n      provider.tools[tool.name] = {\n        description: tool.description,\n        execute: async (input, context) => {\n          const argumentsObject =\n            typeof input === \"object\" && input !== null\n              ? (input as Record<string, unknown>)\n              : undefined;\n\n          return connection.client.callTool(\n            {\n              arguments: argumentsObject,\n              name: tool.name,\n            },\n            undefined,\n            { signal: context.signal },\n          );\n        },\n        inputSchema: tool.inputSchema,\n      };\n    }\n\n    const resolvedProvider = resolveProvider(provider);\n\n    return {\n      close: connection.close,\n      provider: {\n        ...resolvedProvider,\n        types: generateMcpWrappedToolTypes(resolvedProvider),\n      },\n      serverInfo: getMcpToolSourceServerInfo(source),\n    };\n  } catch (error) {\n    await connection.close().catch(() => {});\n    throw error;\n  }\n}\n\n/**\n * Wraps MCP tools from a caller-owned MCP client as a resolved execution provider.\n */\nexport async function createMcpToolProvider(\n  source: McpToolClientSource,\n  options: CreateMcpToolProviderOptions = {},\n): Promise<ResolvedToolProvider> {\n  if (\"server\" in (source as unknown as McpToolSource)) {\n    throw new Error(\n      \"createMcpToolProvider() no longer accepts { server } sources. Use openMcpToolProvider() to receive a cleanup handle for owned local MCP server connections.\",\n    );\n  }\n\n  const handle = await openMcpToolProvider(source, options);\n  return handle.provider;\n}\n","import { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport type { Implementation } from \"@modelcontextprotocol/sdk/types.js\";\nimport * as z from \"zod\";\n\nimport type { Executor } from \"../executor/executor\";\nimport type { ResolvedToolProvider } from \"../types\";\nimport {\n  openMcpToolProvider,\n  type CreateMcpToolProviderOptions,\n  type McpToolSource,\n} from \"./createMcpToolProvider\";\n\n/**\n * Options for exposing wrapped MCP tool execution through an MCP server.\n */\nexport interface CodeMcpServerOptions extends CreateMcpToolProviderOptions {\n  /** Executor used to run guest JavaScript against the wrapped provider. */\n  executor: Executor;\n  /** Implementation metadata exposed to downstream clients as the wrapper server identity. */\n  serverInfo?: Implementation;\n  /** Maximum number of text characters returned in text content blocks. */\n  maxTextChars?: number;\n  /** Wrapper tool layout to expose on the returned server. */\n  mode?: \"both\" | \"single\" | \"split\";\n  /** Optional custom names for the wrapper tools. */\n  names?: {\n    execute?: string;\n    search?: string;\n    single?: string;\n  };\n}\n\nconst DEFAULT_MAX_TEXT_CHARS = 24_000;\nconst DEFAULT_MCP_CODE_WRAPPER_SERVER_INFO = {\n  name: \"mcp-code-wrapper\",\n  version: \"0.0.0\",\n} satisfies Implementation;\n\nfunction truncateText(text: string, maxTextChars: number): string {\n  return text.length <= maxTextChars ? text : text.slice(0, maxTextChars);\n}\n\nfunction renderText(value: unknown, maxTextChars: number): string {\n  return truncateText(JSON.stringify(value, null, 2), maxTextChars);\n}\n\nfunction searchTools(\n  provider: ResolvedToolProvider,\n  query: string | undefined,\n  limit: number,\n): Record<string, unknown> {\n  const normalizedQuery = query?.toLowerCase().trim();\n  const matches = Object.entries(provider.tools)\n    .map(([safeName, descriptor]) => ({\n      description: descriptor.description,\n      inputSchema: descriptor.inputSchema,\n      originalName: descriptor.originalName,\n      outputSchema: descriptor.outputSchema,\n      safeName,\n    }))\n    .filter((tool) => {\n      if (!normalizedQuery) {\n        return true;\n      }\n\n      return [tool.originalName, tool.safeName, tool.description ?? \"\"].some(\n        (field) => field.toLowerCase().includes(normalizedQuery),\n      );\n    })\n    .slice(0, limit);\n\n  return {\n    namespace: provider.name,\n    originalToSafeName: provider.originalToSafeName,\n    safeToOriginalName: provider.safeToOriginalName,\n    tools: matches,\n    types: provider.types,\n  };\n}\n\nfunction registerExecuteTool(\n  server: McpServer,\n  name: string,\n  provider: ResolvedToolProvider,\n  executor: Executor,\n  maxTextChars: number,\n  description: string,\n): void {\n  // Cast required: McpServer.registerTool's generic signature doesn't support\n  // the narrow input/output shape we need for the code-execution tool.\n  const registerTool = server.registerTool.bind(server) as (\n    toolName: string,\n    config: {\n      description: string;\n      inputSchema: Record<string, z.ZodTypeAny>;\n    },\n    handler: (args: { code: string }) => Promise<{\n      content: Array<{ text: string; type: \"text\" }>;\n      isError: boolean;\n      structuredContent: Record<string, unknown>;\n    }>,\n  ) => void;\n\n  registerTool(\n    name,\n    {\n      description,\n      inputSchema: {\n        code: z.string(),\n      },\n    },\n    async (args: { code: string }) => {\n      const execution = await executor.execute(args.code, [provider]);\n\n      return {\n        content: [{ text: renderText(execution, maxTextChars), type: \"text\" }],\n        isError: !execution.ok,\n        // ExecuteResult is JSON-safe; cast satisfies the SDK's generic record type.\n        structuredContent: execution as Record<string, unknown>,\n      };\n    },\n  );\n}\n\nfunction registerSearchTool(\n  server: McpServer,\n  name: string,\n  provider: ResolvedToolProvider,\n  maxTextChars: number,\n): void {\n  // Cast required: same rationale as registerExecuteTool above.\n  const registerTool = server.registerTool.bind(server) as (\n    toolName: string,\n    config: {\n      description: string;\n      inputSchema: Record<string, z.ZodTypeAny>;\n    },\n    handler: (args: { limit?: number; query?: string }) => Promise<{\n      content: Array<{ text: string; type: \"text\" }>;\n      structuredContent: Record<string, unknown>;\n    }>,\n  ) => void;\n\n  registerTool(\n    name,\n    {\n      description: `Search wrapped MCP tools exposed under the ${provider.name} namespace.`,\n      inputSchema: {\n        limit: z.number().int().optional(),\n        query: z.string().optional(),\n      },\n    },\n    async (args: { limit?: number; query?: string }) => {\n      const structuredContent = searchTools(\n        provider,\n        args.query,\n        args.limit ?? 20,\n      );\n      return {\n        content: [\n          { text: renderText(structuredContent, maxTextChars), type: \"text\" },\n        ],\n        structuredContent,\n      };\n    },\n  );\n}\n\nfunction attachOwnedClose(\n  server: McpServer,\n  closeOwnedResources: () => Promise<void>,\n): McpServer {\n  const originalClose = server.close.bind(server);\n  let closePromise: Promise<void> | undefined;\n\n  server.close = async () => {\n    closePromise ??= (async () => {\n      const results = await Promise.allSettled([\n        originalClose(),\n        closeOwnedResources(),\n      ]);\n      const rejected = results.find(\n        (result): result is PromiseRejectedResult =>\n          result.status === \"rejected\",\n      );\n\n      if (rejected) {\n        throw rejected.reason;\n      }\n    })();\n\n    return closePromise;\n  };\n\n  return server;\n}\n\n/**\n * Creates an MCP server that exposes code-execution tools for a wrapped MCP source.\n */\nexport async function codeMcpServer(\n  source: McpToolSource,\n  options: CodeMcpServerOptions,\n): Promise<McpServer> {\n  const maxTextChars = options.maxTextChars ?? DEFAULT_MAX_TEXT_CHARS;\n  const mode = options.mode ?? \"both\";\n  const names = {\n    execute: options.names?.execute ?? \"mcp_execute_code\",\n    search: options.names?.search ?? \"mcp_search_tools\",\n    single: options.names?.single ?? \"mcp_code\",\n  };\n  const handle = await openMcpToolProvider(source, {\n    clientInfo: options.clientInfo,\n    namespace: options.namespace ?? \"mcp\",\n  });\n  const provider = handle.provider;\n  const server = new McpServer(\n    options.serverInfo ??\n      handle.serverInfo ??\n      DEFAULT_MCP_CODE_WRAPPER_SERVER_INFO,\n  );\n\n  try {\n    if (mode === \"both\" || mode === \"split\") {\n      registerSearchTool(server, names.search, provider, maxTextChars);\n      registerExecuteTool(\n        server,\n        names.execute,\n        provider,\n        options.executor,\n        maxTextChars,\n        `Execute JavaScript against the wrapped ${provider.name} MCP tool namespace.`,\n      );\n    }\n\n    if (mode === \"both\" || mode === \"single\") {\n      registerExecuteTool(\n        server,\n        names.single,\n        provider,\n        options.executor,\n        maxTextChars,\n        `Execute JavaScript against the wrapped ${provider.name} MCP tool namespace.\\n\\n${provider.types}`,\n      );\n    }\n\n    return attachOwnedClose(server, handle.close);\n  } catch (error) {\n    await handle.close().catch(() => {});\n    throw error;\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.cjs","names":["renderDocComment","schemaToType","renderNamespaceDeclaration","InMemoryTransport","Client","closePromise: Promise<void> | undefined","provider: ToolProvider","resolveProvider","z","closePromise: Promise<void> | undefined","McpServer"],"sources":["../../src/mcp/mcpWrappedToolTypes.ts","../../src/mcp/createMcpToolProvider.ts","../../src/mcp/codeMcpServer.ts"],"sourcesContent":["import type { ResolvedToolProvider } from \"../types\";\nimport { schemaToType } from \"../typegen/jsonSchema\";\nimport {\n  renderDocComment,\n  renderNamespaceDeclaration,\n} from \"../typegen/render\";\n\nconst MCP_CALL_TOOL_RESULT_TYPE = [\n  \"type McpCallToolResult = {\",\n  \"  content: Array<{\",\n  \"    type: string;\",\n  \"    text?: string;\",\n  \"    data?: string;\",\n  \"    mimeType?: string;\",\n  \"    resource?: unknown;\",\n  \"    uri?: string;\",\n  \"    name?: string;\",\n  \"    description?: string;\",\n  \"  }>;\",\n  \"  structuredContent?: unknown;\",\n  \"  isError?: boolean;\",\n  \"  _meta?: Record<string, unknown>;\",\n  \"};\",\n].join(\"\\n\");\n\n/**\n * Generates one wrapped MCP tool declaration exposed to guest code.\n */\nexport function generateMcpWrappedToolType(\n  provider: ResolvedToolProvider,\n  safeName: string,\n): string {\n  const tool = provider.tools[safeName];\n\n  if (!tool) {\n    throw new Error(`Unknown wrapped MCP tool: ${safeName}`);\n  }\n\n  const comment = renderDocComment([\n    ...(tool.description ? [tool.description, \"\"] : []),\n    \"Wrapped MCP tool. Inspect structuredContent first, then fall back to content text items.\",\n  ]);\n\n  return [\n    comment,\n    `function ${safeName}(input: ${schemaToType(tool.inputSchema)}): Promise<McpCallToolResult>;`,\n  ]\n    .filter(Boolean)\n    .join(\"\\n\");\n}\n\n/**\n * Generates the wrapped MCP tool namespace declarations exposed to guest code.\n */\nexport function generateMcpWrappedToolTypes(\n  provider: ResolvedToolProvider,\n): string {\n  const declarations = [\n    MCP_CALL_TOOL_RESULT_TYPE,\n    ...Object.keys(provider.tools).map((safeName) =>\n      generateMcpWrappedToolType(provider, safeName),\n    ),\n  ];\n\n  return renderNamespaceDeclaration(provider.name, declarations);\n}\n\n/**\n * Generates the wrapped MCP tool namespace declaration for one selected tool.\n */\nexport function generateMcpWrappedSingleToolTypes(\n  provider: ResolvedToolProvider,\n  safeName: string,\n): string {\n  return renderNamespaceDeclaration(provider.name, [\n    MCP_CALL_TOOL_RESULT_TYPE,\n    generateMcpWrappedToolType(provider, safeName),\n  ]);\n}\n","import { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\nimport { InMemoryTransport } from \"@modelcontextprotocol/sdk/inMemory.js\";\nimport type { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport type { Implementation } from \"@modelcontextprotocol/sdk/types.js\";\n\nimport { resolveProvider } from \"../provider/resolveProvider\";\nimport type {\n  JsonSchema,\n  ResolvedToolProvider,\n  ToolAnnotations,\n  ToolProvider,\n} from \"../types\";\nimport { generateMcpWrappedToolTypes } from \"./mcpWrappedToolTypes\";\n\n/**\n * Caller-owned MCP client source used by the convenience wrapper API.\n */\nexport type McpToolClientSource = {\n  client: Client;\n  serverInfo?: Implementation;\n};\n\n/**\n * Local MCP server source that requires explicit lifecycle cleanup.\n */\nexport type McpToolServerSource = {\n  server: McpServer;\n  serverInfo?: Implementation;\n};\n\n/**\n * Source used to discover MCP tools for wrapping.\n */\nexport type McpToolSource = McpToolClientSource | McpToolServerSource;\n\nconst DEFAULT_MCP_TOOL_CLIENT_INFO = {\n  name: \"mcp-tool-client\",\n  version: \"0.0.0\",\n} satisfies Implementation;\n\n/**\n * Returns the upstream server identity when the source can provide one.\n */\nexport function getMcpToolSourceServerInfo(\n  source: McpToolSource,\n): Implementation | undefined {\n  if (source.serverInfo) {\n    return source.serverInfo;\n  }\n\n  if (\"client\" in source) {\n    return source.client.getServerVersion();\n  }\n\n  return undefined;\n}\n\n/**\n * Options for wrapping MCP tools into a code-execution provider.\n */\nexport interface CreateMcpToolProviderOptions {\n  /** Namespace exposed to guest code for the wrapped tools. */\n  namespace?: string;\n  /** Implementation metadata exposed to local `{ server }` sources as the client identity. */\n  clientInfo?: Implementation;\n}\n\n/**\n * Full wrapped MCP tool metadata used by progressive discovery surfaces.\n */\nexport interface McpWrappedToolDefinition {\n  /** Optional MCP-compatible behavior hints copied from the upstream tool. */\n  annotations?: ToolAnnotations;\n  /** Optional human-readable description copied from the upstream tool. */\n  description?: string;\n  /** Normalized input schema used for wrapped tool argument validation. */\n  inputSchema?: JsonSchema;\n  /** Original upstream MCP tool name. */\n  originalName: string;\n  /** Upstream output schema for the tool's `structuredContent`, when provided. */\n  outputSchema?: JsonSchema;\n  /** Sanitized tool name visible in guest code. */\n  safeName: string;\n}\n\n/**\n * Explicit handle for a wrapped MCP provider and any owned source connections.\n */\nexport interface McpToolProviderHandle {\n  /** Resolved provider exposed to the executor or wrapper server. */\n  provider: ResolvedToolProvider;\n  /** Best-effort upstream server identity when available. */\n  serverInfo?: Implementation;\n  /** Full wrapped MCP tool definitions keyed by safe guest-visible name. */\n  toolDefinitions: Record<string, McpWrappedToolDefinition>;\n  /** Releases any internal MCP client/server connection opened for the provider. */\n  close: () => Promise<void>;\n}\n\ninterface OpenMcpToolClientResult {\n  client: Client;\n  close: () => Promise<void>;\n}\n\nasync function closeAll(closers: Array<() => Promise<void>>): Promise<void> {\n  const results = await Promise.allSettled(closers.map((close) => close()));\n  const rejected = results.find(\n    (result): result is PromiseRejectedResult => result.status === \"rejected\",\n  );\n\n  if (rejected) {\n    throw rejected.reason;\n  }\n}\n\nfunction asJsonSchema(schema: unknown): JsonSchema | undefined {\n  return typeof schema === \"object\" && schema !== null\n    ? (schema as JsonSchema)\n    : undefined;\n}\n\nasync function openMcpToolClient(\n  source: McpToolSource,\n  clientInfo: Implementation,\n): Promise<OpenMcpToolClientResult> {\n  if (\"client\" in source) {\n    return {\n      client: source.client,\n      close: async () => {},\n    };\n  }\n\n  if (source.server.isConnected()) {\n    throw new Error(\"{ server } sources must be unconnected local MCP servers\");\n  }\n\n  const [clientTransport, serverTransport] =\n    InMemoryTransport.createLinkedPair();\n  const client = new Client(clientInfo);\n  let closePromise: Promise<void> | undefined;\n  let serverConnected = false;\n\n  try {\n    await source.server.connect(serverTransport);\n    serverConnected = true;\n    await client.connect(clientTransport);\n  } catch (error) {\n    await Promise.allSettled([\n      Promise.resolve().then(() => client.close()),\n      serverConnected\n        ? Promise.resolve().then(() => source.server.close())\n        : Promise.resolve(),\n    ]);\n    throw error;\n  }\n\n  return {\n    client,\n    close: async () => {\n      closePromise ??= closeAll([\n        () => client.close(),\n        () => source.server.close(),\n      ]);\n      return closePromise;\n    },\n  };\n}\n\n/**\n * Opens an MCP tool source as a resolved execution provider with explicit cleanup.\n */\nexport async function openMcpToolProvider(\n  source: McpToolSource,\n  options: CreateMcpToolProviderOptions = {},\n): Promise<McpToolProviderHandle> {\n  const connection = await openMcpToolClient(\n    source,\n    options.clientInfo ?? DEFAULT_MCP_TOOL_CLIENT_INFO,\n  );\n\n  try {\n    const toolsResponse = await connection.client.listTools();\n    const toolsByOriginalName = new Map(\n      toolsResponse.tools.map((tool) => [tool.name, tool] as const),\n    );\n    const provider: ToolProvider = {\n      name: options.namespace ?? \"mcp\",\n      tools: {},\n    };\n\n    for (const tool of toolsResponse.tools) {\n      provider.tools[tool.name] = {\n        annotations: tool.annotations,\n        description: tool.description,\n        execute: async (input, context) => {\n          const argumentsObject =\n            typeof input === \"object\" && input !== null\n              ? (input as Record<string, unknown>)\n              : undefined;\n\n          return connection.client.callTool(\n            {\n              arguments: argumentsObject,\n              name: tool.name,\n            },\n            undefined,\n            { signal: context.signal },\n          );\n        },\n        inputSchema: tool.inputSchema,\n      };\n    }\n\n    const resolvedProvider = resolveProvider(provider);\n    const toolDefinitions = Object.fromEntries(\n      Object.entries(resolvedProvider.tools).map(([safeName, descriptor]) => {\n        const upstreamTool = toolsByOriginalName.get(descriptor.originalName);\n\n        return [\n          safeName,\n          {\n            annotations: descriptor.annotations,\n            description: descriptor.description,\n            inputSchema: descriptor.inputSchema,\n            originalName: descriptor.originalName,\n            outputSchema: asJsonSchema(upstreamTool?.outputSchema),\n            safeName: descriptor.safeName,\n          },\n        ];\n      }),\n    );\n\n    return {\n      close: connection.close,\n      provider: {\n        ...resolvedProvider,\n        types: generateMcpWrappedToolTypes(resolvedProvider),\n      },\n      serverInfo: getMcpToolSourceServerInfo(source),\n      toolDefinitions,\n    };\n  } catch (error) {\n    await connection.close().catch(() => {});\n    throw error;\n  }\n}\n\n/**\n * Wraps MCP tools from a caller-owned MCP client as a resolved execution provider.\n */\nexport async function createMcpToolProvider(\n  source: McpToolClientSource,\n  options: CreateMcpToolProviderOptions = {},\n): Promise<ResolvedToolProvider> {\n  if (\"server\" in (source as unknown as McpToolSource)) {\n    throw new Error(\n      \"createMcpToolProvider() no longer accepts { server } sources. Use openMcpToolProvider() to receive a cleanup handle for owned local MCP server connections.\",\n    );\n  }\n\n  const handle = await openMcpToolProvider(source, options);\n  return handle.provider;\n}\n","import { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport type { Implementation } from \"@modelcontextprotocol/sdk/types.js\";\nimport * as z from \"zod\";\n\nimport type { Executor } from \"../executor/executor\";\nimport type { ResolvedToolProvider, ToolAnnotations } from \"../types\";\nimport {\n  openMcpToolProvider,\n  type CreateMcpToolProviderOptions,\n  type McpWrappedToolDefinition,\n  type McpToolSource,\n} from \"./createMcpToolProvider\";\nimport { generateMcpWrappedSingleToolTypes } from \"./mcpWrappedToolTypes\";\n\n/**\n * Options for exposing wrapped MCP tool execution through an MCP server.\n */\nexport interface CodeMcpServerOptions extends CreateMcpToolProviderOptions {\n  /** Executor used to run guest JavaScript against the wrapped provider. */\n  executor: Executor;\n  /** Implementation metadata exposed to downstream clients as the wrapper server identity. */\n  serverInfo?: Implementation;\n  /** Maximum number of text characters returned in text content blocks. */\n  maxTextChars?: number;\n  /** Wrapper tool layout to expose on the returned server. */\n  mode?: \"both\" | \"progressive\" | \"single\";\n  /** Optional custom names for the wrapper tools. */\n  names?: {\n    details?: string;\n    execute?: string;\n    search?: string;\n    single?: string;\n  };\n}\n\nconst DEFAULT_MAX_TEXT_CHARS = 24_000;\nconst CODE_EXECUTION_TOOL_ANNOTATIONS = {\n  destructiveHint: true,\n  idempotentHint: false,\n  openWorldHint: true,\n  readOnlyHint: false,\n} satisfies ToolAnnotations;\nconst READ_ONLY_TOOL_ANNOTATIONS = {\n  destructiveHint: false,\n  idempotentHint: true,\n  openWorldHint: false,\n  readOnlyHint: true,\n} satisfies ToolAnnotations;\nconst DEFAULT_MCP_CODE_WRAPPER_SERVER_INFO = {\n  name: \"mcp-code-wrapper\",\n  version: \"0.0.0\",\n} satisfies Implementation;\n\nfunction truncateText(text: string, maxTextChars: number): string {\n  return text.length <= maxTextChars ? text : text.slice(0, maxTextChars);\n}\n\nfunction renderText(value: unknown, maxTextChars: number): string {\n  return truncateText(JSON.stringify(value, null, 2), maxTextChars);\n}\n\nfunction searchTools(\n  toolDefinitions: Record<string, McpWrappedToolDefinition>,\n  namespace: string,\n  query: string | undefined,\n  limit: number,\n): Record<string, unknown> {\n  const normalizedQuery = query?.toLowerCase().trim();\n  const matches = Object.values(toolDefinitions)\n    .filter((tool) => {\n      if (!normalizedQuery) {\n        return true;\n      }\n\n      return [tool.originalName, tool.safeName, tool.description ?? \"\"].some(\n        (field) => field.toLowerCase().includes(normalizedQuery),\n      );\n    })\n    .slice(0, limit)\n    .map((tool) => ({\n      annotations: tool.annotations,\n      description: tool.description,\n      originalName: tool.originalName,\n      safeName: tool.safeName,\n    }));\n\n  return {\n    namespace,\n    tools: matches,\n  };\n}\n\nfunction getToolDetails(\n  provider: ResolvedToolProvider,\n  toolDefinitions: Record<string, McpWrappedToolDefinition>,\n  safeName: string,\n): Record<string, unknown> {\n  const tool = toolDefinitions[safeName];\n\n  if (!tool) {\n    throw new Error(`Unknown wrapped MCP tool: ${safeName}`);\n  }\n\n  return {\n    annotations: tool.annotations,\n    description: tool.description,\n    inputSchema: tool.inputSchema,\n    originalName: tool.originalName,\n    outputSchema: tool.outputSchema,\n    safeName: tool.safeName,\n    types: generateMcpWrappedSingleToolTypes(provider, safeName),\n  };\n}\n\nfunction registerExecuteTool(\n  server: McpServer,\n  name: string,\n  provider: ResolvedToolProvider,\n  executor: Executor,\n  maxTextChars: number,\n  description: string,\n): void {\n  // Cast required: McpServer.registerTool's generic signature doesn't support\n  // the narrow input/output shape we need for the code-execution tool.\n  const registerTool = server.registerTool.bind(server) as (\n    toolName: string,\n    config: {\n      annotations: ToolAnnotations;\n      description: string;\n      inputSchema: Record<string, z.ZodTypeAny>;\n    },\n    handler: (args: { code: string }) => Promise<{\n      content: Array<{ text: string; type: \"text\" }>;\n      isError: boolean;\n      structuredContent: Record<string, unknown>;\n    }>,\n  ) => void;\n\n  registerTool(\n    name,\n    {\n      annotations: CODE_EXECUTION_TOOL_ANNOTATIONS,\n      description,\n      inputSchema: {\n        code: z.string(),\n      },\n    },\n    async (args: { code: string }) => {\n      const execution = await executor.execute(args.code, [provider]);\n\n      return {\n        content: [{ text: renderText(execution, maxTextChars), type: \"text\" }],\n        isError: !execution.ok,\n        // ExecuteResult is JSON-safe; cast satisfies the SDK's generic record type.\n        structuredContent: execution as Record<string, unknown>,\n      };\n    },\n  );\n}\n\nfunction registerSearchTool(\n  server: McpServer,\n  name: string,\n  namespace: string,\n  toolDefinitions: Record<string, McpWrappedToolDefinition>,\n  maxTextChars: number,\n): void {\n  // Cast required: same rationale as registerExecuteTool above.\n  const registerTool = server.registerTool.bind(server) as (\n    toolName: string,\n    config: {\n      annotations: ToolAnnotations;\n      description: string;\n      inputSchema: Record<string, z.ZodTypeAny>;\n    },\n    handler: (args: { limit?: number; query?: string }) => Promise<{\n      content: Array<{ text: string; type: \"text\" }>;\n      structuredContent: Record<string, unknown>;\n    }>,\n  ) => void;\n\n  registerTool(\n    name,\n    {\n      annotations: READ_ONLY_TOOL_ANNOTATIONS,\n      description: `Search wrapped MCP tools exposed under the ${namespace} namespace. Returns concise catalog entries only; call the details tool for schemas.`,\n      inputSchema: {\n        limit: z.number().int().optional(),\n        query: z.string().optional(),\n      },\n    },\n    async (args: { limit?: number; query?: string }) => {\n      const structuredContent = searchTools(\n        toolDefinitions,\n        namespace,\n        args.query,\n        args.limit ?? 20,\n      );\n      return {\n        content: [\n          { text: renderText(structuredContent, maxTextChars), type: \"text\" },\n        ],\n        structuredContent,\n      };\n    },\n  );\n}\n\nfunction registerDetailsTool(\n  server: McpServer,\n  name: string,\n  provider: ResolvedToolProvider,\n  toolDefinitions: Record<string, McpWrappedToolDefinition>,\n  maxTextChars: number,\n): void {\n  // Cast required: same rationale as registerExecuteTool above.\n  const registerTool = server.registerTool.bind(server) as (\n    toolName: string,\n    config: {\n      annotations: ToolAnnotations;\n      description: string;\n      inputSchema: Record<string, z.ZodTypeAny>;\n    },\n    handler: (args: { safeName: string }) => Promise<{\n      content: Array<{ text: string; type: \"text\" }>;\n      structuredContent: Record<string, unknown>;\n    }>,\n  ) => void;\n\n  registerTool(\n    name,\n    {\n      annotations: READ_ONLY_TOOL_ANNOTATIONS,\n      description: `Return the full schema and generated TypeScript declaration for one wrapped ${provider.name} MCP tool.`,\n      inputSchema: {\n        safeName: z.string(),\n      },\n    },\n    async (args: { safeName: string }) => {\n      const structuredContent = getToolDetails(\n        provider,\n        toolDefinitions,\n        args.safeName,\n      );\n      return {\n        content: [\n          { text: renderText(structuredContent, maxTextChars), type: \"text\" },\n        ],\n        structuredContent,\n      };\n    },\n  );\n}\n\nfunction attachOwnedClose(\n  server: McpServer,\n  closeOwnedResources: () => Promise<void>,\n): McpServer {\n  const originalClose = server.close.bind(server);\n  let closePromise: Promise<void> | undefined;\n\n  server.close = async () => {\n    closePromise ??= (async () => {\n      const results = await Promise.allSettled([\n        originalClose(),\n        closeOwnedResources(),\n      ]);\n      const rejected = results.find(\n        (result): result is PromiseRejectedResult =>\n          result.status === \"rejected\",\n      );\n\n      if (rejected) {\n        throw rejected.reason;\n      }\n    })();\n\n    return closePromise;\n  };\n\n  return server;\n}\n\n/**\n * Creates an MCP server that exposes code-execution tools for a wrapped MCP source.\n */\nexport async function codeMcpServer(\n  source: McpToolSource,\n  options: CodeMcpServerOptions,\n): Promise<McpServer> {\n  const maxTextChars = options.maxTextChars ?? DEFAULT_MAX_TEXT_CHARS;\n  const mode = options.mode ?? \"progressive\";\n  const names = {\n    details: options.names?.details ?? \"mcp_get_tool_details\",\n    execute: options.names?.execute ?? \"mcp_execute_code\",\n    search: options.names?.search ?? \"mcp_search_tools\",\n    single: options.names?.single ?? \"mcp_code\",\n  };\n  const handle = await openMcpToolProvider(source, {\n    clientInfo: options.clientInfo,\n    namespace: options.namespace ?? \"mcp\",\n  });\n  const provider = handle.provider;\n  const server = new McpServer(\n    options.serverInfo ??\n      handle.serverInfo ??\n      DEFAULT_MCP_CODE_WRAPPER_SERVER_INFO,\n  );\n\n  try {\n    if (mode === \"both\" || mode === \"progressive\") {\n      registerSearchTool(\n        server,\n        names.search,\n        provider.name,\n        handle.toolDefinitions,\n        maxTextChars,\n      );\n      registerDetailsTool(\n        server,\n        names.details,\n        provider,\n        handle.toolDefinitions,\n        maxTextChars,\n      );\n      registerExecuteTool(\n        server,\n        names.execute,\n        provider,\n        options.executor,\n        maxTextChars,\n        `Execute JavaScript against the wrapped ${provider.name} MCP tool namespace. Use the search and details tools before writing code.`,\n      );\n    }\n\n    if (mode === \"both\" || mode === \"single\") {\n      registerExecuteTool(\n        server,\n        names.single,\n        provider,\n        options.executor,\n        maxTextChars,\n        `Execute JavaScript against the wrapped ${provider.name} MCP tool namespace.\\n\\n${provider.types}`,\n      );\n    }\n\n    return attachOwnedClose(server, handle.close);\n  } catch (error) {\n    await handle.close().catch(() => {});\n    throw error;\n  }\n}\n"],"mappings":"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"}