fix(board): disable displaced item movement animations

fix(board): retain swap previews until layout commit renders
fix(board): make container editor centering order independent
2026-09-09 14:37:33 +02:00 · 2026-09-09 11:59:10 +02:00 · 2026-09-09 10:38:26 +02:00 · 2026-09-09 09:21:13 +02:00
19 changed files with 160 additions and 569 deletions
@@ -23,7 +23,7 @@ Homarr 2.0 is an upgrade, not a brand-new app wearing the same logo. Here is wha

 :::warning Back up before upgrading

-Database migrations run automatically when Homarr starts. Create a
+Follow the [v1 to v2 upgrade guide](/docs/getting-started/upgrade-v2) and create a
 [Homarr backup](/docs/management/backup) first. Do not test a prerelease image on your only production volume.
 Backups are boring. Restores are worse.

@@ -161,7 +161,7 @@ Board startup work runs in parallel, heavy screens load when opened, and identic
 ## Links

 - Try the [Homarr 2.0 preview](https://app-v2.preview.homarr.dev).
- Follow the [v2 beta setup guide](/docs/getting-started/upgrade-v2).
+- Follow the [v1 to v2 upgrade guide](/docs/getting-started/upgrade-v2).
 - Follow the [v2 release pull request](https://github.com/homarr-labs/homarr/pull/6545) and [public beta thread](https://github.com/homarr-labs/homarr/issues/6600).
 - Compare [v1.76.2 with the release/v2 branch](https://github.com/homarr-labs/homarr/compare/v1.76.2...release/v2).
 - Read the guides for [Boards](/docs/management/boards), [Custom Widgets](/docs/management/custom-widgets), [Assistant](/docs/management/assistant), [MCP](/docs/management/mcp) and [Docker labels](/docs/integrations/docker-labels).
@@ -1,5 +1,5 @@
 ---
-title: Try the v2 beta
+title: Upgrade from v1 to v2
 sidebar_position: 2
 tags:
  - Getting started
@@ -8,20 +8,8 @@ tags:
  - Backup
 ---

-This page covers the temporary Homarr v2 public beta. Try the [live demo](https://app-v2.preview.homarr.dev/)
-without installing anything, or run the beta image published in the
-[public beta announcement](https://github.com/homarr-labs/homarr/issues/6600):
-
-```sh
-docker pull ghcr.io/homarr-labs/homarr-test:v2
-```
-
-For a fresh beta installation, follow the [Docker installation guide](/docs/getting-started/installation/docker),
-use `ghcr.io/homarr-labs/homarr-test:v2` as the image, and use a separate `/appdata` volume.
-Set `WORKSHOP_API_URL=https://v2.preview.homarr.dev` to use the preview Workshop.
-
-Homarr runs database migrations automatically at startup; no manual database migration command is needed.
-Once v2 is released, existing installations can use their normal update process. The beta image below is temporary.
+Homarr v2 upgrades the existing v1 database in place. Keep the same data storage, database configuration, and
+`SECRET_ENCRYPTION_KEY`; only change the Homarr image or package version for the first start.

 :::danger Back up before starting v2

@@ -30,23 +18,21 @@ before starting v2. See [Backup and restore](/docs/management/backup) for detail

 :::

-## Try the beta with existing v1 data
+## Upgrade

-1. Change the Homarr image to `ghcr.io/homarr-labs/homarr-test:v2`.
+1. Pin the Homarr image to `ghcr.io/homarr-labs/homarr:v2.0.0` for the first v2 start.
 2. Keep the existing `/appdata` mount, database variables, Redis configuration, and `SECRET_ENCRYPTION_KEY` unchanged.
 3. Start one Homarr replica and follow its logs. Startup must reach `Migration complete`; Homarr aborts startup when a
   database migration fails.
 4. Open Homarr and sign in. Confirm **Management → About** reports v2 before starting additional replicas.
-5. Keep using the beta image for beta updates. To return to v1, restore the pre-beta backup as described below.
+5. After validation, keep the version pinned or return to your normal stable release policy.

-Keep your other existing Compose settings, including environment variables. For Docker Compose, update the image and preview Workshop URL before the usual update:
+For Docker Compose, the change is limited to the image tag before the usual update:

 ```yaml
 services:
  homarr:
-    image: ghcr.io/homarr-labs/homarr-test:v2
-    environment:
-      WORKSHOP_API_URL: https://v2.preview.homarr.dev
+    image: ghcr.io/homarr-labs/homarr:v2.0.0
 ```

 ```sh
@@ -27,12 +27,6 @@ session cookie.
 API keys do not expire automatically and act as the user that created them. Every request uses that user's group and
 resource permissions.

-## Invitation dates
-
-`POST /api/invites` and the tRPC `invite.createInvite` procedure accept `expirationDate` as an ISO 8601 timestamp with a
-timezone, for example `2026-12-01T18:00:00Z`. Homarr validates the timestamp and stores it as a date. tRPC callers should
-send the ISO string rather than a JavaScript `Date` object.
-
 ## Health probes

 The liveness endpoint does not require authentication:
@@ -8,17 +8,18 @@ tags:

 # Model Context Protocol (MCP)

-Connect an AI client to Homarr to manage boards, apps, integrations, and other services through MCP tools.
-
-Homarr uses MCP v2 (protocol `2026-07-28`) at `/api/mcp`, with compatibility for 2025 Streamable HTTP clients.
-Requests are stateless: each request authenticates independently, without an MCP session ID.
+Homarr exposes a stateless [Model Context Protocol](https://modelcontextprotocol.io) server at `/api/mcp`. It maps the
+current Homarr API to tools for compatible AI clients.

 ![The AI / MCP management tab](./img/mcp.png)

-## Connect a client
+The endpoint implements MCP `2026-07-28` and accepts 2025 Streamable HTTP clients through a compatibility path. The old
+`/api/mcp/mcp` route remains as an alias; use `/api/mcp` for new clients.

-Create an API key under **Management → Tools → API → Authentication**. Add this configuration to your client,
-replacing the URL and API key:
+## Configure a client
+
+Create an API key under **Management → Tools → API → Authentication**, then add the endpoint and header to the client's
+MCP configuration:

 ```json
 {
@@ -33,10 +34,7 @@ replacing the URL and API key:
 }
 ```

-Use the complete key, including the ID, dot, and token. Keep it private and use HTTPS for remote connections.
-The **AI / MCP** tab on Homarr's API page provides your endpoint, configuration, and available tools.
-
-For clients that only support STDIO, use `mcp-remote`:
+Clients without Streamable HTTP support can use `mcp-remote` over STDIO:

 ```json
 {
@@ -49,30 +47,26 @@ For clients that only support STDIO, use `mcp-remote`:
 }
 ```

-### OAuth
+The **AI / MCP** tab on Homarr's API page shows the current endpoint, configuration, and generated tool catalog. Filter
+the catalog by namespace, tool name, or description; matching categories expand automatically.

-Clients with OAuth support can authorize through OAuth 2.1 with PKCE instead of an API key.
-Homarr publishes discovery metadata under `/.well-known/`.
+## Authentication and permissions

-If your reverse proxy does not preserve the public host and protocol, set `BASE_URL` to your public origin,
-such as `https://homarr.example.com`, without a path.
+MCP supports API keys and OAuth 2.1 with PKCE. API keys are simpler for direct client configuration; OAuth is available
+for clients that support dynamic authorization.

-## Permissions and tools
+When Homarr is behind a reverse proxy that does not preserve the public host and protocol, set `BASE_URL` to the exact
+public origin, for example `https://homarr.example.com`. Do not include a path. OAuth clients discover the authorization
+server and protected resource through Homarr's `/.well-known/` routes.

-Tools use the permissions of the API key owner or OAuth user. Queries read data; mutations change it.
-Inspect the **AI / MCP** tab or your client's tool list for available actions.
+Tools use the permissions of the API key owner or authorized user. Creating a key does not grant additional access.
+Custom Widget and Workshop authoring tools, prompts, and resources are visible only to administrators.

-Custom Widget and Workshop authoring tools, prompts, and resources require administrator access.
-For Custom Widgets, install the official skill and follow the preview-and-evidence workflow described in
-[Connect an agent](./custom-widgets/agent-authoring). Secret values are configured in Homarr and are never returned
-through MCP.
+Use HTTPS when the endpoint crosses an untrusted network.

-The built-in [Assistant](./assistant) uses the same tool catalog with the current Homarr session and asks for approval
-before mutations by default.
+## Verify the endpoint

-## Verify the connection
-
-This request lists tools through the older-client compatibility path. It checks authentication and tool discovery:
+The 2025 compatibility path accepts a compact `tools/list` request:

 ```sh
 curl -X POST \
@@ -83,14 +77,17 @@ curl -X POST \
  https://homarr.example.com/api/mcp
 ```

-A successful discovery or initialization response alone does not verify that tools can be listed.
+The removed HTTP+SSE `/sse` and `/message` transports return `410 Gone`.

-## Troubleshooting
+## Tools and resources

- **`invalid_token`**: copy the complete API key in `<id>.<token>` format.
- **Missing tools**: check the user's permissions. Invalid tool schemas and duplicate names are omitted; check server
-  logs for `MCP tool omitted from catalog` and report the diagnostic with your Homarr version. Exclude API keys.
- **`Date cannot be represented in JSON Schema`**: update Homarr. Older versions could fail to list all tools because
-  of an unsupported date schema.
- **`410 Gone` on `/sse` or `/message`**: use `/api/mcp` with a Streamable HTTP client. The old `/api/mcp/mcp` URL remains
-  an alias.
+The generated catalog includes available board, app, integration, Docker, Kubernetes, media, DNS, download, and other
+Homarr procedures. Queries are read-only; mutations change state. The exact catalog depends on the release and current
+user permissions, so inspect `tools/list` or the table in Homarr instead of relying on a static list.
+
+For Custom Widgets, install the official skill and follow the preview-and-evidence workflow described in
+[Connect an agent](./custom-widgets/agent-authoring). Secret values are configured in Homarr and are never returned
+through MCP.
+
+The built-in [Assistant](./assistant) uses the same tool catalog with the current Homarr session and asks for approval
+before mutations by default.
@@ -2572,9 +2572,7 @@
                "type": "object",
                "properties": {
                  "expirationDate": {
-                    "type": "string",
-                    "format": "date-time",
-                    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
+                    "type": "string"
                  }
                },
                "required": [
@@ -45,7 +45,7 @@ export const InviteCreateForm = ({ onClose }: InviteCreateFormProps) => {
      onSubmit={form.onSubmit((values) => {
        mutate(
          {
-            expirationDate: new Date(values.expirationDate).toISOString(),
+            expirationDate: new Date(values.expirationDate),
          },
          {
            onSuccess: (result) => {
@@ -7,7 +7,7 @@ import { createUIMessageStream, createUIMessageStreamResponse, jsonSchema, stepC
 import { cookies } from "next/headers";
 import { z } from "zod/v4";

-import { callMcpTool, createTRPCContext, mcpRouter } from "@homarr/api/mcp";
+import { createTRPCContext, mcpRouter } from "@homarr/api/mcp";
 import {
  createAssistantGenerationAccessToken,
  getAssistantRequestContextEntitiesAsync,
@@ -547,7 +547,19 @@ export async function POST(request: Request) {
            }
            if (contextRequestKey !== null) loadedCustomWidgetContextRequests.add(contextRequestKey);
            try {
-              const result = await callMcpTool(caller, mcpTool, executionInput);
+              const procedure = mcpTool.pathInRouter.reduce<unknown>(
+                (current, segment) =>
+                  (typeof current === "object" || typeof current === "function") && current !== null
+                    ? (current as Record<string, unknown>)[segment]
+                    : undefined,
+                caller,
+              );
+              if (typeof procedure !== "function") {
+                throw new Error("Procedure not callable");
+              }
+              const result = await (procedure as (value: unknown) => Promise<unknown>)(
+                executionInput && Object.keys(executionInput as object).length > 0 ? executionInput : undefined,
+              );
              customWidgetDiscoveryPhase.observe(mcpTool.name, result);
              return toAssistantToolOutput(result, {
                maxCharacters: getAssistantToolOutputMaxCharacters(mcpTool.name),
@@ -2,11 +2,8 @@

 import { beforeEach, describe, expect, test, vi } from "vitest";

-import type * as CatalogModule from "../_extract-tools";
-
 const mocks = vi.hoisted(() => ({
  authenticate: vi.fn(),
-  extractCatalog: vi.fn(),
  ipAddress: vi.fn(() => "127.0.0.1"),
  toolProcedure: vi.fn(),
  loggerWarn: vi.fn(),
@@ -17,9 +14,7 @@ const mocks = vi.hoisted(() => ({
 }));

 vi.mock("next/server", () => ({ userAgent: () => ({ ua: "MCP route test" }) }));
-vi.mock("@homarr/api/mcp", async () => ({
-  callMcpTool: (await import("../../../../../../../packages/api/src/mcp-tools")).callMcpTool,
-  extractMcpToolsFromProcedures: mocks.extractCatalog,
+vi.mock("@homarr/api/mcp", () => ({
  createTRPCContext: vi.fn(() => ({})),
  mcpRouter: { createCaller: vi.fn(() => ({ board: { getAllBoards: mocks.toolProcedure } })) },
 }));
@@ -59,7 +54,6 @@ vi.mock("../_extract-tools", () => ({
      description: "List boards",
      type: "query",
      pathInRouter: ["board", "getAllBoards"],
-      inputMode: "none",
      inputSchema: { type: "object", properties: {} },
    },
    {
@@ -67,7 +61,6 @@ vi.mock("../_extract-tools", () => ({
      description: "List Custom Widgets",
      type: "query",
      pathInRouter: ["customWidget", "list"],
-      inputMode: "none",
      inputSchema: { type: "object", properties: {} },
    },
    {
@@ -75,7 +68,6 @@ vi.mock("../_extract-tools", () => ({
      description: "Search Workshop",
      type: "query",
      pathInRouter: ["customWidget", "workshopSearch"],
-      inputMode: "none",
      inputSchema: { type: "object", properties: {} },
    },
  ],
@@ -313,21 +305,3 @@ describe("MCP protocol errors", () => {
    expect(metadata).not.toHaveProperty("message");
  });
 });
-
-test("logs catalog omissions only when the shared catalog is first built", async () => {
-  const diagnostic = { name: "broken", path: "broken", reason: "invalid_schema" };
-  const tools = [{ name: "valid" }];
-  mocks.extractCatalog.mockReturnValue({ tools, diagnostics: [diagnostic] });
-  const { extractMcpTools } = await vi.importActual<typeof CatalogModule>("../_extract-tools");
-  expect(extractMcpTools()).toBe(tools);
-  expect(extractMcpTools()).toBe(tools);
-  expect(mocks.extractCatalog).toHaveBeenCalledTimes(1);
-  expect(mocks.loggerWarn).toHaveBeenCalledExactlyOnceWith("MCP tool omitted from catalog", diagnostic);
-});
-
-test("rejects unauthenticated tool calls before execution", async () => {
-  mocks.authenticate.mockResolvedValue(null);
-  const { response } = await callMcp("tools/call", { name: "board_getAllBoards", arguments: {} });
-  expect(response.status).toBe(401);
-  expect(mocks.toolProcedure).not.toHaveBeenCalled();
-});
@@ -1,12 +1,11 @@
 import { extractMcpToolsFromProcedures, mcpRouter } from "@homarr/api/mcp";
-import { createLogger } from "@homarr/core/infrastructure/logs";

-const logger = createLogger({ module: "mcp-catalog" });
 let cache: ReturnType<typeof extractMcpToolsFromProcedures> | null = null;

 export function extractMcpTools() {
-  if (cache) return cache.tools;
+  if (cache) return cache;
+
  cache = extractMcpToolsFromProcedures(mcpRouter);
-  for (const diagnostic of cache.diagnostics) logger.warn("MCP tool omitted from catalog", diagnostic);
-  return cache.tools;
+
+  return cache;
 }
@@ -1,18 +1,12 @@
 // @vitest-environment node

-import { initTRPC, TRPCError } from "@trpc/server";
 import { describe, expect, test, vi } from "vitest";
 import { z } from "zod/v4";

 import type { McpTool } from "@homarr/api/mcp";
-import { appManageSchema } from "@homarr/validation/app";
-import { extractMcpToolsFromProcedures } from "@homarr/api/mcp";
-import type { McpMeta } from "../../../../../../packages/api/src/mcp-tools";

 import { createMcpProtocolHandler } from "./_protocol";

-vi.mock("@homarr/api/mcp", async () => import("../../../../../../packages/api/src/mcp-tools"));
-
 const modernMetadata = {
  "io.modelcontextprotocol/protocolVersion": "2026-07-28",
  "io.modelcontextprotocol/clientInfo": { name: "homarr-test", version: "1.0.0" },
@@ -58,7 +52,7 @@ const echoTool: McpTool = {
  description: "Echo a message",
  type: "query",
  pathInRouter: ["echo"],
-  inputMode: "object",
+  inputValidator: echoValidator,
  inputSchema: z.toJSONSchema(echoValidator),
 };

@@ -169,197 +163,3 @@ describe("MCP v2 protocol", () => {
    expect((await parseResponse(listResponse)).result.tools).toEqual([expect.objectContaining({ name: "echo" })]);
  });
 });
-
-describe.each([false, true])("MCP argument dispatch (modern=%s)", (modern) => {
-  const trpc = initTRPC.context<{ user: string }>().meta<McpMeta>().create();
-  const exposed = trpc.procedure.meta({ mcp: { enabled: true } });
-
-  const call = async (
-    handler: ReturnType<typeof createMcpProtocolHandler>,
-    name: string,
-    argumentsValue: Record<string, unknown>,
-  ) => {
-    let request = createRequest("tools/call", { name, arguments: argumentsValue }, name);
-    if (!modern) {
-      request = new Request("http://homarr.test/api/mcp", {
-        method: "POST",
-        headers: { "Content-Type": "application/json", Accept: "application/json, text/event-stream" },
-        body: JSON.stringify({
-          jsonrpc: "2.0",
-          id: 1,
-          method: "tools/call",
-          params: { name, arguments: argumentsValue },
-        }),
-      });
-    }
-    const response = await handler.fetch(request);
-    expect(response.headers.has("Mcp-Session-Id")).toBe(false);
-    return (await parseResponse(response)).result;
-  };
-
-  test("transforms once and does not coerce, insert defaults, or remove properties before tRPC", async () => {
-    const transform = vi.fn((value: string) => `${value}!`);
-    const execution = vi.fn((input: unknown) => input);
-    const router = trpc.router({
-      update: exposed
-        .input(
-          z.looseObject({
-            name: z.string().transform(transform),
-            limit: z.number().default(7),
-          }),
-        )
-        .mutation(({ input }) => execution(input)),
-    });
-    const catalog = extractMcpToolsFromProcedures(router);
-    expect(catalog.diagnostics).toEqual([]);
-    const realCaller = router.createCaller({ user: "one" });
-    const dispatch = vi.fn(realCaller.update);
-    const handler = createMcpProtocolHandler({
-      caller: { update: dispatch },
-      tools: catalog.tools,
-      version: "test",
-      instructions: "test",
-      formatToolError: () => "Invalid input",
-    });
-    const argumentsValue = { name: "hello", extra: "preserved" };
-    const result = await call(handler, "update", argumentsValue);
-    expect(result.isError).not.toBe(true);
-    expect(dispatch).toHaveBeenCalledWith(argumentsValue);
-    expect(transform).toHaveBeenCalledTimes(1);
-    expect(execution).toHaveBeenCalledWith({ name: "hello!", limit: 7, extra: "preserved" });
-    await call(handler, "update", { name: "hello", limit: "7" });
-    expect(dispatch).toHaveBeenCalledTimes(1);
-    expect(execution).toHaveBeenCalledTimes(1);
-  });
-
-  test("retains overlapping chained constraints, refinements, and empty object defaults", async () => {
-    const execution = vi.fn((input: unknown) => input);
-    const router = trpc.router({
-      bounded: exposed
-        .input(z.object({ count: z.number().min(2) }))
-        .input(z.object({ count: z.number().max(5) }))
-        .mutation(({ input }) => execution(input)),
-      refined: exposed
-        .input(z.object({ value: z.string().refine((value) => value !== "blocked") }))
-        .mutation(({ input }) => execution(input)),
-      defaults: exposed.input(z.object({ count: z.number().default(3) })).query(({ input }) => input),
-      none: exposed.query(({ input }) => ({ absent: input === undefined })),
-    });
-    const catalog = extractMcpToolsFromProcedures(router);
-    expect(catalog.diagnostics).toEqual([]);
-    const handler = createMcpProtocolHandler({
-      caller: router.createCaller({ user: "one" }),
-      tools: catalog.tools,
-      version: "test",
-      instructions: "test",
-      formatToolError: () => "Invalid input",
-    });
-    for (const count of [1, 6]) expect((await call(handler, "bounded", { count })).isError).toBe(true);
-    expect((await call(handler, "refined", { value: "blocked" })).isError).toBe(true);
-    expect(execution).not.toHaveBeenCalled();
-    expect((await call(handler, "bounded", { count: 3 })).isError).not.toBe(true);
-    expect(execution).toHaveBeenCalledWith({ count: 3 });
-    expect((await call(handler, "defaults", {})).content).toEqual([{ type: "text", text: '{"count":3}' }]);
-    expect((await call(handler, "none", {})).content).toEqual([{ type: "text", text: '{"absent":true}' }]);
-  });
-
-  test("accepts app inputs that tRPC normalizes before checking constraints", async () => {
-    const mutation = vi.fn((input: unknown) => input);
-    const router = trpc.router({ create: exposed.input(appManageSchema).mutation(({ input }) => mutation(input)) });
-    const { tools, diagnostics } = extractMcpToolsFromProcedures(router);
-    expect(diagnostics).toEqual([]);
-    const handler = createMcpProtocolHandler({
-      caller: router.createCaller({ user: "admin" }),
-      tools,
-      version: "test",
-      instructions: "test",
-      formatToolError: () => "Invalid input",
-    });
-    const argumentsValue = {
-      name: `${" ".repeat(64)}App `,
-      description: " description ",
-      iconUrl: " icon ",
-      href: null,
-      pingUrl: " https://example.com ",
-    };
-    expect((await call(handler, "create", argumentsValue)).isError).not.toBe(true);
-    expect(mutation).toHaveBeenCalledExactlyOnceWith({
-      name: "App",
-      description: "description",
-      iconUrl: "icon",
-      href: null,
-      pingUrl: "https://example.com",
-    });
-    expect((await call(handler, "create", { ...argumentsValue, pingUrl: " javascript:alert(1) " })).isError).toBe(true);
-    expect(mutation).toHaveBeenCalledTimes(1);
-  });
-
-  test("accepts Zod ISO timestamps without seconds while rejecting invalid dates", async () => {
-    const mutation = vi.fn((input: unknown) => input);
-    const router = trpc.router({
-      invite: exposed
-        .input(z.object({ expirationDate: z.iso.datetime({ offset: true }) }))
-        .mutation(({ input }) => mutation(input)),
-    });
-    const { tools, diagnostics } = extractMcpToolsFromProcedures(router);
-    expect(diagnostics).toEqual([]);
-    const handler = createMcpProtocolHandler({
-      caller: router.createCaller({ user: "admin" }),
-      tools,
-      version: "test",
-      instructions: "test",
-      formatToolError: () => "Invalid input",
-    });
-    for (const expirationDate of ["2026-12-01T18:00Z", "2026-12-01T19:00+01:00"]) {
-      expect((await call(handler, "invite", { expirationDate })).isError).not.toBe(true);
-      expect(mutation).toHaveBeenLastCalledWith({ expirationDate });
-    }
-    for (const expirationDate of ["2026-02-30T18:00Z", "not-a-date"]) {
-      expect((await call(handler, "invite", { expirationDate })).isError).toBe(true);
-    }
-    expect(mutation).toHaveBeenCalledTimes(2);
-  });
-
-  test("enforces tRPC permissions before executing mutations", async () => {
-    const mutation = vi.fn(() => "changed");
-    const router = trpc.router({
-      restricted: exposed
-        .use(({ ctx, next }) => {
-          if (ctx.user !== "admin") throw new TRPCError({ code: "FORBIDDEN" });
-          return next();
-        })
-        .input(z.object({}))
-        .mutation(mutation),
-    });
-    const { tools, diagnostics } = extractMcpToolsFromProcedures(router);
-    expect(diagnostics).toEqual([]);
-    const handler = createMcpProtocolHandler({
-      caller: router.createCaller({ user: "guest" }),
-      tools,
-      version: "test",
-      instructions: "test",
-      formatToolError: () => "Forbidden",
-    });
-    expect((await call(handler, "restricted", {})).isError).toBe(true);
-    expect(mutation).not.toHaveBeenCalled();
-  });
-
-  test("isolates authenticated callers when reusing catalog schemas", async () => {
-    const router = trpc.router({ who: exposed.query(({ ctx }) => ctx.user) });
-    const { tools } = extractMcpToolsFromProcedures(router);
-    const handlers = ["alice", "bob"].map((user) =>
-      createMcpProtocolHandler({
-        caller: router.createCaller({ user }),
-        tools,
-        version: "test",
-        instructions: "test",
-        formatToolError: () => "Failed",
-      }),
-    );
-    const results = await Promise.all(handlers.map((handler) => call(handler, "who", {})));
-    expect(results.map((result) => result.content)).toEqual([
-      [{ type: "text", text: '"alice"' }],
-      [{ type: "text", text: '"bob"' }],
-    ]);
-  });
-});
@@ -1,6 +1,5 @@
-import { createMcpHandler, fromJsonSchema, McpServer } from "@modelcontextprotocol/server";
+import { createMcpHandler, McpServer } from "@modelcontextprotocol/server";

-import { callMcpTool } from "@homarr/api/mcp";
 import type { McpTool } from "@homarr/api/mcp";

 import { toAssistantToolOutput } from "../assistant/chat/assistant-tool-output";
@@ -16,6 +15,15 @@ interface CreateMcpProtocolHandlerOptions {
  onProtocolError?: (error: Error) => void;
 }

+const resolveProcedure = (caller: unknown, path: string[]) =>
+  path.reduce<unknown>(
+    (current, segment) =>
+      (typeof current === "object" || typeof current === "function") && current !== null
+        ? (current as Record<string, unknown>)[segment]
+        : undefined,
+    caller,
+  );
+
 export const createMcpProtocolHandler = ({
  caller,
  tools,
@@ -44,11 +52,20 @@ export const createMcpProtocolHandler = ({
          tool.name,
          {
            description: tool.description,
-            inputSchema: fromJsonSchema(tool.inputSchema as Parameters<typeof fromJsonSchema>[0]),
+            inputSchema: tool.inputValidator,
          },
          async (args) => {
            try {
-              const result = await callMcpTool(caller, tool, args);
+              const procedure = resolveProcedure(caller, tool.pathInRouter);
+              if (typeof procedure !== "function") {
+                return {
+                  content: [{ type: "text" as const, text: `Tool "${tool.name}" is not callable` }],
+                  isError: true,
+                };
+              }
+
+              const input = Object.keys(args).length > 0 ? args : undefined;
+              const result = await (procedure as (value: unknown) => Promise<unknown>)(input);
              return {
                content: [
                  {
@@ -51,13 +51,11 @@
    "@homarr/validation": "workspace:^0.1.0",
    "@homarr/workshop": "workspace:^0.1.0",
    "@kubernetes/client-node": "catalog:",
-    "@modelcontextprotocol/server": "catalog:",
    "@tanstack/react-query": "catalog:",
    "@trpc/client": "catalog:",
    "@trpc/react-query": "catalog:",
    "@trpc/server": "catalog:",
    "@trpc/tanstack-react-query": "catalog:",
-    "ajv": "catalog:",
    "lodash.clonedeep": "catalog:",
    "next": "catalog:",
    "react": "catalog:",
@@ -1,5 +1,3 @@
-import { Ajv2020 } from "ajv/dist/2020.js";
-import { addFormats, AjvJsonSchemaValidator } from "@modelcontextprotocol/server/validators/ajv";
 import type { AnyProcedure, AnyRootTypes, Router, RouterRecord } from "@trpc/server/unstable-core-do-not-import";
 import { z } from "zod/v4";

@@ -17,35 +15,23 @@ export interface McpTool {
  type: "query" | "mutation";
  pathInRouter: string[];
  inputSchema: z.core.JSONSchema.JSONSchema;
-  inputMode: "none" | "object";
+  inputValidator: z.ZodObject;
 }

-export interface McpToolDiagnostic {
-  name: string;
-  path: string;
-  reason: "unsupported_input" | "invalid_schema" | "duplicate_name" | "invalid_name";
-}
+const emptyInput = z.object({});

-export interface McpToolCatalog {
-  tools: McpTool[];
-  diagnostics: McpToolDiagnostic[];
-}
-
-const emptyInput = z.strictObject({});
-const schemaEngine = new Ajv2020({
-  strict: false,
-  validateSchema: true,
-  coerceTypes: false,
-  useDefaults: false,
-  removeAdditional: false,
-});
-addFormats(schemaEngine);
-const schemaValidator = new AjvJsonSchemaValidator(schemaEngine);
 const isProcedure = (value: AnyProcedure | RouterRecord): value is AnyProcedure => typeof value === "function";

-const getObjectInput = (input: unknown): z.ZodObject | null => {
+const mergeInputs = (inputs: z.ZodObject[]) => inputs.reduce((merged, input) => merged.extend(input.shape), emptyInput);
+
+const getObjectInput = (input: z.ZodType) => {
  if (input instanceof z.ZodObject) return input;
-  if (input instanceof z.ZodOptional) return getObjectInput(input.unwrap());
+
+  if (input instanceof z.ZodOptional) {
+    const unwrappedInput = input.unwrap();
+    if (unwrappedInput instanceof z.ZodObject) return unwrappedInput;
+  }
+
  return null;
 };

@@ -64,110 +50,70 @@ const getMcpMetadata = (meta: unknown): McpMeta["mcp"] => {
  return result;
 };

+const getProcedureInput = (inputs: z.ZodType[]) => {
+  if (inputs.length === 0) return emptyInput;
+  if (inputs.length === 1) {
+    const input = inputs[0] ?? emptyInput;
+    return getObjectInput(input) ?? input;
+  }
+
+  const objectInputs = inputs.map(getObjectInput);
+  if (objectInputs.every((input): input is z.ZodObject => input !== null)) return mergeInputs(objectInputs);
+  return null;
+};
+
+const normalizeJsonSchema = (schema: z.core.JSONSchema.JSONSchema): z.core.JSONSchema.JSONSchema => {
+  const properties = schema.properties ?? {};
+  const required = (schema.required ?? []).filter((key) => {
+    const property = properties[key];
+    return !property || typeof property !== "object" || !("default" in property);
+  });
+
+  return {
+    ...schema,
+    type: "object",
+    properties,
+    required,
+  };
+};
+
 export function extractMcpToolsFromProcedures<TRoot extends AnyRootTypes, TRecord extends RouterRecord>(
  router: Router<TRoot, TRecord>,
-): McpToolCatalog {
+): McpTool[] {
  const tools: McpTool[] = [];
-  const diagnostics: McpToolDiagnostic[] = [];
-  const names = new Map<string, string[]>();

  for (const [path, procedure] of Object.entries(router["_def"].procedures)) {
    if (!isProcedure(procedure)) continue;
    const definition = procedure["_def"];
    if (definition.type === "subscription") continue;
+
    const metadata = getMcpMetadata(definition.meta);
    if (!metadata?.enabled) continue;

-    const name = metadata.name ?? path.replaceAll(".", "_");
-    const paths = names.get(name) ?? [];
-    paths.push(path);
-    names.set(name, paths);
-    if (!/^[a-zA-Z0-9_.-]{1,128}$/.test(name)) {
-      diagnostics.push({ name, path, reason: "invalid_name" });
-      continue;
-    }
+    const inputs = definition.inputs.filter((input): input is z.ZodType => input instanceof z.ZodType);
+    const procedureInput = getProcedureInput(inputs);

-    const inputs = definition.inputs;
-    let inputMode: McpTool["inputMode"] = "object";
-    if (inputs.every((input) => input instanceof z.ZodUndefined || input instanceof z.ZodVoid)) inputMode = "none";
-    const objectInputs = inputs.map(getObjectInput);
-    if (inputMode === "object" && !objectInputs.every((input) => input !== null)) {
-      diagnostics.push({ name, path, reason: "unsupported_input" });
-      continue;
+    if (
+      procedureInput === null ||
+      (!(procedureInput instanceof z.ZodObject) && !procedureInput.safeParse(undefined).success)
+    ) {
+      console.warn(`[MCP] Procedure ${path} does not use an object input schema; using an empty schema`);
    }
+    const inputValidator = procedureInput instanceof z.ZodObject ? procedureInput : emptyInput;

-    try {
-      let input: z.ZodType = emptyInput;
-      if (inputMode === "object") {
-        const objects = objectInputs.filter((schema): schema is z.ZodObject => schema !== null);
-        input = objects[0] ?? emptyInput;
-        for (const object of objects.slice(1)) input = z.intersection(input, object);
-      }
-      const inputSchema = z.toJSONSchema(input, {
-        io: "input",
-        override: ({ zodSchema, jsonSchema }) => {
-          if (zodSchema["_zod"].def.type !== "string") return;
-          if (zodSchema["_zod"].def.checks?.some((check) => check["_zod"].def.check === "overwrite")) {
-            // trim/case normalization runs before these checks in tRPC. They cannot constrain raw JSON.
-            delete jsonSchema.minLength;
-            delete jsonSchema.maxLength;
-            delete jsonSchema.pattern;
-            delete jsonSchema.allOf;
-            delete jsonSchema.format;
-          }
-          // Zod's ISO regex permits minute precision; JSON Schema date-time requires seconds.
-          if (jsonSchema.format === "date-time" && typeof jsonSchema.pattern === "string") {
-            delete jsonSchema.format;
-          }
-        },
-      });
-      // Chained tRPC object inputs produce allOf; MCP requires an explicit object root.
-      if (inputSchema.type !== undefined && inputSchema.type !== "object") throw new Error("Invalid root");
-      inputSchema.type = "object";
-      // Zod and the SDK disagree on JSON Schema vocabulary types; compilation checks the actual schema.
-      schemaValidator.getValidator(inputSchema as Parameters<typeof schemaValidator.getValidator>[0]);
-      tools.push({
-        name,
-        description: metadata.description ?? "",
-        type: definition.type,
-        pathInRouter: path.split("."),
-        inputMode,
-        inputSchema,
-      });
-    } catch {
-      // Conversion errors can contain schema metadata. Only expose a stable, safe reason.
-      diagnostics.push({ name, path, reason: "invalid_schema" });
-    }
+    tools.push({
+      name: metadata.name ?? path.replaceAll(".", "_"),
+      description: metadata.description ?? "",
+      type: definition.type,
+      pathInRouter: path.split("."),
+      inputValidator,
+      inputSchema: normalizeJsonSchema(
+        z.toJSONSchema(inputValidator, {
+          unrepresentable: "any",
+        }),
+      ),
+    });
  }

-  const duplicates = new Set<string>();
-  for (const [name, paths] of names) {
-    if (paths.length < 2) continue;
-    duplicates.add(name);
-    for (const path of paths) diagnostics.push({ name, path, reason: "duplicate_name" });
-  }
-  return {
-    tools: tools
-      .filter((tool) => !duplicates.has(tool.name))
-      .toSorted((left, right) => left.name.localeCompare(right.name)),
-    diagnostics: diagnostics.toSorted(
-      (left, right) => left.path.localeCompare(right.path) || left.reason.localeCompare(right.reason),
-    ),
-  };
-}
-
-/** Dispatch raw JSON through the caller so tRPC owns parsing, transforms, and authorization. */
-export async function callMcpTool(caller: unknown, tool: McpTool, input: unknown) {
-  let procedure = caller;
-  for (const segment of tool.pathInRouter) {
-    if ((typeof procedure !== "object" && typeof procedure !== "function") || procedure === null) {
-      throw new Error("Tool is not callable");
-    }
-    procedure = (procedure as Record<string, unknown>)[segment];
-  }
-  if (typeof procedure !== "function") throw new Error("Tool is not callable");
-  let procedureInput = input;
-  if (tool.inputMode === "none") procedureInput = undefined;
-  else if (input === undefined) procedureInput = {};
-  return await (procedure as (value: unknown) => Promise<unknown>)(procedureInput);
+  return tools.toSorted((left, right) => left.name.localeCompare(right.name));
 }
@@ -1,5 +1,5 @@
 export { createTRPCContext } from "./trpc";
-export { callMcpTool, extractMcpToolsFromProcedures } from "./mcp-tools";
+export { extractMcpToolsFromProcedures } from "./mcp-tools";
 export type { McpTool } from "./mcp-tools";

 import { createTRPCRouter } from "./trpc";
@@ -56,7 +56,7 @@ export const inviteRouter = createTRPCRouter({
    .requiresPermission("admin")
    .input(
      z.object({
-        expirationDate: z.iso.datetime({ offset: true }),
+        expirationDate: z.date(),
      }),
    )
    .output(z.object({ id: z.string(), token: z.string() }))
@@ -80,7 +80,7 @@ export const inviteRouter = createTRPCRouter({

      await ctx.db.insert(invites).values({
        id,
-        expirationDate: new Date(input.expirationDate),
+        expirationDate: input.expirationDate,
        creatorId: ctx.session.user.id,
        token,
      });
@@ -123,7 +123,7 @@ describe("create should create a new invite expiring on the specified date with

    // Act
    const result = await caller.createInvite({
-      expirationDate: expirationDate.toISOString(),
+      expirationDate,
    });

    // Assert
@@ -1,12 +1,9 @@
-import { initTRPC } from "@trpc/server";
 import type { TRPCError } from "@trpc/server";
 import { describe, expect, test, vi } from "vitest";
 import { z } from "zod/v4";

 import { mcpRouter } from "../mcp";
-import type { McpMeta } from "../mcp-tools";
-import { createMcpProtocolHandler } from "../../../../apps/nextjs/src/app/api/mcp/_protocol";
-import { callMcpTool, extractMcpToolsFromProcedures } from "../mcp-tools";
+import { extractMcpToolsFromProcedures } from "../mcp-tools";

 vi.mock("@homarr/auth", () => ({}));

@@ -160,7 +157,7 @@ function actualToolInventory() {
    { _def?: { type?: "query" | "mutation" } }
  >;
  return extractMcpToolsFromProcedures(mcpRouter)
-    .tools.map((tool) => {
+    .map((tool) => {
      const procedure = procedures[tool.pathInRouter.join(".")];
      const type = procedure?.["_def"]?.type;
      if (type !== "query" && type !== "mutation") throw new Error(`Unable to classify MCP tool '${tool.name}'`);
@@ -178,7 +175,7 @@ describe("production MCP router", () => {
  });

  test("keeps every secret-bearing tool behind a mutation procedure", () => {
-    const tools = extractMcpToolsFromProcedures(mcpRouter).tools;
+    const tools = extractMcpToolsFromProcedures(mcpRouter);
    const procedures = mcpRouter["_def"].procedures as unknown as Record<
      string,
      { _def?: { type?: "query" | "mutation" } }
@@ -192,7 +189,7 @@ describe("production MCP router", () => {
  });

  test("gives every production tool a description", () => {
-    const tools = extractMcpToolsFromProcedures(mcpRouter).tools;
+    const tools = extractMcpToolsFromProcedures(mcpRouter);
    for (const tool of tools) expect(tool.description, `Tool ${tool.name} should have a description`).toBeTruthy();
    expect(tools.find((tool) => tool.name === "customWidget_getAuthoringPrompt")?.description).toBe(
      "Get the current Custom Widget authoring instructions.",
@@ -200,17 +197,16 @@ describe("production MCP router", () => {
  });
 });

-test("MCP tools are deterministically ordered and have valid production schemas", () => {
-  expect(extractMcpToolsFromProcedures(mcpRouter).diagnostics).toEqual([]);
-  const tools = extractMcpToolsFromProcedures(mcpRouter).tools;
+test("MCP tools are deterministically ordered and retain executable schemas", () => {
+  const tools = extractMcpToolsFromProcedures(mcpRouter);
  const toolNames = tools.map((tool) => tool.name);

  expect(toolNames).toEqual(toolNames.toSorted((left, right) => left.localeCompare(right)));
-  expect(tools.every((tool) => tool.inputSchema.type === "object")).toBe(true);
+  expect(tools.every((tool) => tool.inputValidator instanceof z.ZodObject)).toBe(true);
 });

 test("publishes both Custom Widget template input formats", () => {
-  const tool = extractMcpToolsFromProcedures(mcpRouter).tools.find(
+  const tool = extractMcpToolsFromProcedures(mcpRouter).find(
    (candidate) => candidate.name === "customWidget_validateTemplate",
  );

@@ -359,119 +355,3 @@ describe("custom widget authoring procedure access", () => {
    );
  });
 });
-
-describe("MCP catalog diagnostics", () => {
-  const trpc = initTRPC.meta<McpMeta>().create();
-  const exposed = trpc.procedure.meta({ mcp: { enabled: true } });
-
-  test("omits unsupported parsers and malformed schemas without losing valid tools", () => {
-    const router = trpc.router({
-      good: exposed.input(z.object({ name: z.string() })).query(() => "ok"),
-      date: exposed.input(z.object({ date: z.date() })).query(() => "unused"),
-      scalar: exposed.input(z.string()).query(() => "unused"),
-      parser: exposed.input({ parse: (value: unknown) => value }).query(() => "unused"),
-      malformed: exposed
-        .input(z.object({ value: z.string().meta({ type: "invalid-json-type" }) }))
-        .query(() => "unused"),
-    });
-    const catalog = extractMcpToolsFromProcedures(router);
-    expect(catalog.tools.map((tool) => tool.name)).toEqual(["good"]);
-    expect(catalog.diagnostics).toEqual([
-      { name: "date", path: "date", reason: "invalid_schema" },
-      { name: "malformed", path: "malformed", reason: "invalid_schema" },
-      { name: "parser", path: "parser", reason: "unsupported_input" },
-      { name: "scalar", path: "scalar", reason: "unsupported_input" },
-    ]);
-  });
-
-  test("omits all duplicate names even when one procedure has an invalid schema", () => {
-    const shared = trpc.procedure.meta({ mcp: { enabled: true, name: "shared" } });
-    const catalog = extractMcpToolsFromProcedures(
-      trpc.router({
-        first: shared.query(() => "first"),
-        second: shared.input(z.object({ date: z.date() })).query(() => "second"),
-        good: exposed.query(() => "good"),
-        invalidName: trpc.procedure.meta({ mcp: { enabled: true, name: "bad name" } }).query(() => "unused"),
-      }),
-    );
-    expect(catalog.tools.map((tool) => tool.name)).toEqual(["good"]);
-    expect(catalog.diagnostics.filter((diagnostic) => diagnostic.reason === "duplicate_name")).toEqual([
-      { name: "shared", path: "first", reason: "duplicate_name" },
-      { name: "shared", path: "second", reason: "duplicate_name" },
-    ]);
-    expect(catalog.diagnostics).toContainEqual({ name: "bad name", path: "invalidName", reason: "invalid_name" });
-  });
-
-  test("distinguishes empty object input from no input for shared Assistant dispatch", async () => {
-    const router = trpc.router({
-      none: exposed.query(({ input }) => input),
-      explicitNone: exposed.input(z.undefined()).query(({ input }) => input),
-      object: exposed.input(z.object({ value: z.string().default("default") })).query(({ input }) => input),
-      optional: exposed
-        .input(z.object({ value: z.string().default("default") }).optional())
-        .query(({ input }) => input),
-    });
-    const catalog = extractMcpToolsFromProcedures(router);
-    expect(catalog.diagnostics).toEqual([]);
-    for (const tool of catalog.tools) {
-      const result = await callMcpTool(router.createCaller({}), tool, {});
-      if (tool.inputMode === "none") expect(result).toBeUndefined();
-      else expect(result).toEqual({ value: "default" });
-    }
-  });
-});
-
-test.each([false, true])(
-  "production catalog registers through the real protocol handler (modern=%s)",
-  async (modern) => {
-    const { tools, diagnostics } = extractMcpToolsFromProcedures(mcpRouter);
-    expect(diagnostics).toEqual([]);
-    const handler = createMcpProtocolHandler({
-      caller: {},
-      tools,
-      version: "test",
-      instructions: "test",
-      formatToolError: () => "Tool failed",
-    });
-    const headers: Record<string, string> = {
-      "Content-Type": "application/json",
-      Accept: "application/json, text/event-stream",
-    };
-    const params: Record<string, unknown> = {};
-    if (modern) {
-      headers["Mcp-Method"] = "tools/list";
-      headers["Mcp-Name"] = "homarr";
-      params["_meta"] = {
-        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
-        "io.modelcontextprotocol/clientInfo": { name: "catalog-test", version: "1" },
-        "io.modelcontextprotocol/clientCapabilities": {},
-      };
-    }
-    const response = await handler.fetch(
-      new Request("http://homarr.test/api/mcp", {
-        method: "POST",
-        headers,
-        body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list", params }),
-      }),
-    );
-    expect(response.status).toBe(200);
-    expect(response.headers.has("Mcp-Session-Id")).toBe(false);
-    const body = await response.text();
-    let payload = body;
-    if (response.headers.get("Content-Type")?.includes("text/event-stream")) {
-      payload =
-        body
-          .split("\n")
-          .find((line) => line.startsWith("data: "))
-          ?.slice(6) ?? "";
-    }
-    const result = JSON.parse(payload) as {
-      error?: unknown;
-      result: { tools: { name: string; inputSchema: unknown }[] };
-    };
-    expect(result.error).toBeUndefined();
-    expect(result.result.tools.map((tool) => ({ name: tool.name, inputSchema: tool.inputSchema }))).toEqual(
-      tools.map((tool) => ({ name: tool.name, inputSchema: tool.inputSchema })),
-    );
-  },
-);
@@ -366,9 +366,6 @@ catalogs:
    ai:
      specifier: ^7.0.56
      version: 7.0.56
-    ajv:
-      specifier: 8.18.0
-      version: 8.18.0
    assistant-stream:
      specifier: 0.3.34
      version: 0.3.34
@@ -1523,9 +1520,6 @@ importers:
      '@kubernetes/client-node':
        specifier: 'catalog:'
        version: 1.4.0(supports-color@10.2.2)
-      '@modelcontextprotocol/server':
-        specifier: 'catalog:'
-        version: 2.0.0
      '@tanstack/react-query':
        specifier: 'catalog:'
        version: 5.101.2(react@19.2.7)
@@ -1541,9 +1535,6 @@ importers:
      '@trpc/tanstack-react-query':
        specifier: 'catalog:'
        version: 11.18.0(@tanstack/react-query@5.101.2(react@19.2.7))(@trpc/client@11.18.0(@trpc/server@11.18.0(typescript@7.0.2))(typescript@7.0.2))(@trpc/server@11.18.0(typescript@7.0.2))(react@19.2.7)(typescript@7.0.2)
-      ajv:
-        specifier: 'catalog:'
-        version: 8.18.0
      lodash.clonedeep:
        specifier: 'catalog:'
        version: 4.5.0
@@ -123,7 +123,6 @@ catalog:
  adm-zip: 0.6.0
  acorn: ^8.16.0
  acorn-jsx: ^5.3.2
-  ajv: 8.18.0
  jszip: ^3.10.1
  sql.js: ^1.14.1
  babel-plugin-react-compiler: ^1.0.0
Author	SHA1	Message	Date
ajnart	cc015463f3	fix(board): disable displaced item movement animations	2026-09-09 14:37:33 +02:00
ajnart	4df618e418	fix(board): retain swap previews until layout commit renders	2026-09-09 11:59:10 +02:00
ajnart	dba4c27ea5	fix(board): make container editor centering order independent	2026-09-09 10:38:26 +02:00
ajnart	6f2bcb8054	fix(board): restore container grid geometry	2026-09-09 09:21:13 +02:00