reusable mcp client (#1646)

* feat: add listToolCallbacks method to McpClient interface and update related implementations

* feat: add disableToolIdMangling option to McpServerConfig and update related implementations

* feat: add devproxy support and upgrade sample script for Dev Proxy versioning

* feat: integrate patchInputSchema function to standardize input schema processing

* ✨: Enhance type imports across multiple files

Added new type imports for better typing and code reliability.

Author: pelikhan

.vscode/settings.json

@@ -73,6 +73,7 @@
         "demux",
         "devcli",
         "devcontainers",
+        "devproxy",
         "dfence",
         "docify",
         "Dockerized",

docs/src/content/docs/reference/scripts/mcp-clients.mdx

@@ -11,7 +11,6 @@ hero:
       details include a small play button or gear symbol, symbolizing operations
       or scripting functionality.
     file: ./mcp-clients.png
-
 ---
 
 The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) defines a protocol for sharing [tools](https://modelcontextprotocol.io/docs/concepts/tools)
@@ -40,10 +39,10 @@ This identifier is used to reference the server in the `mcpClient`.
 
 ```js
 const fs = await host.mcpServer({
-    id: "filesystem",
-    command: "npx",
-    args: ["-y", "@modelcontextprotocol/server-filesystem", path.resolve(".")],
-})
+  id: "filesystem",
+  command: "npx",
+  args: ["-y", "@modelcontextprotocol/server-filesystem", path.resolve(".")],
+});
 ```
 
 The server is automatically stopped when the prompt finishes.
@@ -52,28 +51,28 @@ The server is automatically stopped when the prompt finishes.
 
 You can perform operations on tools. Queries are not cached and always communicate with the server.
 
-- List tools:
+- List tools (metadata):
 
-    ```js
-    const tools = await fs.listTools()
-    ```
+  ```js
+  const tools = await fs.listTools();
+  ```
 
 - Call a tool:
 
-    ```js
-    const res = await fs.callTool("get_file_info", { path: "README.md" })
-    ```
+  ```js
+  const res = await fs.callTool("get_file_info", { path: "README.md" });
+  ```
 
 - Use the result:
 
-    ```js
-    const info = res.content[0].text
-    ```
+  ```js
+  const info = res.content[0].text;
+  ```
 
 The structure of the output depends on the tool, but it is designed to be consumed by an LLM. You will likely want to use `def` to store it in your prompt:
 
 ```js
-def("INFO", info)
+def("INFO", info);
 ```
 
 ## Example: YouTube Transcript
@@ -83,12 +82,28 @@ of a YouTube video. It is listed in the [Docker MCP Catalog](https://hub.docker.
 
 ```js
 const yt = await host.mcpServer({
-    id: "youtube_transcript",
-    command: "docker",
-    args: ["run", "-i", "--rm", "mcp/youtube-transcript"],
-})
-
-const url = "https://youtu.be/ENunZe--7j0"
-const transcript = await yt.callTool("get_transcript", { url })
-console.log(`transcript: ${transcript.text}`)
+  id: "youtube_transcript",
+  command: "docker",
+  args: ["run", "-i", "--rm", "mcp/youtube-transcript"],
+});
+
+const url = "https://youtu.be/ENunZe--7j0";
+const transcript = await yt.callTool("get_transcript", { url });
+console.log(`transcript: ${transcript.text}`);
+```
+
+## Sharing MCPs
+
+By default, MCP servers are not shared between prompts. If you want to use the same MCP server in multiple prompts,
+you can use the `host.mcpClient` function to create a client that can be reused across prompts.
+
+You can also get tools in a form that can be used in `defTool` and reuse it in multiple prompts:
+
+```js
+const tools = await fs.listToolCallbacks();
+
+await runPrompt((ctx) => {
+  for (const tool of tools) ctx.defTool(tools);
+  ctx....
+});
 ```

packages/core/src/agent.ts

@@ -9,7 +9,11 @@ import { HTMLEscape } from "./htmlescape.js";
 import { prettifyMarkdown } from "./markdown.js";
 import { TraceOptions } from "./trace.js";
 import { ellipse } from "./util.js";
-import type { ChatGenerationContext, WorkspaceFileCache } from "./types.js";
+import type {
+  ChatGenerationContext,
+  ChatTurnGenerationContext,
+  WorkspaceFileCache,
+} from "./types.js";
 
 import debug from "debug";
 const dbg = debug("agent:memory");
@@ -50,7 +54,6 @@ export async function agentQueryMemory(
   cache: AgentMemoryCache,
   ctx: ChatGenerationContext,
   query: string,
-  _options: Required<TraceOptions>,
 ) {
   if (!query) return undefined;
 

packages/core/src/annotations.ts

@@ -10,7 +10,7 @@
 import { deleteUndefinedValues } from "./cleaners.js";
 import { EMOJI_FAIL, EMOJI_WARNING } from "./constants.js";
 import { unfence } from "./unwrappers.js";
-import type { Diagnostic } from "./types.js";
+import type { Diagnostic, DiagnosticSeverity } from "./types.js";
 
 // Regular expression for matching GitHub Actions annotations.
 // Example: ::error file=foo.js,line=10,endLine=11::Something went wrong.
@@ -39,7 +39,7 @@ const GITHUB_MARKDOWN_WARNINGS_RX =
 // Example: src/connection.ts(71,5): error TS1128: Declaration or statement expected.
 // src/connection.ts(71,5): error TS1128: Declaration or statement expected.
 const TYPESCRIPT_PARENTHESES_ANNOTATIONS_RX =
-  /^(?<file>[^\(\n]+)\((?<line>\d+),(?<col>\d+)\):\s+(?<severity>error|warning)\s+(?<code>TS\d+):\s+(?<message>.+)$/gim;
+  /^(?<file>[^(\n]+)\((?<line>\d+),(?<col>\d+)\):\s+(?<severity>error|warning)\s+(?<code>TS\d+):\s+(?<message>.+)$/gim;
 const ANNOTATIONS_RX = [
   TYPESCRIPT_PARENTHESES_ANNOTATIONS_RX,
   TYPESCRIPT_ANNOTATIONS_RX,
@@ -187,6 +187,7 @@ export function convertGithubMarkdownAnnotationsToItems(text: string) {
  * @returns A formatted string representing the Diagnostic as a list item.
  */
 export function convertAnnotationToItem(d: Diagnostic) {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
   const { severity, message, filename, code, range } = d;
   const line = range?.[0]?.[0];
   return `- ${SEV_EMOJI_MAP[severity?.toLowerCase()] ?? "info"} ${message}${filename ? ` (\`${filename}${line ? `#L${line}` : ""}\`)` : ""}`;

packages/core/src/anthropic.ts

@@ -40,6 +40,7 @@ import { LanguageModelConfiguration } from "./server/messages.js";
 import { deleteUndefinedValues } from "./cleaners.js";
 import debug from "debug";
 import { providerFeatures } from "./features.js";
+import { LanguageModelInfo } from "./types.js";
 const dbg = debug("genaiscript:anthropic");
 const dbgMessages = debug("genaiscript:anthropic:msg");
 

packages/core/src/ast.ts

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
+/// <reference types="./types/prompt_template.d.ts" />
 // Import necessary regular expressions for file type detection and host utilities
 import { GENAI_ANYJS_REGEX, GENAI_ANYTS_REGEX } from "./constants.js";
 import { Project } from "./server/messages.js";

packages/core/src/azureaisearch.ts

@@ -14,6 +14,15 @@ import { LanguageModelConfiguration } from "./server/messages.js";
 import { chunk } from "./encoders.js";
 import { genaiscriptDebug } from "./debug.js";
 import { SearchClient, SearchIndexClient, AzureKeyCredential } from "@azure/search-documents";
+import type {
+  ElementOrArray,
+  TextChunk,
+  VectorIndexOptions,
+  VectorSearchOptions,
+  WorkspaceFile,
+  WorkspaceFileIndex,
+  WorkspaceFileWithScore,
+} from "./types.js";
 
 const dbg = genaiscriptDebug("azureaisearch");
 

packages/core/src/azuredevops.ts

@@ -110,6 +110,7 @@ export async function azureDevOpsUpdatePullRequestDescription(
   // query pull request
   const pr = await findPullRequest(info);
   if (!pr) return;
+  // eslint-disable-next-line prefer-const
   let { pullRequestId, description } = pr;
 
   text = prettifyMarkdown(text);

packages/core/src/azureopenai.ts

@@ -34,7 +34,7 @@ const azureManagementListModels: ListModelsFunction = async (cfg, options) => {
     const { base } = cfg;
     const subscriptionId = process.env.AZURE_OPENAI_SUBSCRIPTION_ID;
     let resourceGroupName = process.env.AZURE_OPENAI_RESOURCE_GROUP;
-    const accountName = /^https:\/\/([^\.]+)\./.exec(base)[1];
+    const accountName = /^https:\/\/([^.]+)\./.exec(base)[1];
 
     if (!subscriptionId || !accountName) {
       dbg("subscriptionId or accountName is missing, returning an empty model list");
@@ -78,7 +78,7 @@ const azureManagementListModels: ListModelsFunction = async (cfg, options) => {
         `https://management.azure.com/subscriptions/${subscriptionId}/resources?api-version=2021-04-01`,
       );
       const resource = resources.value.find((r) => r.name === accountName);
-      resourceGroupName = /\/resourceGroups\/([^\/]+)\/providers\//.exec(resource?.id)[1];
+      resourceGroupName = /\/resourceGroups\/([^/]+)\/providers\//.exec(resource?.id)[1];
       if (!resourceGroupName) {
         dbg("unable to extract resource group name from resource id");
         throw new Error("Resource group not found");

packages/core/src/azuretoken.ts

@@ -26,6 +26,7 @@ import {
   ManagedIdentityCredential,
   WorkloadIdentityCredential,
 } from "@azure/identity";
+import type { SerializedError } from "./types.js";
 
 /**
  * This module provides functions to handle Azure authentication tokens,