@apollo/client-ai-apps 0.6.3 → 0.6.5

package/src/mcp/link/__tests__/ToolCallLink.test.ts

@@ -11,6 +11,57 @@ import {
 } from "../../../testing/internal/index.js";
 import { ToolCallLink } from "../ToolCallLink.js";
 
+test("merges _meta.structuredContent into result for @private fields", async () => {
+  using _ = spyOnConsole("debug");
+  const query = gql`
+    query GreetingQuery {
+      greeting @private
+    }
+  `;
+
+  const client = new ApolloClient({
+    cache: new InMemoryCache(),
+    manifest: mockApplicationManifest(),
+  });
+
+  using host = await mockMcpHost({
+    hostContext: minimalHostContextWithToolName("GetProduct"),
+  });
+  host.onCleanup(() => client.stop());
+
+  host.sendToolInput({ arguments: {} });
+  host.sendToolResult({
+    _meta: { toolName: "GetProduct" },
+    content: [],
+    structuredContent: {
+      result: {
+        data: {
+          product: null,
+        },
+      },
+    },
+  });
+
+  host.mockToolCall("execute", () => ({
+    content: [],
+    structuredContent: {},
+    _meta: {
+      structuredContent: { data: { greeting: "Hello, private world" } },
+    },
+  }));
+
+  await client.connect();
+
+  const observable = execute(new ToolCallLink(), { query }, { client });
+  const stream = new ObservableStream(observable);
+
+  await expect(stream).toEmitValue({
+    data: { greeting: "Hello, private world" },
+  });
+
+  await expect(stream).toComplete();
+});
+
 test("delegates query execution to MCP host", async () => {
   using _ = spyOnConsole("debug");
   const query = gql`

package/src/openai/core/ApolloClient.ts

@@ -126,25 +126,30 @@ export class ApolloClient extends BaseApolloClient {
   }
 
   connect = cacheAsync(async () => {
-    const { prefetch, result, toolName, args } =
+    const { structuredContent, toolName, args } =
       await this.appManager.connect();
 
     this.#toolInput = args;
 
     this.manifest.operations.forEach((operation) => {
-      if (operation.prefetchID && prefetch?.[operation.prefetchID]) {
+      if (
+        operation.prefetchID &&
+        structuredContent.prefetch?.[operation.prefetchID]
+      ) {
         this.writeQuery({
           query: parse(operation.body),
-          data: prefetch[operation.prefetchID].data,
+          data: structuredContent.prefetch[operation.prefetchID].data,
         });
       }
 
       if (operation.tools.find((tool) => tool.name === toolName)) {
-        this.writeQuery({
-          query: parse(operation.body),
-          data: result.data,
-          variables: getVariablesForOperationFromToolInput(operation, args),
-        });
+        if (structuredContent.result?.data) {
+          this.writeQuery({
+            query: parse(operation.body),
+            data: structuredContent.result.data,
+            variables: getVariablesForOperationFromToolInput(operation, args),
+          });
+        }
       }
     });
   });

package/src/openai/core/McpAppManager.ts

@@ -13,6 +13,7 @@ import type { ApolloMcpServerApps } from "../../core/types";
 
 type ExecuteQueryCallToolResult = Omit<CallToolResult, "structuredContent"> & {
   structuredContent: FormattedExecutionResult;
+  _meta?: { structuredContent?: FormattedExecutionResult };
 };
 
 /** @internal */
@@ -100,9 +101,14 @@ export class McpAppManager {
     this.#toolMetadata = window.openai.toolResponseMetadata;
 
     return {
-      ...structuredContent,
+      structuredContent: {
+        ...structuredContent,
+        ...(
+          window.openai.toolResponseMetadata as ApolloMcpServerApps.Meta | null
+        )?.structuredContent,
+      },
       toolName: this.toolName,
-      args: this.toolInput,
+      args: this.#toolInput,
     };
   });
 
@@ -122,7 +128,10 @@ export class McpAppManager {
       arguments: { query: print(query), variables },
     })) as ExecuteQueryCallToolResult;
 
-    return result.structuredContent;
+    return {
+      ...result.structuredContent,
+      ...result._meta?.structuredContent,
+    };
   }
 
   private async connectToHost() {

package/src/openai/core/__tests__/ApolloClient.test.ts

@@ -2,6 +2,7 @@ import { expect, test, describe, vi } from "vitest";
 import { ApolloClient } from "../ApolloClient.js";
 import { parse } from "graphql";
 import { ApolloLink, HttpLink, InMemoryCache, gql } from "@apollo/client";
+import { print } from "@apollo/client/utilities";
 import { ToolCallLink } from "../../link/ToolCallLink.js";
 import {
   graphqlToolResult,
@@ -91,6 +92,62 @@ describe("Client Basics", () => {
   });
 });
 
+test("merges _meta.structuredContent into result for @private fields", async () => {
+  stubOpenAiGlobals();
+  using _ = spyOnConsole("debug");
+  const manifest = mockApplicationManifest();
+  const client = new ApolloClient({
+    cache: new InMemoryCache(),
+    manifest,
+  });
+  using host = await mockMcpHost();
+
+  const query = gql`
+    query Product {
+      id
+      title @private
+    }
+  `;
+
+  host.onCleanup(() => client.stop());
+
+  host.sendToolInput({});
+  host.sendToolResult({
+    content: [],
+    structuredContent: {},
+  });
+
+  host.mockToolCall("execute", () => ({
+    content: [],
+    structuredContent: {},
+    _meta: {
+      structuredContent: {
+        data: {
+          product: {
+            id: "1",
+            title: "Private Pen",
+            __typename: "Product",
+          },
+        },
+      },
+    },
+  }));
+
+  await client.connect();
+
+  await expect(
+    client.query({ query, variables: { id: "1" } })
+  ).resolves.toStrictEqual({
+    data: {
+      product: {
+        __typename: "Product",
+        id: "1",
+        title: "Private Pen",
+      },
+    },
+  });
+});
+
 describe("prefetchData", () => {
   test("caches tool response when data is provided", async () => {
     stubOpenAiGlobals({ toolInput: { id: 1 } });
@@ -400,6 +457,252 @@ describe("prefetchData", () => {
   });
 });
 
+test("reads result data from toolResponseMetadata.structuredContent", async () => {
+  stubOpenAiGlobals({
+    toolInput: { id: "1" },
+    toolResponseMetadata: {
+      structuredContent: {
+        result: {
+          data: {
+            product: { id: "1", title: "Pen", __typename: "Product" },
+          },
+        },
+      },
+    },
+  });
+  using _ = spyOnConsole("debug");
+
+  const query = gql`
+    query Product($id: ID!) {
+      product(id: $id) @private {
+        id
+        title
+        __typename
+      }
+    }
+  `;
+
+  const client = new ApolloClient({
+    cache: new InMemoryCache(),
+    manifest: mockApplicationManifest({
+      operations: [
+        {
+          id: "c43af26552874026c3fb346148c5795896aa2f3a872410a0a2621cffee25291c",
+          name: "Product",
+          type: "query",
+          body: print(query),
+          variables: { id: "ID" },
+          prefetch: false,
+          tools: [{ name: "GetProduct", description: "Get a product" }],
+        },
+      ],
+    }),
+  });
+  using host = await mockMcpHost({
+    hostContext: minimalHostContextWithToolName("GetProduct"),
+  });
+  host.onCleanup(() => client.stop());
+
+  host.sendToolInput({ arguments: { id: "1" } });
+  host.sendToolResult({
+    content: [],
+    structuredContent: {},
+  });
+
+  await client.connect();
+
+  expect(client.extract()).toEqual({
+    "Product:1": {
+      __typename: "Product",
+      id: "1",
+      title: "Pen",
+    },
+    ROOT_QUERY: {
+      __typename: "Query",
+      'product({"id":"1"})@private': { __ref: "Product:1" },
+    },
+  });
+});
+
+test("merges prefetch from structuredContent and result from toolResponseMetadata.structuredContent", async () => {
+  stubOpenAiGlobals({
+    toolInput: { id: "2" },
+    toolResponseMetadata: {
+      structuredContent: {
+        result: {
+          data: {
+            product: { id: "2", title: "iPad", __typename: "Product" },
+          },
+        },
+      },
+    },
+  });
+  using _ = spyOnConsole("debug");
+
+  const prefetchQuery = gql`
+    query TopProducts {
+      topProducts {
+        id
+        title
+        __typename
+      }
+    }
+  `;
+
+  const query = gql`
+    query Product($id: ID!) {
+      product(id: $id) @private {
+        id
+        title
+        __typename
+      }
+    }
+  `;
+
+  const client = new ApolloClient({
+    cache: new InMemoryCache(),
+    manifest: mockApplicationManifest({
+      operations: [
+        {
+          id: "1",
+          name: "TopProducts",
+          body: print(prefetchQuery),
+          type: "query",
+          variables: {},
+          prefetch: true,
+          prefetchID: "__anonymous",
+          tools: [
+            {
+              name: "TopProducts",
+              description: "Shows the currently highest rated products.",
+            },
+          ],
+        },
+        {
+          id: "2",
+          name: "Product",
+          body: print(query),
+          type: "query",
+          variables: { id: "ID" },
+          prefetch: false,
+          tools: [{ name: "GetProduct", description: "Get a product" }],
+        },
+      ],
+    }),
+  });
+  using host = await mockMcpHost({
+    hostContext: minimalHostContextWithToolName("GetProduct"),
+  });
+  host.onCleanup(() => client.stop());
+
+  host.sendToolInput({ arguments: { id: "2" } });
+  host.sendToolResult({
+    content: [],
+    structuredContent: {
+      prefetch: {
+        __anonymous: {
+          data: {
+            topProducts: [{ id: "1", title: "iPhone", __typename: "Product" }],
+          },
+        },
+      },
+    },
+  });
+
+  await client.connect();
+
+  expect(client.extract()).toEqual({
+    "Product:1": {
+      __typename: "Product",
+      id: "1",
+      title: "iPhone",
+    },
+    "Product:2": {
+      __typename: "Product",
+      id: "2",
+      title: "iPad",
+    },
+    ROOT_QUERY: {
+      __typename: "Query",
+      topProducts: [{ __ref: "Product:1" }],
+      'product({"id":"2"})@private': { __ref: "Product:2" },
+    },
+  });
+});
+
+test("toolResponseMetadata.structuredContent wins over structuredContent", async () => {
+  stubOpenAiGlobals({
+    toolInput: { id: "1" },
+    toolResponseMetadata: {
+      structuredContent: {
+        result: {
+          data: {
+            product: { id: "1", title: "Meta title", __typename: "Product" },
+          },
+        },
+      },
+    },
+  });
+  using _ = spyOnConsole("debug");
+
+  const query = gql`
+    query Product($id: ID!) {
+      product(id: $id) {
+        id
+        title @private
+        __typename
+      }
+    }
+  `;
+
+  const client = new ApolloClient({
+    cache: new InMemoryCache(),
+    manifest: mockApplicationManifest({
+      operations: [
+        {
+          id: "1",
+          name: "Product",
+          body: print(query),
+          type: "query",
+          variables: { id: "ID" },
+          prefetch: false,
+          tools: [{ name: "GetProduct", description: "Get a product" }],
+        },
+      ],
+    }),
+  });
+  using host = await mockMcpHost({
+    hostContext: minimalHostContextWithToolName("GetProduct"),
+  });
+  host.onCleanup(() => client.stop());
+
+  host.sendToolInput({ arguments: { id: "1" } });
+  host.sendToolResult({
+    content: [],
+    structuredContent: {
+      result: {
+        data: {
+          product: { id: "1", __typename: "Product" },
+        },
+      },
+    },
+  });
+
+  await client.connect();
+
+  expect(client.extract()).toEqual({
+    "Product:1": {
+      __typename: "Product",
+      id: "1",
+      "title@private": "Meta title",
+    },
+    ROOT_QUERY: {
+      __typename: "Query",
+      'product({"id":"1"})': { __ref: "Product:1" },
+    },
+  });
+});
+
 test("connects using window.openai.toolOutput when tool-result notification is not sent", async () => {
   stubOpenAiGlobals({
     toolOutput: {

package/src/types/application-manifest.ts

@@ -32,6 +32,7 @@ export type ManifestTool = {
   name: string;
   description: string;
   extraInputs?: ManifestExtraInput[];
+  extraOutputs?: Record<string, unknown>;
   labels?: ManifestLabels;
 };
 

package/src/vite/__tests__/apolloClientAiApps.test.ts

@@ -143,6 +143,35 @@ describe("operations", () => {
     `);
   });
 
+  test("writes extraOutputs to the manifest", async () => {
+    vol.fromJSON({
+      "package.json": mockPackageJson(),
+      "src/my-component.tsx": declareOperation(gql`
+        query HelloWorldQuery
+        @tool(
+          name: "hello-world"
+          description: "This is an awesome tool!"
+          extraOutputs: { foo: "bar", nested: { label: "count" } }
+        ) {
+          helloWorld
+        }
+      `),
+    });
+
+    await using server = await setupServer({
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
+    });
+    await server.listen();
+
+    const manifest = readManifestFile();
+    expect(manifest.operations[0].tools[0].extraOutputs).toEqual({
+      foo: "bar",
+      nested: { label: "count" },
+    });
+  });
+
   test("handles operations with fragments in the same file", async () => {
     vol.fromJSON({
       "package.json": mockPackageJson(),
@@ -890,6 +919,33 @@ describe("@tool validation", () => {
     );
   });
 
+  test("errors when extraOutputs is not an object", async () => {
+    vol.fromJSON({
+      "package.json": mockPackageJson(),
+      "src/my-component.tsx": declareOperation(gql`
+        query HelloWorldQuery
+        @tool(
+          name: "hello-world"
+          description: "hello"
+          extraOutputs: [1, 2, 3]
+        ) {
+          helloWorld
+        }
+      `),
+    });
+
+    await expect(async () => {
+      await using server = await setupServer({
+        plugins: [
+          apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+        ],
+      });
+      await server.listen();
+    }).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[Error: Expected argument 'extraOutputs' to be of type 'ObjectValue' but found 'ListValue' instead.]`
+    );
+  });
+
   test("errors when extraInputs is not an array", async () => {
     vol.fromJSON({
       "package.json": mockPackageJson(),

package/src/vite/apolloClientAiApps.ts

@@ -690,10 +690,7 @@ export function apolloClientAiApps(
         await processFile(fullPath);
       }
 
-      // We don't want to do this here on builds cause it just gets overwritten anyways. We'll call it on writeBundle instead.
-      if (config.command === "serve") {
-        await Promise.all([generateManifest(), generateTypesFiles()]);
-      }
+      await Promise.all([generateManifest(), generateTypesFiles()]);
     },
     configResolved(resolvedConfig) {
       config = resolvedConfig;
@@ -797,9 +794,6 @@ export function apolloClientAiApps(
           .replace(/(src=["'])\/([^"']+)/gi, `$1${baseUrl}/$2`)
       );
     },
-    async writeBundle() {
-      await Promise.all([generateManifest(), generateTypesFiles()]);
-    },
   } satisfies Plugin;
 }
 
@@ -880,6 +874,10 @@ const processQueryLink = new ApolloLink((operation) => {
         getDirectiveArgument("extraInputs", directive),
         Kind.LIST
       ),
+      extraOutputs: maybeGetArgumentValue(
+        getDirectiveArgument("extraOutputs", directive),
+        Kind.OBJECT
+      ),
       labels: maybeGetArgumentValue(
         getDirectiveArgument("labels", directive),
         Kind.OBJECT
@@ -1050,5 +1048,6 @@ const ToolDirectiveSchema = z.strictObject({
       })
     )
   ),
+  extraOutputs: z.optional(z.record(z.string(), z.unknown())),
   labels: ApolloClientAiAppsConfigSchema.shape.labels.optional(),
 });