feat!(js/plugins/mcp): renamed mcp plugin package to @genkit-ai/mcp and new MCP client API

.github/workflows/bump-js-version.yml

@@ -228,8 +228,8 @@ jobs:
           default: ${{ inputs.releaseType }}
           version-type: ${{ inputs.releaseType }}
           preid: ${{ inputs.preid }}
-          commit-message: 'chore: bump genkitx-mcp version to {{version}}'
-          tag-prefix:  'genkitx-mcp@'
+          commit-message: 'chore: bump @genkit-ai/mcp version to {{version}}'
+          tag-prefix:  '@genkit-ai/mcp@'
       - name: 'js/plugins/express version bump'
         uses: 'phips28/gh-action-bump-version@master'
         env:

js/ai/src/prompt.ts

@@ -147,6 +147,9 @@ export interface ExecutablePrompt<
   O extends z.ZodTypeAny = z.ZodTypeAny,
   CustomOptions extends z.ZodTypeAny = z.ZodTypeAny,
 > {
+  /** Prompt reference. */
+  ref: { name: string; metadata?: Record<string, any> };
+
   /**
    * Generates a response by rendering the prompt template with given user input and then calling the model.
    *
@@ -234,7 +237,8 @@ export function definePrompt<
   return definePromptAsync(
     registry,
     `${options.name}${options.variant ? `.${options.variant}` : ''}`,
-    Promise.resolve(options)
+    Promise.resolve(options),
+    options.metadata
   );
 }
 
@@ -245,7 +249,8 @@ function definePromptAsync<
 >(
   registry: Registry,
   name: string,
-  optionsPromise: PromiseLike<PromptConfig<I, O, CustomOptions>>
+  optionsPromise: PromiseLike<PromptConfig<I, O, CustomOptions>>,
+  metadata?: Record<string, any>
 ): ExecutablePrompt<z.infer<I>, O, CustomOptions> {
   const promptCache = {} as PromptCache;
 
@@ -399,11 +404,13 @@ function definePromptAsync<
     }
   ) as Promise<ExecutablePromptAction<I>>;
 
-  const executablePrompt = wrapInExecutablePrompt(
+  const executablePrompt = wrapInExecutablePrompt({
     registry,
+    name,
     renderOptionsFn,
-    rendererAction
-  );
+    rendererAction,
+    metadata,
+  });
 
   return executablePrompt;
 }
@@ -436,57 +443,64 @@ function wrapInExecutablePrompt<
   I extends z.ZodTypeAny = z.ZodTypeAny,
   O extends z.ZodTypeAny = z.ZodTypeAny,
   CustomOptions extends z.ZodTypeAny = z.ZodTypeAny,
->(
-  registry: Registry,
+>(wrapOpts: {
+  registry: Registry;
+  name: string;
   renderOptionsFn: (
     input: z.infer<I>,
     renderOptions: PromptGenerateOptions<O, CustomOptions> | undefined
-  ) => Promise<GenerateOptions>,
-  rendererAction: Promise<PromptAction<I>>
-) {
+  ) => Promise<GenerateOptions>;
+  rendererAction: Promise<PromptAction<I>>;
+  metadata?: Record<string, any>;
+}) {
   const executablePrompt = (async (
     input?: I,
     opts?: PromptGenerateOptions<O, CustomOptions>
   ): Promise<GenerateResponse<z.infer<O>>> => {
     return await runInNewSpan(
-      registry,
+      wrapOpts.registry,
       {
         metadata: {
-          name: (await rendererAction).__action.name,
+          name: (await wrapOpts.rendererAction).__action.name,
           input,
         },
         labels: {
           [SPAN_TYPE_ATTR]: 'dotprompt',
         },
       },
       async (metadata) => {
-        const output = await generate(registry, {
-          ...(await renderOptionsFn(input, opts)),
+        const output = await generate(wrapOpts.registry, {
+          ...(await wrapOpts.renderOptionsFn(input, opts)),
         });
         metadata.output = output;
         return output;
       }
     );
   }) as ExecutablePrompt<z.infer<I>, O, CustomOptions>;
 
+  executablePrompt.ref = { name: wrapOpts.name, metadata: wrapOpts.metadata };
+
   executablePrompt.render = async (
     input?: I,
     opts?: PromptGenerateOptions<O, CustomOptions>
   ): Promise<GenerateOptions<O, CustomOptions>> => {
     return {
-      ...(await renderOptionsFn(input, opts)),
+      ...(await wrapOpts.renderOptionsFn(input, opts)),
     } as GenerateOptions<O, CustomOptions>;
   };
 
   executablePrompt.stream = (
     input?: I,
     opts?: PromptGenerateOptions<O, CustomOptions>
   ): GenerateStreamResponse<z.infer<O>> => {
-    return generateStream(registry, renderOptionsFn(input, opts));
+    return generateStream(
+      wrapOpts.registry,
+      wrapOpts.renderOptionsFn(input, opts)
+    );
   };
 
   executablePrompt.asTool = async (): Promise<ToolAction<I, O>> => {
-    return (await rendererAction) as unknown as ToolAction<I, O>;
+    return (await wrapOpts.rendererAction) as unknown as ToolAction<I, O>;
   };
   return executablePrompt;
 }

js/genkit/package.json

@@ -28,19 +28,20 @@
   "author": "genkit",
   "license": "Apache-2.0",
   "dependencies": {
-    "@genkit-ai/core": "workspace:*",
     "@genkit-ai/ai": "workspace:*",
+    "@genkit-ai/core": "workspace:*",
     "uuid": "^10.0.0"
   },
   "devDependencies": {
+    "@types/body-parser": "^1.19.5",
     "@types/express": "^4.17.21",
+    "@types/node": "^22.15.3",
     "@types/uuid": "^9.0.6",
     "npm-run-all": "^4.1.5",
     "rimraf": "^6.0.1",
     "tsup": "^8.3.5",
-    "typescript": "^4.9.0",
     "tsx": "^4.19.2",
-    "@types/body-parser": "^1.19.5"
+    "typescript": "^4.9.0"
   },
   "files": [
     "genkit-ui",

js/genkit/src/common.ts

@@ -19,6 +19,8 @@ export {
   BaseDataPointSchema,
   Document,
   DocumentDataSchema,
+  GenerateResponse,
+  GenerateResponseChunk,
   GenerationBlockedError,
   GenerationCommonConfigSchema,
   GenerationResponseError,
@@ -57,8 +59,6 @@ export {
   type GenerateOptions,
   type GenerateRequest,
   type GenerateRequestData,
-  type GenerateResponse,
-  type GenerateResponseChunk,
   type GenerateResponseChunkData,
   type GenerateResponseData,
   type GenerateStreamOptions,
@@ -82,6 +82,7 @@ export {
   type Part,
   type PromptAction,
   type PromptConfig,
+  type PromptGenerateOptions,
   type RankedDocument,
   type RerankerAction,
   type RerankerArgument,

js/genkit/src/genkit.ts

@@ -326,6 +326,8 @@ export class Genkit implements HasRegistry {
       return (await promise)(input, opts);
     }) as ExecutablePrompt<z.infer<I>, O, CustomOptions>;
 
+    executablePrompt.ref = { name };
+
     executablePrompt.render = async (
       input?: I,
       opts?: PromptGenerateOptions<O, CustomOptions>

js/genkit/tests/prompts_test.ts

@@ -72,6 +72,36 @@ describe('definePrompt', () => {
     defineEchoModel(ai);
   });
 
+  it('should define the prompt', async () => {
+    const prompt = ai.definePrompt({
+      name: 'hi',
+      metadata: { foo: 'bar' },
+      input: {
+        schema: z.object({
+          name: z.string(),
+        }),
+      },
+      messages: async (input) => {
+        return [
+          {
+            role: 'user',
+            content: [{ text: `hi ${input.name}` }],
+          },
+        ];
+      },
+    });
+
+    assert.deepStrictEqual(prompt.ref, {
+      name: 'hi',
+      metadata: { foo: 'bar' },
+    });
+
+    const lookedUpPrompt = ai.prompt('hi');
+    // This is a known limitation -- prompt lookup is async under the hood,
+    // so we can't actually get the metadata...
+    assert.deepStrictEqual(lookedUpPrompt.ref, { name: 'hi' }); // ideally metadatashould be: { foo: 'bar' }
+  });
+
   it('should apply middleware to a prompt call', async () => {
     const prompt = ai.definePrompt({
       name: 'hi',