@apollo/client-ai-apps 0.5.1 → 0.5.3

package/dist/utilities/getVariableNamesFromDocument.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getVariableNamesFromDocument.js","sourceRoot":"","sources":["../../src/utilities/getVariableNamesFromDocument.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAG3E,MAAM,UAAU,4BAA4B,CAAC,QAAsB;IACjE,MAAM,YAAY,GAAG,sBAAsB,CAAC,QAAQ,CAAC,CAAC;IACtD,OAAO,IAAI,GAAG,CACZ,YAAY,EAAE,mBAAmB,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAC3E,CAAC;AACJ,CAAC","sourcesContent":["import { getOperationDefinition } from \"@apollo/client/utilities/internal\";\nimport type { DocumentNode } from \"graphql\";\n\nexport function getVariableNamesFromDocument(document: DocumentNode) {\n  const operationDef = getOperationDefinition(document);\n  return new Set(\n    operationDef?.variableDefinitions?.map((v) => v.variable.name.value) ?? []\n  );\n}\n"]}

package/dist/utilities/index.d.ts

@@ -1,6 +1,9 @@
 export { aiClientSymbol } from "./constants.js";
 export { getVariablesForOperationFromToolInput } from "./getVariablesForOperationFromToolInput.js";
+export { getToolNamesFromDocument } from "./getToolNamesFromDocument.js";
+export { getVariableNamesFromDocument } from "./getVariableNamesFromDocument.js";
 export { cacheAsync } from "./cacheAsync.js";
 export { invariant } from "./invariant.js";
 export { promiseWithResolvers } from "./promiseWithResolvers.js";
+export { warnOnVariableMismatch } from "./warnOnVariableMismatch.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/utilities/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utilities/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,qCAAqC,EAAE,MAAM,4CAA4C,CAAC;AACnG,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utilities/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,qCAAqC,EAAE,MAAM,4CAA4C,CAAC;AACnG,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,EAAE,4BAA4B,EAAE,MAAM,mCAAmC,CAAC;AACjF,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/utilities/index.js

@@ -1,6 +1,9 @@
 export { aiClientSymbol } from "./constants.js";
 export { getVariablesForOperationFromToolInput } from "./getVariablesForOperationFromToolInput.js";
+export { getToolNamesFromDocument } from "./getToolNamesFromDocument.js";
+export { getVariableNamesFromDocument } from "./getVariableNamesFromDocument.js";
 export { cacheAsync } from "./cacheAsync.js";
 export { invariant } from "./invariant.js";
 export { promiseWithResolvers } from "./promiseWithResolvers.js";
+export { warnOnVariableMismatch } from "./warnOnVariableMismatch.js";
 //# sourceMappingURL=index.js.map

package/dist/utilities/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utilities/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,qCAAqC,EAAE,MAAM,4CAA4C,CAAC;AACnG,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC","sourcesContent":["export { aiClientSymbol } from \"./constants.js\";\nexport { getVariablesForOperationFromToolInput } from \"./getVariablesForOperationFromToolInput.js\";\nexport { cacheAsync } from \"./cacheAsync.js\";\nexport { invariant } from \"./invariant.js\";\nexport { promiseWithResolvers } from \"./promiseWithResolvers.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utilities/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,qCAAqC,EAAE,MAAM,4CAA4C,CAAC;AACnG,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,EAAE,4BAA4B,EAAE,MAAM,mCAAmC,CAAC;AACjF,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC","sourcesContent":["export { aiClientSymbol } from \"./constants.js\";\nexport { getVariablesForOperationFromToolInput } from \"./getVariablesForOperationFromToolInput.js\";\nexport { getToolNamesFromDocument } from \"./getToolNamesFromDocument.js\";\nexport { getVariableNamesFromDocument } from \"./getVariableNamesFromDocument.js\";\nexport { cacheAsync } from \"./cacheAsync.js\";\nexport { invariant } from \"./invariant.js\";\nexport { promiseWithResolvers } from \"./promiseWithResolvers.js\";\nexport { warnOnVariableMismatch } from \"./warnOnVariableMismatch.js\";\n"]}

package/dist/utilities/warnOnVariableMismatch.d.ts

@@ -0,0 +1,3 @@
+import type { DocumentNode, OperationVariables } from "@apollo/client";
+export declare function warnOnVariableMismatch(document: DocumentNode, toolInput: OperationVariables, actualVariables: OperationVariables | undefined): void;
+//# sourceMappingURL=warnOnVariableMismatch.d.ts.map

package/dist/utilities/warnOnVariableMismatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"warnOnVariableMismatch.d.ts","sourceRoot":"","sources":["../../src/utilities/warnOnVariableMismatch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAGvE,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,YAAY,EACtB,SAAS,EAAE,kBAAkB,EAC7B,eAAe,EAAE,kBAAkB,GAAG,SAAS,QAahD"}

package/dist/utilities/warnOnVariableMismatch.js

@@ -0,0 +1,10 @@
+import { getOperationName } from "@apollo/client/utilities/internal/internal.cjs";
+export function warnOnVariableMismatch(document, toolInput, actualVariables) {
+    const operationName = getOperationName(document, "(anonymous)");
+    console.warn(`The operation "${operationName}" has a @tool directive matching the current ` +
+        "tool call, but the variables provided to the query don't match the tool " +
+        "input. Use the `useHydratedVariables` hook returned from `createHydrationUtils` " +
+        "to provide the hydrated variables to the query. " +
+        "\n\nExpected variables:\n%o\n\nReceived:\n%o", toolInput, actualVariables);
+}
+//# sourceMappingURL=warnOnVariableMismatch.js.map

package/dist/utilities/warnOnVariableMismatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"warnOnVariableMismatch.js","sourceRoot":"","sources":["../../src/utilities/warnOnVariableMismatch.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,gDAAgD,CAAC;AAElF,MAAM,UAAU,sBAAsB,CACpC,QAAsB,EACtB,SAA6B,EAC7B,eAA+C;IAE/C,MAAM,aAAa,GAAG,gBAAgB,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;IAEhE,OAAO,CAAC,IAAI,CACV,kBAAkB,aAAa,+CAA+C;QAC5E,0EAA0E;QAC1E,kFAAkF;QAClF,kDAAkD;QAClD,8CAA8C,EAChD,SAAS,EACT,eAAe,CAChB,CAAC;AACJ,CAAC","sourcesContent":["import type { DocumentNode, OperationVariables } from \"@apollo/client\";\nimport { getOperationName } from \"@apollo/client/utilities/internal/internal.cjs\";\n\nexport function warnOnVariableMismatch(\n  document: DocumentNode,\n  toolInput: OperationVariables,\n  actualVariables: OperationVariables | undefined\n) {\n  const operationName = getOperationName(document, \"(anonymous)\");\n\n  console.warn(\n    `The operation \"${operationName}\" has a @tool directive matching the current ` +\n      \"tool call, but the variables provided to the query don't match the tool \" +\n      \"input. Use the `useHydratedVariables` hook returned from `createHydrationUtils` \" +\n      \"to provide the hydrated variables to the query. \" +\n      \"\\n\\nExpected variables:\\n%o\\n\\nReceived:\\n%o\",\n    toolInput,\n    actualVariables\n  );\n}\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "@apollo/client-ai-apps",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "publishConfig": {
     "access": "public"
   },
@@ -157,6 +157,7 @@
   },
   "dependencies": {
     "@graphql-tools/graphql-tag-pluck": "^8.3.23",
+    "@wry/equality": "^0.5.7",
     "cosmiconfig": "^9.0.0",
     "crypto-hash": "^4.0.0",
     "glob": "^11.0.3",

package/src/core/ApolloClient.ts

@@ -21,5 +21,5 @@ export class ApolloClient extends BaseApolloClient {
     );
   }
 
-  async waitForInitialization() {}
+  async connect() {}
 }

package/src/core/types.ts

@@ -2,13 +2,20 @@ import type { CallToolResult as McpCallToolResult } from "@modelcontextprotocol/
 import type { FormattedExecutionResult } from "graphql";
 
 export namespace ApolloMcpServerApps {
+  export interface Meta {
+    toolName: string;
+    [x: string]: unknown;
+  }
+
   export interface StructuredContent {
     result: FormattedExecutionResult;
     prefetch?: Record<string, FormattedExecutionResult>;
+    toolName?: string;
     [x: string]: unknown;
   }
 
   export interface CallToolResult extends McpCallToolResult {
+    _meta?: ApolloMcpServerApps.Meta;
     structuredContent: ApolloMcpServerApps.StructuredContent;
   }
 }

package/src/mcp/core/ApolloClient.ts

@@ -3,15 +3,24 @@ import {
   ApolloClient as BaseApolloClient,
   DocumentTransform,
 } from "@apollo/client";
+import type {
+  WatchQueryOptions,
+  ObservableQuery,
+  OperationVariables,
+} from "@apollo/client";
 import { removeDirectivesFromDocument } from "@apollo/client/utilities/internal";
 import { parse } from "graphql";
+import { equal } from "@wry/equality";
 import { __DEV__ } from "@apollo/client/utilities/environment";
 import type { ApplicationManifest } from "../../types/application-manifest.js";
 import { ToolCallLink } from "../link/ToolCallLink.js";
 import {
   aiClientSymbol,
   cacheAsync,
+  getToolNamesFromDocument,
+  getVariableNamesFromDocument,
   getVariablesForOperationFromToolInput,
+  warnOnVariableMismatch,
 } from "../../utilities/index.js";
 import { McpAppManager } from "./McpAppManager.js";
 
@@ -29,6 +38,8 @@ export class ApolloClient extends BaseApolloClient {
   /** @internal */
   readonly [aiClientSymbol] = true;
 
+  #toolInput: Record<string, unknown> | undefined;
+
   constructor(options: ApolloClient.Options) {
     const link = options.link ?? new ToolCallLink();
 
@@ -57,9 +68,63 @@ export class ApolloClient extends BaseApolloClient {
     this.appManager.close().catch(() => {});
   }
 
-  waitForInitialization = cacheAsync(async () => {
+  get toolInput() {
+    return this.#toolInput;
+  }
+
+  clearToolInput() {
+    this.#toolInput = undefined;
+  }
+
+  watchQuery<
+    T = any,
+    TVariables extends OperationVariables = OperationVariables,
+  >(options: WatchQueryOptions<TVariables, T>): ObservableQuery<T, TVariables> {
+    if (__DEV__) {
+      const toolInput = this.#toolInput;
+
+      if (toolInput) {
+        const toolName = this.appManager.toolName;
+        const hasMatchingTool =
+          !!toolName && getToolNamesFromDocument(options.query).has(toolName);
+
+        if (hasMatchingTool) {
+          // Clear after first matching comparison so this only fires once and
+          // remounting doesn't produce spurious warnings.
+          this.#toolInput = undefined;
+
+          const variableNames = getVariableNamesFromDocument(options.query);
+
+          if (variableNames.size > 0) {
+            const { variables } = options;
+            const toolInputVariables = Object.entries(toolInput).filter(
+              ([key]) => variableNames.has(key)
+            );
+
+            const hasToolInputMismatch = toolInputVariables.some(
+              ([key, value]) => !equal(value, variables?.[key])
+            );
+
+            if (hasToolInputMismatch) {
+              warnOnVariableMismatch(
+                options.query,
+                Object.fromEntries(toolInputVariables),
+                variables
+              );
+            }
+          }
+        }
+      }
+    }
+
+    return super.watchQuery(options);
+  }
+
+  connect = cacheAsync(async () => {
     const { prefetch, result, toolName, args } =
-      await this.appManager.waitForInitialization();
+      await this.appManager.connect();
+
+    this.#toolInput = args;
 
     this.manifest.operations.forEach((operation) => {
       if (operation.prefetchID && prefetch?.[operation.prefetchID]) {

package/src/mcp/core/McpAppManager.ts

@@ -16,7 +16,7 @@ export class McpAppManager {
   readonly app: App;
 
   #toolName: string | undefined;
-  #toolMetadata: ApolloMcpServerApps.CallToolResult["_meta"];
+  #toolMetadata: ApolloMcpServerApps.CallToolResult["_meta"] | undefined;
   #toolInput: Record<string, unknown> | undefined;
 
   constructor(manifest: ApplicationManifest) {
@@ -35,7 +35,7 @@ export class McpAppManager {
     return this.#toolInput;
   }
 
-  waitForInitialization = cacheAsync(async () => {
+  connect = cacheAsync(async () => {
     let toolResult = promiseWithResolvers<ApolloMcpServerApps.CallToolResult>();
     let toolInput = promiseWithResolvers<Parameters<App["ontoolinput"]>[0]>();
 
@@ -49,12 +49,21 @@ export class McpAppManager {
       toolInput.resolve(params);
     };
 
-    await this.connect();
+    await this.connectToHost();
 
     const { structuredContent, _meta } = await toolResult.promise;
     const { arguments: args } = await toolInput.promise;
 
-    this.#toolName = this.app.getHostContext()?.toolInfo?.tool.name;
+    // Some hosts do not provide toolInfo in the ui/initialize response, so we
+    // fallback to `_meta.toolName` provided by Apollo MCP server if the value
+    // is not available.
+    this.#toolName =
+      this.app.getHostContext()?.toolInfo?.tool.name ??
+      _meta?.toolName ??
+      // Some hosts do not forward `_meta` nor do they provide `toolInfo`. Our
+      // MCP server provides `toolName` in `structuredContent` as a workaround
+      // that we can use if all else fails
+      structuredContent.toolName;
     this.#toolMetadata = _meta;
     this.#toolInput = args;
 
@@ -84,7 +93,7 @@ export class McpAppManager {
     return result.structuredContent;
   }
 
-  private async connect() {
+  private async connectToHost() {
     try {
       return await this.app.connect(
         new PostMessageTransport(window.parent, window.parent)

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

@@ -1,9 +1,10 @@
-import { expect, test, vi } from "vitest";
+import { expect, test, vi, describe } from "vitest";
 import { ApolloClient } from "../ApolloClient.js";
 import { ApolloLink, HttpLink, InMemoryCache, gql } from "@apollo/client";
 import { print } from "@apollo/client/utilities";
 import { ToolCallLink } from "../../link/ToolCallLink.js";
 import {
+  graphqlToolResult,
   minimalHostContextWithToolName,
   mockApplicationManifest,
   mockMcpHost,
@@ -57,7 +58,7 @@ test("writes tool result data to cache", async () => {
   });
   host.sendToolInput({ arguments: { id: "1" } });
 
-  await client.waitForInitialization();
+  await client.connect();
 
   expect(client.extract()).toEqual({
     "Product:1": {
@@ -124,7 +125,7 @@ test("writes prefetch data to cache", async () => {
   });
   host.sendToolInput({ arguments: {} });
 
-  await client.waitForInitialization();
+  await client.connect();
 
   expect(client.extract()).toEqual({
     "Product:1": {
@@ -213,7 +214,7 @@ test("writes prefetch and tool response data to cache when both are provided", a
   });
   host.sendToolInput({ arguments: { id: "2" } });
 
-  await client.waitForInitialization();
+  await client.connect();
 
   expect(client.extract()).toEqual({
     "Product:1": {
@@ -281,7 +282,7 @@ test("excludes extra tool input variables not defined in the operation", async (
   });
   host.sendToolInput({ arguments: { id: "1", extraParam: "ignored" } });
 
-  await client.waitForInitialization();
+  await client.connect();
 
   expect(client.extract()).toEqual({
     "Product:1": {
@@ -345,7 +346,7 @@ test("allows for custom links provided to the constructor", async () => {
     },
   }));
 
-  await client.waitForInitialization();
+  await client.connect();
 
   const variables = { id: "1" };
   const query = gql(manifest.operations[0].body);
@@ -462,3 +463,105 @@ test("creates a default ToolCallLink when no link is provided", () => {
     });
   }).not.toThrow();
 });
+
+describe("watchQuery dev warnings", () => {
+  const query = gql`
+    query Products($category: String!, $page: Int!, $sortBy: String!)
+    @tool(name: "GetProductsByCategory") {
+      products(category: $category, page: $page, sortBy: $sortBy) {
+        id
+      }
+    }
+  `;
+
+  async function setupClient({
+    toolInput,
+  }: {
+    toolInput: Record<string, unknown>;
+  }) {
+    const client = new ApolloClient({
+      cache: new InMemoryCache(),
+      manifest: mockApplicationManifest(),
+    });
+    using host = await mockMcpHost({
+      hostContext: minimalHostContextWithToolName("GetProductsByCategory"),
+    });
+    host.onCleanup(() => client.stop());
+    host.sendToolResult(graphqlToolResult({ data: { products: [] } }));
+    host.sendToolInput({ arguments: toolInput });
+    await client.connect();
+    return client;
+  }
+
+  test("warns when variables don't match tool input", async () => {
+    using _ = spyOnConsole("debug", "warn");
+    const client = await setupClient({
+      toolInput: { category: "electronics", page: 1, sortBy: "title" },
+    });
+
+    client.watchQuery({
+      query,
+      variables: { category: "music", page: 1, sortBy: "name" },
+    });
+
+    expect(console.warn).toHaveBeenCalledWith(
+      expect.stringContaining("useHydratedVariables"),
+      { category: "electronics", page: 1, sortBy: "title" },
+      { category: "music", page: 1, sortBy: "name" }
+    );
+  });
+
+  test("does not warn when variables match tool input", async () => {
+    using _ = spyOnConsole("debug", "warn");
+    const client = await setupClient({
+      toolInput: { category: "electronics", page: 1, sortBy: "title" },
+    });
+
+    client.watchQuery({
+      query,
+      variables: { category: "electronics", page: 1, sortBy: "title" },
+    });
+
+    expect(console.warn).not.toHaveBeenCalled();
+  });
+
+  test("does not warn when query has no matching @tool directive", async () => {
+    using _ = spyOnConsole("debug", "warn");
+    const client = await setupClient({
+      toolInput: { category: "electronics", page: 1, sortBy: "title" },
+    });
+
+    const queryWithoutTool = gql`
+      query Products($category: String!) {
+        products(category: $category) {
+          id
+        }
+      }
+    `;
+
+    client.watchQuery({
+      query: queryWithoutTool,
+      variables: { category: "music" },
+    });
+
+    expect(console.warn).not.toHaveBeenCalled();
+  });
+
+  test("warning fires at most once (subsequent calls don't re-warn)", async () => {
+    using _ = spyOnConsole("debug", "warn");
+    const client = await setupClient({
+      toolInput: { category: "electronics", page: 1, sortBy: "title" },
+    });
+
+    client.watchQuery({
+      query,
+      variables: { category: "music", page: 1, sortBy: "name" },
+    });
+    client.watchQuery({
+      query,
+      variables: { category: "music", page: 1, sortBy: "name" },
+    });
+
+    expect(console.warn).toHaveBeenCalledTimes(1);
+  });
+});

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

@@ -3,6 +3,7 @@ import { gql, InMemoryCache } from "@apollo/client";
 import { execute } from "@apollo/client/link";
 import { ApolloClient } from "../../core/ApolloClient.js";
 import {
+  minimalHostContextWithToolName,
   mockApplicationManifest,
   mockMcpHost,
   ObservableStream,
@@ -23,15 +24,23 @@ test("delegates query execution to MCP host", async () => {
     manifest: mockApplicationManifest(),
   });
 
-  using host = await mockMcpHost();
+  using host = await mockMcpHost({
+    hostContext: minimalHostContextWithToolName("GetProduct"),
+  });
   host.onCleanup(() => client.stop());
 
+  host.sendToolInput({ arguments: {} });
   host.sendToolResult({
     _meta: { toolName: "GetProduct" },
     content: [],
-    structuredContent: {},
+    structuredContent: {
+      result: {
+        data: {
+          product: null,
+        },
+      },
+    },
   });
-  host.sendToolInput({ arguments: {} });
 
   host.mockToolCall("execute", () => ({
     content: [],
@@ -40,7 +49,7 @@ test("delegates query execution to MCP host", async () => {
     },
   }));
 
-  await client.waitForInitialization();
+  await client.connect();
 
   const observable = execute(new ToolCallLink(), { query }, { client });
   const stream = new ObservableStream(observable);