@stigmer/react 3.12.1 → 3.12.2

package/src/mcp-server/__tests__/definitionDrift.test.ts

@@ -0,0 +1,245 @@
+import { describe, expect, it } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import {
+  HttpServerConfigSchema,
+  McpServerAuthSchema,
+  McpServerSpecSchema,
+  StdioServerConfigSchema,
+  ToolApprovalPolicySchema,
+} from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
+import { EnvVarDeclarationSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
+import { samples } from "../../test/samples";
+import {
+  buildRefreshInput,
+  computeDefinitionDrift,
+} from "../internal/definitionDrift";
+
+/**
+ * Pins the drift comparison and refresh-payload semantics of
+ * stigmer/stigmer#228. The scenarios mirror the reporting incident: the
+ * monday.com seedpack template was fixed (custom token header ->
+ * `Authorization: Bearer`, plus `oauth_only`), and pre-fix copies had to
+ * detect exactly that class of change — while cosmetic template edits
+ * (descriptions, icons, tags) must never nag.
+ */
+
+/** The org copy: pre-fix monday.com configuration. */
+function preFixCopy(): McpServer {
+  const server = samples.mcpServer({ name: "Monday", org: "acme", slug: "monday" });
+  server.spec = create(McpServerSpecSchema, {
+    description: "monday.com MCP server",
+    iconUrl: "https://example.com/monday.svg",
+    tags: ["monday", "project-management"],
+    serverType: {
+      case: "http",
+      value: create(HttpServerConfigSchema, {
+        url: "https://mcp.monday.com/mcp",
+        headers: { MONDAY_TOKEN: "${MONDAY_ACCESS_TOKEN}" },
+      }),
+    },
+    env: {
+      MONDAY_ACCESS_TOKEN: create(EnvVarDeclarationSchema, {
+        isSecret: true,
+        description: "monday.com personal API token",
+      }),
+    },
+    defaultEnabledTools: ["boards_list"],
+    pinnedToolApprovals: [
+      create(ToolApprovalPolicySchema, {
+        toolName: "items_delete",
+        message: "Deletes board items",
+        fromDestructiveHint: true,
+      }),
+    ],
+    auth: create(McpServerAuthSchema, {
+      targetEnvVar: "MONDAY_ACCESS_TOKEN",
+      tokenLifetimeHint: "1h",
+    }),
+  });
+  return server;
+}
+
+/** The marketplace template after the fix. */
+function fixedTemplate(): McpServer {
+  const server = preFixCopy();
+  server.metadata!.org = "stigmer";
+  server.spec!.serverType = {
+    case: "http",
+    value: create(HttpServerConfigSchema, {
+      url: "https://mcp.monday.com/mcp",
+      headers: { Authorization: "Bearer ${MONDAY_ACCESS_TOKEN}" },
+    }),
+  };
+  server.spec!.env = {
+    MONDAY_ACCESS_TOKEN: create(EnvVarDeclarationSchema, {
+      isSecret: true,
+      // Rewritten by the fix — descriptions are cosmetic and must not
+      // register as environment-variable drift on their own.
+      description: "OAuth access token, obtained automatically via Connect.",
+    }),
+  };
+  server.spec!.auth = create(McpServerAuthSchema, {
+    targetEnvVar: "MONDAY_ACCESS_TOKEN",
+    tokenLifetimeHint: "1h",
+    oauthOnly: true,
+  });
+  // Policy fields differ on the template: a refresh must NOT import them.
+  server.spec!.defaultEnabledTools = [];
+  server.spec!.pinnedToolApprovals = [];
+  return server;
+}
+
+describe("computeDefinitionDrift", () => {
+  it("returns null when connection-defining configuration matches", () => {
+    expect(computeDefinitionDrift(preFixCopy(), preFixCopy())).toBeNull();
+  });
+
+  it("detects the monday.com incident: header fix + oauth_only", () => {
+    expect(computeDefinitionDrift(preFixCopy(), fixedTemplate())).toEqual([
+      "headers",
+      "authentication",
+    ]);
+  });
+
+  it("ignores cosmetic-only template changes", () => {
+    const template = preFixCopy();
+    template.spec!.description = "A much better description";
+    template.spec!.iconUrl = "https://example.com/new-icon.svg";
+    template.spec!.tags = ["monday", "pm", "extra"];
+    template.spec!.repositoryUrl = "https://github.com/mondaycom/mcp-v2";
+    template.spec!.githubStars = 999;
+    expect(computeDefinitionDrift(preFixCopy(), template)).toBeNull();
+  });
+
+  it("ignores user policy differences (enabled tools, approval pins)", () => {
+    const template = preFixCopy();
+    template.spec!.defaultEnabledTools = ["boards_list", "items_create"];
+    template.spec!.pinnedToolApprovals = [];
+    expect(computeDefinitionDrift(preFixCopy(), template)).toBeNull();
+  });
+
+  it("detects endpoint URL changes", () => {
+    const template = preFixCopy();
+    (template.spec!.serverType.value as { url: string }).url =
+      "https://mcp2.monday.com/mcp";
+    expect(computeDefinitionDrift(preFixCopy(), template)).toEqual(["endpoint"]);
+  });
+
+  it("detects a transport switch as a single coarse change", () => {
+    const template = preFixCopy();
+    template.spec!.serverType = {
+      case: "stdio",
+      value: create(StdioServerConfigSchema, { command: "npx" }),
+    };
+    expect(computeDefinitionDrift(preFixCopy(), template)).toEqual(["transport"]);
+  });
+
+  it("detects functional env changes (new required var)", () => {
+    const template = preFixCopy();
+    template.spec!.env = {
+      ...template.spec!.env,
+      MONDAY_WORKSPACE_ID: create(EnvVarDeclarationSchema, { isSecret: false }),
+    };
+    expect(computeDefinitionDrift(preFixCopy(), template)).toEqual([
+      "environmentVariables",
+    ]);
+  });
+
+  it("detects an is_secret flip as functional env drift", () => {
+    const template = preFixCopy();
+    template.spec!.env = {
+      MONDAY_ACCESS_TOKEN: create(EnvVarDeclarationSchema, {
+        isSecret: false,
+        description: "monday.com personal API token",
+      }),
+    };
+    expect(computeDefinitionDrift(preFixCopy(), template)).toEqual([
+      "environmentVariables",
+    ]);
+  });
+
+  it("compares stdio command and args", () => {
+    const current = preFixCopy();
+    current.spec!.serverType = {
+      case: "stdio",
+      value: create(StdioServerConfigSchema, {
+        command: "npx",
+        args: ["-y", "@mondaycom/mcp@1"],
+      }),
+    };
+    const template = preFixCopy();
+    template.spec!.serverType = {
+      case: "stdio",
+      value: create(StdioServerConfigSchema, {
+        command: "npx",
+        args: ["-y", "@mondaycom/mcp@2"],
+      }),
+    };
+    expect(computeDefinitionDrift(current, template)).toEqual(["command"]);
+  });
+
+  it("treats header map key order as irrelevant", () => {
+    const current = preFixCopy();
+    current.spec!.serverType = {
+      case: "http",
+      value: create(HttpServerConfigSchema, {
+        url: "https://mcp.monday.com/mcp",
+        headers: { "X-One": "1", "X-Two": "2" },
+      }),
+    };
+    const template = preFixCopy();
+    template.spec!.serverType = {
+      case: "http",
+      value: create(HttpServerConfigSchema, {
+        url: "https://mcp.monday.com/mcp",
+        headers: { "X-Two": "2", "X-One": "1" },
+      }),
+    };
+    expect(computeDefinitionDrift(current, template)).toBeNull();
+  });
+});
+
+describe("buildRefreshInput", () => {
+  it("takes the definition from the template and keeps the user's identity and policy", () => {
+    const current = preFixCopy();
+    const template = fixedTemplate();
+    const input = buildRefreshInput(current, template);
+
+    // Identity: the update lands on the user's own resource.
+    expect(input.name).toBe("Monday");
+    expect(input.org).toBe("acme");
+    expect(input.slug).toBe("monday");
+
+    // Definition: the fixed template configuration wins.
+    expect(input.http?.headers).toEqual({
+      Authorization: "Bearer ${MONDAY_ACCESS_TOKEN}",
+    });
+    expect(input.auth?.oauthOnly).toBe(true);
+    expect(input.env?.MONDAY_ACCESS_TOKEN?.description).toBe(
+      "OAuth access token, obtained automatically via Connect.",
+    );
+
+    // User policy: never reset by a refresh (the template has neither).
+    expect(input.defaultEnabledTools).toEqual(["boards_list"]);
+    expect(input.pinnedToolApprovals).toEqual([
+      {
+        toolName: "items_delete",
+        message: "Deletes board items",
+        fromDestructiveHint: true,
+      },
+    ]);
+  });
+
+  it("carries a template transport switch cleanly", () => {
+    const current = preFixCopy();
+    const template = preFixCopy();
+    template.spec!.serverType = {
+      case: "stdio",
+      value: create(StdioServerConfigSchema, { command: "npx", args: ["-y", "mcp"] }),
+    };
+    const input = buildRefreshInput(current, template);
+    expect(input.stdio).toEqual({ command: "npx", args: ["-y", "mcp"] });
+    expect(input.http).toBeUndefined();
+  });
+});

package/src/mcp-server/__tests__/mcpServerToInput.test.ts

@@ -0,0 +1,201 @@
+import { describe, expect, it } from "vitest";
+import { create, toJson } from "@bufbuild/protobuf";
+import type { DescMessage } from "@bufbuild/protobuf";
+import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import {
+  HttpServerConfigSchema,
+  McpServerAuthSchema,
+  McpServerSpecSchema,
+  StdioServerConfigSchema,
+  ToolApprovalPolicySchema,
+} from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
+import { EnvVarDeclarationSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
+import { ApiResourceReferenceSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { buildMcpServerProto } from "@stigmer/sdk";
+import { mcpServerToInput } from "../internal/mcpServerToInput.js";
+
+/**
+ * `mcpServerToInput` powers every read-modify-write update in the SDK: the
+ * backend does FULL spec replacement, so any spec field the conversion
+ * fails to carry is silently ERASED by the very next inline edit. That is
+ * not hypothetical — `spec.tags` and `auth.oauth_only` were lost this way
+ * until the conversion (and the SDK input type) learned them.
+ *
+ * Two layers of protection:
+ *
+ * 1. A field-inventory fence: pins the exact field set of every proto
+ *    message the conversion traverses. Adding a field to the proto makes
+ *    this test fail with instructions, instead of shipping a new
+ *    silent-data-loss bug.
+ * 2. A round-trip proof: a fully-populated server survives
+ *    `mcpServerToInput` -> `buildMcpServerProto` with its spec intact.
+ */
+
+// ---------------------------------------------------------------------------
+// Layer 1 — field-inventory fence
+// ---------------------------------------------------------------------------
+
+/**
+ * Every message the conversion walks, with its complete expected field set
+ * (proto `localName`s; oneof members appear as individual fields).
+ *
+ * If this fails because a field was ADDED: map the new field in
+ * `mcpServerToInput`, populate it in `fullyPopulatedServer` below, and only
+ * then extend the expected list here.
+ */
+const EXPECTED_FIELD_INVENTORY: ReadonlyArray<
+  readonly [DescMessage, readonly string[]]
+> = [
+  [
+    McpServerSpecSchema,
+    [
+      "auth",
+      "defaultEnabledTools",
+      "description",
+      "env",
+      "githubStars",
+      "http",
+      "iconUrl",
+      "pinnedToolApprovals",
+      "repositoryUrl",
+      "stdio",
+      "tags",
+    ],
+  ],
+  [StdioServerConfigSchema, ["args", "command", "workingDir"]],
+  [HttpServerConfigSchema, ["headers", "queryParams", "timeoutSeconds", "url"]],
+  [EnvVarDeclarationSchema, ["description", "isSecret", "optional"]],
+  [ToolApprovalPolicySchema, ["fromDestructiveHint", "message", "toolName"]],
+  [
+    McpServerAuthSchema,
+    [
+      "discoveryUrl",
+      "oauthAppRef",
+      "oauthOnly",
+      "scopeHints",
+      "targetEnvVar",
+      "tokenLifetimeHint",
+    ],
+  ],
+];
+
+describe("mcpServerToInput field-inventory fence", () => {
+  it.each(
+    EXPECTED_FIELD_INVENTORY.map(
+      ([schema, fields]) => [schema.typeName, schema, fields] as const,
+    ),
+  )("%s has exactly the fields the conversion maps", (_name, schema, fields) => {
+    const actual = schema.fields.map((f) => f.localName).sort();
+    expect(
+      actual,
+      `${schema.typeName} changed shape. Map any new field in ` +
+        "mcpServerToInput (unmapped spec fields are ERASED on the next " +
+        "update), populate it in this file's fullyPopulatedServer fixture, " +
+        "then update EXPECTED_FIELD_INVENTORY.",
+    ).toEqual([...fields].sort());
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Layer 2 — round-trip proof
+// ---------------------------------------------------------------------------
+
+/**
+ * A server with EVERY spec field set to a non-default value, so any field
+ * the conversion drops shows up as a round-trip diff.
+ */
+function fullyPopulatedServer(transport: "stdio" | "http") {
+  const server = create(McpServerSchema, {
+    apiVersion: "agentic.stigmer.ai/v1",
+    kind: "McpServer",
+    metadata: create(ApiResourceMetadataSchema, {
+      name: "Monday",
+      org: "acme",
+      slug: "monday",
+      labels: { "stigmer.ai/category": "productivity" },
+    }),
+    spec: create(McpServerSpecSchema, {
+      description: "monday.com MCP server",
+      iconUrl: "https://example.com/monday.svg",
+      tags: ["monday", "project-management"],
+      defaultEnabledTools: ["boards_list", "items_create"],
+      env: {
+        MONDAY_ACCESS_TOKEN: create(EnvVarDeclarationSchema, {
+          isSecret: true,
+          description: "OAuth access token",
+          optional: true,
+        }),
+      },
+      pinnedToolApprovals: [
+        create(ToolApprovalPolicySchema, {
+          toolName: "items_delete",
+          message: "Deletes board items",
+          fromDestructiveHint: true,
+        }),
+      ],
+      repositoryUrl: "https://github.com/mondaycom/mcp",
+      githubStars: 387,
+      auth: create(McpServerAuthSchema, {
+        oauthAppRef: create(ApiResourceReferenceSchema, {
+          org: "stigmer",
+          slug: "monday-oauth",
+          kind: ApiResourceKind.oauth_app,
+        }),
+        targetEnvVar: "MONDAY_ACCESS_TOKEN",
+        tokenLifetimeHint: "1h",
+        scopeHints: ["boards:read", "boards:write"],
+        discoveryUrl: "https://auth.monday.com/.well-known/oauth",
+        oauthOnly: true,
+      }),
+    }),
+  });
+
+  if (transport === "stdio") {
+    server.spec!.serverType = {
+      case: "stdio",
+      value: create(StdioServerConfigSchema, {
+        command: "npx",
+        args: ["-y", "@mondaycom/mcp"],
+        workingDir: "/workspace",
+      }),
+    };
+  } else {
+    server.spec!.serverType = {
+      case: "http",
+      value: create(HttpServerConfigSchema, {
+        url: "https://mcp.monday.com/mcp",
+        headers: { Authorization: "Bearer ${MONDAY_ACCESS_TOKEN}" },
+        queryParams: { version: "2" },
+        timeoutSeconds: 45,
+      }),
+    };
+  }
+
+  return server;
+}
+
+describe("mcpServerToInput round-trip", () => {
+  it.each(["stdio", "http"] as const)(
+    "a fully-populated %s server survives toInput -> buildProto with spec intact",
+    (transport) => {
+      const original = fullyPopulatedServer(transport);
+      const rebuilt = buildMcpServerProto(mcpServerToInput(original));
+
+      expect(toJson(McpServerSpecSchema, rebuilt.spec!)).toEqual(
+        toJson(McpServerSpecSchema, original.spec!),
+      );
+
+      // Metadata identity fields the conversion is responsible for.
+      // (visibility is intentionally absent: the backend preserves it on
+      // update, and updateVisibility is its dedicated write path.)
+      expect(rebuilt.metadata?.name).toBe("Monday");
+      expect(rebuilt.metadata?.org).toBe("acme");
+      expect(rebuilt.metadata?.slug).toBe("monday");
+      expect(rebuilt.metadata?.labels).toEqual({
+        "stigmer.ai/category": "productivity",
+      });
+    },
+  );
+});

package/src/mcp-server/__tests__/useMcpServerDefinitionDrift.test.tsx

@@ -0,0 +1,173 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { renderHook, waitFor, cleanup } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { create } from "@bufbuild/protobuf";
+import { createRouterTransport, ConnectError, Code } from "@connectrpc/connect";
+import { Stigmer } from "@stigmer/sdk";
+import { McpServerQueryController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/query_pb";
+import { SearchService } from "@stigmer/protos/ai/stigmer/search/v1/query_pb";
+import {
+  SearchResponseSchema,
+  SearchResultSchema,
+} from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+import {
+  HttpServerConfigSchema,
+  McpServerSpecSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { samples } from "../../test/samples";
+import { StigmerContext } from "../../context";
+import { useMcpServerDefinitionDrift } from "../useMcpServerDefinitionDrift";
+
+/**
+ * Pins the template-resolution rules of the drift check
+ * (stigmer/stigmer#228): the marketplace counterpart is a cross-org
+ * PUBLIC row with the exact same slug — found through the search RPC's
+ * `crossOrgPublic` scope, the SDK's only client-side definition of
+ * "marketplace". Zero candidates, ambiguity, and transport failures all
+ * resolve to `null` (advisory affordance, never an error state).
+ */
+
+afterEach(cleanup);
+
+function serverWithHeaders(
+  org: string,
+  headers: Record<string, string>,
+): McpServer {
+  const server = samples.mcpServer({ name: "Monday", org, slug: "monday" });
+  server.spec = create(McpServerSpecSchema, {
+    serverType: {
+      case: "http",
+      value: create(HttpServerConfigSchema, {
+        url: "https://mcp.monday.com/mcp",
+        headers,
+      }),
+    },
+  });
+  return server;
+}
+
+function searchEntry(org: string) {
+  return create(SearchResultSchema, {
+    kind: ApiResourceKind.mcp_server,
+    id: `mcp-${org}`,
+    name: "Monday",
+    slug: "monday",
+    org,
+  });
+}
+
+function renderDrift(
+  server: McpServer | null,
+  register: Parameters<typeof createRouterTransport>[0],
+) {
+  const client = new Stigmer({
+    baseUrl: "/",
+    getAccessToken: () => "test-token",
+    customTransport: createRouterTransport(register),
+  });
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <StigmerContext.Provider value={client}>{children}</StigmerContext.Provider>
+  );
+  return renderHook(() => useMcpServerDefinitionDrift(server), { wrapper });
+}
+
+const STALE_HEADERS = { MONDAY_TOKEN: "${MONDAY_ACCESS_TOKEN}" };
+const FIXED_HEADERS = { Authorization: "Bearer ${MONDAY_ACCESS_TOKEN}" };
+
+describe("useMcpServerDefinitionDrift", () => {
+  it("reports drift against a single cross-org public row with the same slug", async () => {
+    const { result } = renderDrift(
+      serverWithHeaders("acme", STALE_HEADERS),
+      (router) => {
+        router.service(SearchService, {
+          search: () =>
+            create(SearchResponseSchema, {
+              entries: [searchEntry("acme"), searchEntry("stigmer")],
+            }),
+        });
+        router.service(McpServerQueryController, {
+          getByReference: () => serverWithHeaders("stigmer", FIXED_HEADERS),
+        });
+      },
+    );
+
+    await waitFor(() => expect(result.current.drift).not.toBeNull());
+    expect(result.current.drift?.changedFields).toEqual(["headers"]);
+    expect(result.current.drift?.template.metadata?.org).toBe("stigmer");
+  });
+
+  it("stays quiet when the configurations match", async () => {
+    const { result } = renderDrift(
+      serverWithHeaders("acme", FIXED_HEADERS),
+      (router) => {
+        router.service(SearchService, {
+          search: () =>
+            create(SearchResponseSchema, { entries: [searchEntry("stigmer")] }),
+        });
+        router.service(McpServerQueryController, {
+          getByReference: () => serverWithHeaders("stigmer", FIXED_HEADERS),
+        });
+      },
+    );
+
+    // Settle the async check, then confirm no drift was reported.
+    await new Promise((r) => setTimeout(r, 20));
+    await waitFor(() => expect(result.current.drift).toBeNull());
+  });
+
+  it("stays quiet when no foreign-org row shares the slug", async () => {
+    const { result } = renderDrift(
+      serverWithHeaders("acme", STALE_HEADERS),
+      (router) => {
+        router.service(SearchService, {
+          search: () =>
+            create(SearchResponseSchema, { entries: [searchEntry("acme")] }),
+        });
+      },
+    );
+
+    await new Promise((r) => setTimeout(r, 20));
+    expect(result.current.drift).toBeNull();
+  });
+
+  it("stays quiet when multiple foreign orgs share the slug (ambiguous template)", async () => {
+    const { result } = renderDrift(
+      serverWithHeaders("acme", STALE_HEADERS),
+      (router) => {
+        router.service(SearchService, {
+          search: () =>
+            create(SearchResponseSchema, {
+              entries: [searchEntry("stigmer"), searchEntry("other-org")],
+            }),
+        });
+      },
+    );
+
+    await new Promise((r) => setTimeout(r, 20));
+    expect(result.current.drift).toBeNull();
+  });
+
+  it("fails quiet when the search RPC errors", async () => {
+    const { result } = renderDrift(
+      serverWithHeaders("acme", STALE_HEADERS),
+      (router) => {
+        router.service(SearchService, {
+          search: () => {
+            throw new ConnectError("boom", Code.Unavailable);
+          },
+        });
+      },
+    );
+
+    await new Promise((r) => setTimeout(r, 20));
+    expect(result.current.drift).toBeNull();
+  });
+
+  it("skips entirely when passed null", async () => {
+    const { result } = renderDrift(null, () => {});
+    await new Promise((r) => setTimeout(r, 20));
+    expect(result.current.drift).toBeNull();
+  });
+});