style: auto-fix lint and format

apps/docs/docs/management/api/index.mdx

@@ -70,4 +70,16 @@ API key authentication enables programmatic access for:
 - Automation scripts and CI/CD pipelines
 - Third-party integrations
 - Custom dashboards and monitoring tools
-- Container orchestration systems that need to sync app definitions
+- Container orchestration systems that need to sync app definitions
+
+## Board Automation
+
+The OpenAPI and MCP APIs include board management endpoints for common automation workflows:
+
+- Create, duplicate, rename and delete boards
+- Change board visibility
+- Update board visual and behavior settings
+- Set desktop and mobile home boards for the current user
+- Configure global board defaults such as public home boards and status behavior
+
+Use the interactive API reference to inspect the exact request body for each endpoint under the `boards` and `settings` tags.

apps/docs/static/api/open-api-schema.json

@@ -1 +1 @@
-{"openapi":"3.1.0","info":{"title":"Homarr API documentation","version":"1.0.0"},"servers":[{"url":"http://localhost:3000"}],"externalDocs":{"url":"https://homarr.dev"},"paths":{"/api/apps/paginated":{"get":{"operationId":"appRouter-getPaginated","tags":["apps"],"security":[{"apikey":[]}],"parameters":[{"in":"query","name":"search","schema":{"type":"string"}},{"in":"query","name":"pageSize","schema":{"default":10,"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"in":"query","name":"page","schema":{"default":1,"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"iconUrl":{"type":"string"},"href":{"anyOf":[{"type":"string"},{"type":"null"}]},"pingUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","description","iconUrl","href","pingUrl"],"additionalProperties":false}},"totalCount":{"type":"number"}},"required":["items","totalCount"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/api/apps":{"get":{"operationId":"appRouter-all","tags":["apps"],"security":[{"apikey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"iconUrl":{"type":"string"},"href":{"anyOf":[{"type":"string"},{"type":"null"}]},"pingUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","description","iconUrl","href","pingUrl"],"additionalProperties":false}}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}},"post":{"operationId":"appRouter-create","tags":["apps"],"security":[{"apikey":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64},"description":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}]},"iconUrl":{"type":"string","minLength":1},"href":{"anyOf":[{"anyOf":[{"type":"string","pattern":"^(?!javascript)[a-zA-Z]*:\\/\\/"},{"type":"string","const":""}]},{"type":"null"}]},"pingUrl":{"anyOf":[{"anyOf":[{"type":"string","pattern":"^https?:\\/\\/"},{"type":"string","const":""}]},{"type":"null"}]}},"required":["name","description","iconUrl","href","pingUrl"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"appId":{"type":"string"}},"required":["appId"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"iconUrl":{"type":"string"},"href":{"anyOf":[{"type":"string"},{"type":"null"}]},"pingUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","description","iconUrl","href","pingUrl"],"additionalProperties":false}]}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/api/apps/search":{"get":{"operationId":"appRouter-search","tags":["apps"],"security":[{"apikey":[]}],"parameters":[{"in":"query","name":"query","schema":{"type":"string"},"required":true},{"in":"queLine truncated
+{"openapi":"3.1.0","info":{"title":"Homarr API documentation","version":"1.1.0"},"servers":[{"url":"http://localhost:3000"}],"externalDocs":{"url":"https://homarr.dev"},"paths":{"/api/apps/paginated":{"get":{"operationId":"appRouter-getPaginated","tags":["apps"],"security":[{"apikey":[]}],"parameters":[{"in":"query","name":"search","schema":{"type":"string"}},{"in":"query","name":"pageSize","schema":{"default":10,"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"in":"query","name":"page","schema":{"default":1,"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"iconUrl":{"type":"string"},"href":{"anyOf":[{"type":"string"},{"type":"null"}]},"pingUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","description","iconUrl","href","pingUrl"],"additionalProperties":false}},"totalCount":{"type":"number"}},"required":["items","totalCount"],"additionalProperties":false}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/api/apps":{"get":{"operationId":"appRouter-all","tags":["apps"],"security":[{"apikey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"iconUrl":{"type":"string"},"href":{"anyOf":[{"type":"string"},{"type":"null"}]},"pingUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","description","iconUrl","href","pingUrl"],"additionalProperties":false}}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}},"post":{"operationId":"appRouter-create","tags":["apps"],"security":[{"apikey":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64},"description":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}]},"iconUrl":{"type":"string","minLength":1},"href":{"anyOf":[{"anyOf":[{"type":"string","pattern":"^(?!javascript)[a-zA-Z]*:\\/\\/"},{"type":"string","const":""}]},{"type":"null"}]},"pingUrl":{"anyOf":[{"anyOf":[{"type":"string","pattern":"^https?:\\/\\/"},{"type":"string","const":""}]},{"type":"null"}]}},"required":["name","description","iconUrl","href","pingUrl"]}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"appId":{"type":"string"}},"required":["appId"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"iconUrl":{"type":"string"},"href":{"anyOf":[{"type":"string"},{"type":"null"}]},"pingUrl":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name","description","iconUrl","href","pingUrl"],"additionalProperties":false}]}}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.BAD_REQUEST"}}}},"401":{"description":"Authorization not provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.UNAUTHORIZED"}}}},"403":{"description":"Insufficient access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.FORBIDDEN"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.INTERNAL_SERVER_ERROR"}}}}}}},"/api/apps/search":{"get":{"operationId":"appRouter-search","tags":["apps"],"security":[{"apikey":[]}],"parameters":[{"in":"query","name":"query","schema":{"type":"string"},"required":true},{"in":"queLine truncated

packages/api/src/mcp.ts

@@ -9,6 +9,7 @@ import { iconsRouter } from "./router/icons";
 import { infoRouter } from "./router/info";
 import { integrationRouter } from "./router/integration/integration-router";
 import { inviteRouter } from "./router/invite";
+import { serverSettingsRouter } from "./router/serverSettings";
 import { beszelRouter } from "./router/widgets/beszel";
 import { calendarRouter } from "./router/widgets/calendar";
 import { dnsHoleRouter } from "./router/widgets/dns-hole";
@@ -28,6 +29,7 @@ export const mcpRouter = createTRPCRouter({
   info: infoRouter,
   integration: integrationRouter,
   invite: inviteRouter,
+  serverSettings: serverSettingsRouter,
   beszel: beszelRouter,
   calendar: calendarRouter,
   dnsHole: dnsHoleRouter,

packages/api/src/open-api.ts

@@ -6,6 +6,7 @@ import { appRouter } from "./router/app";
 import { boardRouter } from "./router/board";
 import { infoRouter } from "./router/info";
 import { inviteRouter } from "./router/invite";
+import { serverSettingsRouter } from "./router/serverSettings";
 import { userRouter } from "./router/user";
 import { createTRPCRouter } from "./trpc";
 
@@ -14,13 +15,14 @@ export const openApiRouter = createTRPCRouter({
   boardRouter,
   infoRouter,
   inviteRouter,
+  serverSettingsRouter,
   userRouter,
 });
 
 export const openApiDocument = (base: string) =>
   generateOpenApiDocument(openApiRouter, {
     title: "Homarr API documentation",
-    version: "1.0.0",
+    version: "1.1.0",
     baseUrl: base,
     docsUrl: "https://homarr.dev",
     securitySchemes: {

packages/api/src/router/board.ts

@@ -330,7 +330,16 @@ export const boardRouter = createTRPCRouter({
     }),
   duplicateBoard: permissionRequiredProcedure
     .requiresPermission("board-create")
+    .meta({
+      openapi: { method: "POST", path: "/api/boards/{id}/duplicate", tags: ["boards"], protect: true },
+      mcp: {
+        enabled: true,
+        description:
+          "Duplicate an existing board into a new board. Requires board-create permission and view permission on the source board. REQUIRED: id (source board ID), name (unique name for the new board). Returns { boardId }",
+      },
+    })
     .input(boardDuplicateSchema)
+    .output(z.object({ boardId: z.string() }))
     .mutation(async ({ ctx, input }) => {
       await throwIfActionForbiddenAsync(ctx, eq(boards.id, input.id), "view");
       await noBoardWithSimilarNameAsync(ctx.db, input.name);
@@ -544,33 +553,57 @@ export const boardRouter = createTRPCRouter({
           });
         },
       });
+
+      return { boardId: newBoardId };
     }),
-  renameBoard: protectedProcedure.input(boardRenameSchema).mutation(async ({ ctx, input }) => {
-    await throwIfActionForbiddenAsync(ctx, eq(boards.id, input.id), "full");
+  renameBoard: protectedProcedure
+    .meta({
+      openapi: { method: "PATCH", path: "/api/boards/{id}/name", tags: ["boards"], protect: true },
+      mcp: {
+        enabled: true,
+        description:
+          "Rename a board by ID. Requires full permission on the board. REQUIRED: id (board ID), name (new unique board name)",
+      },
+    })
+    .input(boardRenameSchema)
+    .output(z.void())
+    .mutation(async ({ ctx, input }) => {
+      await throwIfActionForbiddenAsync(ctx, eq(boards.id, input.id), "full");
 
-    await noBoardWithSimilarNameAsync(ctx.db, input.name, [input.id]);
+      await noBoardWithSimilarNameAsync(ctx.db, input.name, [input.id]);
 
-    await ctx.db.update(boards).set({ name: input.name }).where(eq(boards.id, input.id));
-  }),
-  changeBoardVisibility: protectedProcedure.input(boardChangeVisibilitySchema).mutation(async ({ ctx, input }) => {
-    await throwIfActionForbiddenAsync(ctx, eq(boards.id, input.id), "full");
-    const boardSettings = await getServerSettingByKeyAsync(ctx.db, "board");
+      await ctx.db.update(boards).set({ name: input.name }).where(eq(boards.id, input.id));
+    }),
+  changeBoardVisibility: protectedProcedure
+    .meta({
+      openapi: { method: "PATCH", path: "/api/boards/{id}/visibility", tags: ["boards"], protect: true },
+      mcp: {
+        enabled: true,
+        description:
+          "Change board visibility. Requires full permission on the board. REQUIRED: id (board ID), visibility ('public' or 'private'). Home boards cannot be made private",
+      },
+    })
+    .input(boardChangeVisibilitySchema)
+    .output(z.void())
+    .mutation(async ({ ctx, input }) => {
+      await throwIfActionForbiddenAsync(ctx, eq(boards.id, input.id), "full");
+      const boardSettings = await getServerSettingByKeyAsync(ctx.db, "board");
 
-    if (
-      input.visibility !== "public" &&
-      (boardSettings.homeBoardId === input.id || boardSettings.mobileHomeBoardId === input.id)
-    ) {
-      throw new TRPCError({
-        code: "BAD_REQUEST",
-        message: "Cannot make home board private",
-      });
-    }
+      if (
+        input.visibility !== "public" &&
+        (boardSettings.homeBoardId === input.id || boardSettings.mobileHomeBoardId === input.id)
+      ) {
+        throw new TRPCError({
+          code: "BAD_REQUEST",
+          message: "Cannot make home board private",
+        });
+      }
 
-    await ctx.db
-      .update(boards)
-      .set({ isPublic: input.visibility === "public" })
-      .where(eq(boards.id, input.id));
-  }),
+      await ctx.db
+        .update(boards)
+        .set({ isPublic: input.visibility === "public" })
+        .where(eq(boards.id, input.id));
+    }),
   deleteBoard: protectedProcedure
     .meta({
       openapi: { method: "DELETE", path: "/api/boards/{id}", tags: ["boards"], protect: true },
@@ -587,16 +620,38 @@ export const boardRouter = createTRPCRouter({
 
       await ctx.db.delete(boards).where(eq(boards.id, input.id));
     }),
-  setHomeBoard: protectedProcedure.input(z.object({ id: z.string() })).mutation(async ({ ctx, input }) => {
-    await throwIfActionForbiddenAsync(ctx, eq(boards.id, input.id), "view");
+  setHomeBoard: protectedProcedure
+    .meta({
+      openapi: { method: "PATCH", path: "/api/boards/{id}/home", tags: ["boards"], protect: true },
+      mcp: {
+        enabled: true,
+        description:
+          "Set the current user's desktop home board. Requires view permission on the board. REQUIRED: id (board ID)",
+      },
+    })
+    .input(z.object({ id: z.string() }))
+    .output(z.void())
+    .mutation(async ({ ctx, input }) => {
+      await throwIfActionForbiddenAsync(ctx, eq(boards.id, input.id), "view");
 
-    await ctx.db.update(users).set({ homeBoardId: input.id }).where(eq(users.id, ctx.session.user.id));
-  }),
-  setMobileHomeBoard: protectedProcedure.input(z.object({ id: z.string() })).mutation(async ({ ctx, input }) => {
-    await throwIfActionForbiddenAsync(ctx, eq(boards.id, input.id), "view");
+      await ctx.db.update(users).set({ homeBoardId: input.id }).where(eq(users.id, ctx.session.user.id));
+    }),
+  setMobileHomeBoard: protectedProcedure
+    .meta({
+      openapi: { method: "PATCH", path: "/api/boards/{id}/mobile-home", tags: ["boards"], protect: true },
+      mcp: {
+        enabled: true,
+        description:
+          "Set the current user's mobile home board. Requires view permission on the board. REQUIRED: id (board ID)",
+      },
+    })
+    .input(z.object({ id: z.string() }))
+    .output(z.void())
+    .mutation(async ({ ctx, input }) => {
+      await throwIfActionForbiddenAsync(ctx, eq(boards.id, input.id), "view");
 
-    await ctx.db.update(users).set({ mobileHomeBoardId: input.id }).where(eq(users.id, ctx.session.user.id));
-  }),
+      await ctx.db.update(users).set({ mobileHomeBoardId: input.id }).where(eq(users.id, ctx.session.user.id));
+    }),
   getHomeBoard: publicProcedure.query(async ({ ctx }) => {
     const userId = ctx.session?.user.id;
     const user = userId
@@ -752,7 +807,16 @@ export const boardRouter = createTRPCRouter({
     }
   }),
   savePartialBoardSettings: protectedProcedure
-    .input(boardSavePartialSettingsSchema.and(z.object({ id: z.string() })))
+    .meta({
+      openapi: { method: "PATCH", path: "/api/boards/{id}/settings", tags: ["boards"], protect: true },
+      mcp: {
+        enabled: true,
+        description:
+          "Update visual and behavior settings for a board. Requires modify permission. REQUIRED: id (board ID). Optional fields include pageTitle, metaTitle, logoImageUrl, faviconImageUrl, backgroundImageUrl, colors, opacity, customCss, itemRadius, and disableStatus",
+      },
+    })
+    .input(boardSavePartialSettingsSchema.extend({ id: z.string() }))
+    .output(z.void())
     .mutation(async ({ ctx, input }) => {
       await throwIfActionForbiddenAsync(ctx, eq(boards.id, input.id), "modify");
 

packages/api/src/router/serverSettings.ts

@@ -1,6 +1,14 @@
+import { TRPCError } from "@trpc/server";
 import { z } from "zod/v4";
 
-import { getServerSettingByKeyAsync, getServerSettingsAsync, updateServerSettingByKeyAsync } from "@homarr/db/queries";
+import { and, eq, inArray } from "@homarr/db";
+import {
+  getServerSettingByKeyAsync,
+  getServerSettingsAsync,
+  insertServerSettingByKeyAsync,
+  updateServerSettingByKeyAsync,
+} from "@homarr/db/queries";
+import { boards, serverSettings } from "@homarr/db/schema";
 import type { ServerSettings } from "@homarr/server-settings";
 import { defaultServerSettingsKeys } from "@homarr/server-settings";
 import { settingsInitSchema } from "@homarr/validation/settings";
@@ -8,6 +16,15 @@ import { settingsInitSchema } from "@homarr/validation/settings";
 import { createTRPCRouter, onboardingProcedure, permissionRequiredProcedure, publicProcedure } from "../trpc";
 import { nextOnboardingStepAsync } from "./onboard/onboard-queries";
 
+const boardServerSettingsSchema = z.object({
+  homeBoardId: z.string().nullable(),
+  mobileHomeBoardId: z.string().nullable(),
+  enableStatusByDefault: z.boolean(),
+  forceDisableStatus: z.boolean(),
+}) satisfies z.ZodType<ServerSettings["board"]>;
+
+const boardServerSettingsUpdateSchema = boardServerSettingsSchema.partial();
+
 export const serverSettingsRouter = createTRPCRouter({
   getCulture: publicProcedure.query(async ({ ctx }) => {
     return await getServerSettingByKeyAsync(ctx.db, "culture");
@@ -15,6 +32,67 @@ export const serverSettingsRouter = createTRPCRouter({
   getAll: permissionRequiredProcedure.requiresPermission("admin").query(async ({ ctx }) => {
     return await getServerSettingsAsync(ctx.db);
   }),
+  getBoardSettings: permissionRequiredProcedure
+    .requiresPermission("admin")
+    .meta({
+      openapi: { method: "GET", path: "/api/settings/board", tags: ["settings"], protect: true },
+      mcp: {
+        enabled: true,
+        description:
+          "Get global board defaults, including desktop/mobile home board IDs and status behavior. Requires admin permission",
+      },
+    })
+    .input(z.void())
+    .output(boardServerSettingsSchema)
+    .query(async ({ ctx }) => {
+      return await getServerSettingByKeyAsync(ctx.db, "board");
+    }),
+  updateBoardSettings: permissionRequiredProcedure
+    .requiresPermission("admin")
+    .meta({
+      openapi: { method: "PATCH", path: "/api/settings/board", tags: ["settings"], protect: true },
+      mcp: {
+        enabled: true,
+        description:
+          "Update global board defaults. Requires admin permission. Optional fields: homeBoardId, mobileHomeBoardId, enableStatusByDefault, forceDisableStatus. Home board IDs must reference public boards or be null",
+      },
+    })
+    .input(boardServerSettingsUpdateSchema)
+    .output(boardServerSettingsSchema)
+    .mutation(async ({ ctx, input }) => {
+      const inputBoardIds = [input.homeBoardId, input.mobileHomeBoardId].filter(
+        (id) => id !== undefined && id !== null,
+      );
+
+      if (inputBoardIds.length > 0) {
+        const publicBoards = await ctx.db.query.boards.findMany({
+          columns: { id: true },
+          where: and(inArray(boards.id, inputBoardIds), eq(boards.isPublic, true)),
+        });
+        const publicBoardIds = new Set(publicBoards.map((board) => board.id));
+        const invalidBoardIds = inputBoardIds.filter((id) => !publicBoardIds.has(id));
+        if (invalidBoardIds.length > 0) {
+          throw new TRPCError({
+            code: "BAD_REQUEST",
+            message: `Board settings home board IDs must reference public boards: ${invalidBoardIds.join(", ")}`,
+          });
+        }
+      }
+
+      const current = await getServerSettingByKeyAsync(ctx.db, "board");
+      const next = { ...current, ...input };
+      const existing = await ctx.db.query.serverSettings.findFirst({
+        where: eq(serverSettings.settingKey, "board"),
+      });
+
+      if (existing) {
+        await updateServerSettingByKeyAsync(ctx.db, "board", next);
+      } else {
+        await insertServerSettingByKeyAsync(ctx.db, "board", next);
+      }
+
+      return next;
+    }),
   saveSettings: permissionRequiredProcedure
     .requiresPermission("admin")
     .input(

packages/api/src/router/test/serverSettings.spec.ts

@@ -1,9 +1,9 @@
-import SuperJSON from "superjson";
+import { stringify } from "superjson";
 import { describe, expect, test, vi } from "vitest";
 
 import type { Session } from "@homarr/auth";
 import { createId } from "@homarr/common";
-import { serverSettings } from "@homarr/db/schema";
+import { boards, serverSettings } from "@homarr/db/schema";
 import { createDb } from "@homarr/db/test";
 import { defaultServerSettings, defaultServerSettingsKeys } from "@homarr/server-settings";
 
@@ -33,7 +33,7 @@ describe("getAll server settings", () => {
     await db.insert(serverSettings).values([
       {
         settingKey: defaultServerSettingsKeys[0],
-        value: SuperJSON.stringify(defaultServerSettings.analytics),
+        value: stringify(defaultServerSettings.analytics),
       },
     ]);
 
@@ -67,7 +67,7 @@ describe("saveSettings", () => {
     await db.insert(serverSettings).values([
       {
         settingKey: defaultServerSettingsKeys[0],
-        value: SuperJSON.stringify(defaultServerSettings.analytics),
+        value: stringify(defaultServerSettings.analytics),
       },
     ]);
 
@@ -82,7 +82,7 @@ describe("saveSettings", () => {
     expect(dbSettings).toStrictEqual([
       {
         settingKey: "analytics",
-        value: SuperJSON.stringify({
+        value: stringify({
           enableGeneral: true,
           instanceId: null,
         }),
@@ -90,3 +90,91 @@ describe("saveSettings", () => {
     ]);
   });
 });
+
+describe("board settings API", () => {
+  test("getBoardSettings should return board defaults", async () => {
+    const db = createDb();
+    const caller = serverSettingsRouter.createCaller({
+      db,
+      deviceType: undefined,
+      session: defaultSession,
+    });
+
+    await expect(caller.getBoardSettings()).resolves.toStrictEqual(defaultServerSettings.board);
+  });
+
+  test("updateBoardSettings should insert settings when defaults are not persisted", async () => {
+    const db = createDb();
+    const caller = serverSettingsRouter.createCaller({
+      db,
+      deviceType: undefined,
+      session: defaultSession,
+    });
+    const boardId = createId();
+    await db.insert(boards).values({ id: boardId, name: "default", isPublic: true });
+
+    const result = await caller.updateBoardSettings({
+      homeBoardId: boardId,
+      forceDisableStatus: true,
+    });
+
+    expect(result).toStrictEqual({
+      ...defaultServerSettings.board,
+      homeBoardId: boardId,
+      forceDisableStatus: true,
+    });
+    const dbSettings = await db.select().from(serverSettings);
+    expect(dbSettings).toStrictEqual([
+      {
+        settingKey: "board",
+        value: stringify(result),
+      },
+    ]);
+  });
+
+  test("updateBoardSettings should update existing settings", async () => {
+    const db = createDb();
+    const caller = serverSettingsRouter.createCaller({
+      db,
+      deviceType: undefined,
+      session: defaultSession,
+    });
+    const boardId = createId();
+    await db.insert(boards).values({ id: boardId, name: "default", isPublic: true });
+
+    await caller.updateBoardSettings({ homeBoardId: boardId });
+    const result = await caller.updateBoardSettings({
+      mobileHomeBoardId: boardId,
+      enableStatusByDefault: false,
+    });
+
+    expect(result).toStrictEqual({
+      ...defaultServerSettings.board,
+      homeBoardId: boardId,
+      mobileHomeBoardId: boardId,
+      enableStatusByDefault: false,
+    });
+    const dbSettings = await db.select().from(serverSettings);
+    expect(dbSettings).toStrictEqual([
+      {
+        settingKey: "board",
+        value: stringify(result),
+      },
+    ]);
+  });
+
+  test("updateBoardSettings should reject private home boards", async () => {
+    const db = createDb();
+    const caller = serverSettingsRouter.createCaller({
+      db,
+      deviceType: undefined,
+      session: defaultSession,
+    });
+    const boardId = createId();
+    await db.insert(boards).values({ id: boardId, name: "private", isPublic: false });
+
+    const actAsync = async () => await caller.updateBoardSettings({ homeBoardId: boardId });
+
+    await expect(actAsync()).rejects.toThrow("must reference public boards");
+  });
+});

packages/api/src/test/mcp.spec.ts

@@ -2,16 +2,20 @@ import { expect, test, vi } from "vitest";
 import { extractToolsFromProcedures } from "trpc-to-mcp";
 
 import { appRouter } from "../router/app";
+import { boardRouter } from "../router/board";
 import { infoRouter } from "../router/info";
 import { inviteRouter } from "../router/invite";
+import { serverSettingsRouter } from "../router/serverSettings";
 import { createTRPCRouter } from "../trpc";
 
 vi.mock("@homarr/auth", () => ({}));
 
 const mcpTestRouter = createTRPCRouter({
   app: appRouter,
+  board: boardRouter,
   info: infoRouter,
   invite: inviteRouter,
+  serverSettings: serverSettingsRouter,
 });
 
 test("MCP tools should be extractable from the router", () => {
@@ -28,8 +32,12 @@ test("MCP tools should contain expected procedures", () => {
   expect(toolNames).toContain("app_all");
   expect(toolNames).toContain("app_byId");
   expect(toolNames).toContain("app_create");
+  expect(toolNames).toContain("board_savePartialBoardSettings");
+  expect(toolNames).toContain("board_duplicateBoard");
   expect(toolNames).toContain("info_getInfo");
   expect(toolNames).toContain("invite_getAll");
+  expect(toolNames).toContain("serverSettings_getBoardSettings");
+  expect(toolNames).toContain("serverSettings_updateBoardSettings");
 });
 
 test("MCP tools should have descriptions", () => {

packages/api/src/test/open-api.spec.ts

@@ -14,3 +14,12 @@ test("OpenAPI documentation should be generated", () => {
   // Assert
   expect(act).not.toThrow();
 });
+
+test("OpenAPI documentation should expose board automation endpoints", () => {
+  const document = openApiDocument("https://homarr.dev");
+
+  expect(document.info.version).toBe("1.1.0");
+  expect(document.paths).toHaveProperty("/api/boards/{id}/settings");
+  expect(document.paths).toHaveProperty("/api/boards/{id}/duplicate");
+  expect(document.paths).toHaveProperty("/api/settings/board");
+});

packages/definitions/src/docs/homarr-docs-sitemap.ts

@@ -60,8 +60,8 @@ export type HomarrDocumentationPath =
   | "/docs/tags/connections"
   | "/docs/tags/custom-widgets"
   | "/docs/tags/customization"
-  | "/docs/tags/data-sources"
   | "/docs/tags/data"
+  | "/docs/tags/data-sources"
   | "/docs/tags/database"
   | "/docs/tags/developer"
   | "/docs/tags/development"
@@ -99,8 +99,8 @@ export type HomarrDocumentationPath =
   | "/docs/tags/redis"
   | "/docs/tags/responsive"
   | "/docs/tags/roles"
-  | "/docs/tags/search-engines"
   | "/docs/tags/search"
+  | "/docs/tags/search-engines"
   | "/docs/tags/secrets"
   | "/docs/tags/security"
   | "/docs/tags/self-signed"
@@ -132,15 +132,6 @@ export type HomarrDocumentationPath =
   | "/docs/advanced/running-as-different-user"
   | "/docs/advanced/single-sign-on"
   | "/docs/advanced/styling"
-  | "/docs/category/advanced"
-  | "/docs/category/community"
-  | "/docs/category/developer-guides"
-  | "/docs/category/getting-started"
-  | "/docs/category/installation-1"
-  | "/docs/category/installation"
-  | "/docs/category/integrations"
-  | "/docs/category/management"
-  | "/docs/category/widgets"
   | "/docs/community/donate"
   | "/docs/community/faq"
   | "/docs/community/get-in-touch"
@@ -205,9 +196,11 @@ export type HomarrDocumentationPath =
   | "/docs/integrations/slskd"
   | "/docs/integrations/sonarr"
   | "/docs/integrations/speedtest-tracker"
+  | "/docs/integrations/synology"
   | "/docs/integrations/tdarr"
   | "/docs/integrations/technitium-dns"
   | "/docs/integrations/tracearr"
+  | "/docs/integrations/traefik"
   | "/docs/integrations/transmission"
   | "/docs/integrations/truenas"
   | "/docs/integrations/umami"
@@ -266,9 +259,11 @@ export type HomarrDocumentationPath =
   | "/docs/widgets/smart-home-execute-automation"
   | "/docs/widgets/speedtest-tracker"
   | "/docs/widgets/stock-price"
+  | "/docs/widgets/system-disks"
   | "/docs/widgets/system-resources"
   | "/docs/widgets/timetable"
   | "/docs/widgets/tracearr"
+  | "/docs/widgets/traefik"
   | "/docs/widgets/umami"
   | "/docs/widgets/ups"
   | "/docs/widgets/uptime-kuma"