feat: add backward compat normalization in registerAppTool

- If _meta.ui.resourceUri is set, also set legacy flat key
- If legacy flat key is set, also set _meta.ui.resourceUri
- Preserves existing visibility when merging
- Does not overwrite if both formats already set

Author: ochafik

src/server/index.test.ts

@@ -52,6 +52,131 @@ describe("registerAppTool", () => {
     ).toBe("ui://test/widget.html");
     expect(capturedHandler).toBe(handler);
   });
+
+  describe("backward compatibility", () => {
+    it("should set legacy key when _meta.ui.resourceUri is provided", () => {
+      let capturedConfig: Record<string, unknown> | undefined;
+
+      const mockServer = {
+        registerTool: mock(
+          (_name: string, config: Record<string, unknown>, _handler: unknown) => {
+            capturedConfig = config;
+          },
+        ),
+      };
+
+      registerAppTool(
+        mockServer as unknown as Pick<McpServer, "registerTool">,
+        "my-tool",
+        {
+          _meta: {
+            ui: { resourceUri: "ui://test/widget.html" },
+          },
+        },
+        async () => ({ content: [{ type: "text" as const, text: "ok" }] }),
+      );
+
+      const meta = capturedConfig?._meta as Record<string, unknown>;
+      // New format should be preserved
+      expect((meta.ui as { resourceUri: string }).resourceUri).toBe(
+        "ui://test/widget.html",
+      );
+      // Legacy key should also be set
+      expect(meta[RESOURCE_URI_META_KEY]).toBe("ui://test/widget.html");
+    });
+
+    it("should set _meta.ui.resourceUri when legacy key is provided", () => {
+      let capturedConfig: Record<string, unknown> | undefined;
+
+      const mockServer = {
+        registerTool: mock(
+          (_name: string, config: Record<string, unknown>, _handler: unknown) => {
+            capturedConfig = config;
+          },
+        ),
+      };
+
+      registerAppTool(
+        mockServer as unknown as Pick<McpServer, "registerTool">,
+        "my-tool",
+        {
+          _meta: {
+            [RESOURCE_URI_META_KEY]: "ui://test/widget.html",
+          },
+        },
+        async () => ({ content: [{ type: "text" as const, text: "ok" }] }),
+      );
+
+      const meta = capturedConfig?._meta as Record<string, unknown>;
+      // Legacy key should be preserved
+      expect(meta[RESOURCE_URI_META_KEY]).toBe("ui://test/widget.html");
+      // New format should also be set
+      expect((meta.ui as { resourceUri: string }).resourceUri).toBe(
+        "ui://test/widget.html",
+      );
+    });
+
+    it("should preserve visibility when converting from legacy format", () => {
+      let capturedConfig: Record<string, unknown> | undefined;
+
+      const mockServer = {
+        registerTool: mock(
+          (_name: string, config: Record<string, unknown>, _handler: unknown) => {
+            capturedConfig = config;
+          },
+        ),
+      };
+
+      registerAppTool(
+        mockServer as unknown as Pick<McpServer, "registerTool">,
+        "my-tool",
+        {
+          _meta: {
+            ui: { visibility: ["app"] },
+            [RESOURCE_URI_META_KEY]: "ui://test/widget.html",
+          },
+        } as any,
+        async () => ({ content: [{ type: "text" as const, text: "ok" }] }),
+      );
+
+      const meta = capturedConfig?._meta as Record<string, unknown>;
+      const ui = meta.ui as { resourceUri: string; visibility: string[] };
+      // Should have merged resourceUri into existing ui object
+      expect(ui.resourceUri).toBe("ui://test/widget.html");
+      expect(ui.visibility).toEqual(["app"]);
+    });
+
+    it("should not overwrite if both formats are already set", () => {
+      let capturedConfig: Record<string, unknown> | undefined;
+
+      const mockServer = {
+        registerTool: mock(
+          (_name: string, config: Record<string, unknown>, _handler: unknown) => {
+            capturedConfig = config;
+          },
+        ),
+      };
+
+      registerAppTool(
+        mockServer as unknown as Pick<McpServer, "registerTool">,
+        "my-tool",
+        {
+          _meta: {
+            ui: { resourceUri: "ui://new/widget.html" },
+            [RESOURCE_URI_META_KEY]: "ui://old/widget.html",
+          },
+        } as any,
+        async () => ({ content: [{ type: "text" as const, text: "ok" }] }),
+      );
+
+      const meta = capturedConfig?._meta as Record<string, unknown>;
+      // Both should remain unchanged
+      expect((meta.ui as { resourceUri: string }).resourceUri).toBe(
+        "ui://new/widget.html",
+      );
+      expect(meta[RESOURCE_URI_META_KEY]).toBe("ui://old/widget.html");
+    });
+  });
 });
 
 describe("registerAppResource", () => {

src/server/index.ts

@@ -102,6 +102,21 @@ export function registerAppTool(
   config: McpUiAppToolConfig,
   handler: ToolCallback<ZodRawShape>,
 ): void {
+  // Normalize metadata for backward compatibility:
+  // - If _meta.ui.resourceUri is set, also set the legacy flat key
+  // - If the legacy flat key is set, also set _meta.ui.resourceUri
+  const meta = config._meta;
+  const uiMeta = meta.ui as McpUiToolMeta | undefined;
+  const legacyUri = meta[RESOURCE_URI_META_KEY] as string | undefined;
+
+  if (uiMeta?.resourceUri && !legacyUri) {
+    // New format -> also set legacy key
+    meta[RESOURCE_URI_META_KEY] = uiMeta.resourceUri;
+  } else if (legacyUri && !uiMeta?.resourceUri) {
+    // Legacy format -> also set new format
+    meta.ui = { ...uiMeta, resourceUri: legacyUri };
+  }
+
   server.registerTool(name, config, handler);
 }