feat: expand utility widgets (#6638)

packages/api/src/mcp.ts

@@ -12,6 +12,7 @@ import { iconsRouter } from "./router/icons";
 import { infoRouter } from "./router/info";
 import { integrationRouter } from "./router/integration/integration-router";
 import { inviteRouter } from "./router/invite";
+import { airQualityRouter } from "./router/widgets/air-quality";
 import { bazarrRouter } from "./router/widgets/bazarr";
 import { serverSettingsRouter } from "./router/serverSettings";
 import { beszelRouter } from "./router/widgets/beszel";
@@ -35,6 +36,7 @@ export const mcpRouter = createTRPCRouter({
   info: infoRouter,
   integration: integrationRouter,
   invite: inviteRouter,
+  airQuality: airQualityRouter,
   bazarr: bazarrRouter,
   serverSettings: serverSettingsRouter,
   beszel: beszelRouter,

packages/api/src/router/widgets/air-quality.ts

@@ -0,0 +1,29 @@
+import { z } from "zod/v4";
+
+import { env } from "@homarr/common/env";
+import { airQualityRequestHandler } from "@homarr/request-handler/air-quality";
+
+import { createTRPCRouter, publicProcedure } from "../../trpc";
+
+const atLocationInput = z.object({
+  longitude: z.number().min(-180).max(180),
+  latitude: z.number().min(-90).max(90),
+});
+
+export const airQualityRouter = createTRPCRouter({
+  atLocation: publicProcedure
+    .meta({
+      mcp: {
+        enabled: true,
+        description:
+          "Get current and forecast air quality, UV, pollutant, and pollen data for geographic coordinates. REQUIRED: latitude (-90 to 90) and longitude (-180 to 180).",
+      },
+    })
+    .input(atLocationInput)
+    .query(async ({ input }) => {
+      if (env.NO_EXTERNAL_CONNECTION) return null;
+
+      const handler = airQualityRequestHandler.handler(input);
+      return await handler.getDataAsync().then((result) => result.data);
+    }),
+});

packages/api/src/router/widgets/index.ts

@@ -13,6 +13,7 @@ export const widgetRouter = createTRPCRouter({
   bazarr: lazy(() => import("./bazarr").then((mod) => mod.bazarrRouter)),
   notebook: lazy(() => import("./notebook").then((mod) => mod.notebookRouter)),
   weather: lazy(() => import("./weather").then((mod) => mod.weatherRouter)),
+  airQuality: lazy(() => import("./air-quality").then((mod) => mod.airQualityRouter)),
   app: lazy(() => import("./app").then((mod) => mod.appRouter)),
   dnsHole: lazy(() => import("./dns-hole").then((mod) => mod.dnsHoleRouter)),
   smartHome: lazy(() => import("./smart-home").then((mod) => mod.smartHomeRouter)),

packages/api/src/router/widgets/weather.ts

@@ -6,8 +6,8 @@ import { weatherRequestHandler } from "@homarr/request-handler/weather";
 import { createTRPCRouter, publicProcedure } from "../../trpc";
 
 const atLocationInput = z.object({
-  longitude: z.number(),
-  latitude: z.number(),
+  longitude: z.number().min(-180).max(180),
+  latitude: z.number().min(-90).max(90),
 });
 
 export const weatherRouter = createTRPCRouter({

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

@@ -9,6 +9,7 @@ vi.mock("@homarr/auth", () => ({}));
 
 const MCP_TOOL_ALLOWLIST = {
   query: [
+    "airQuality_atLocation",
     "apiKeys_getAll",
     "app_all",
     "app_byId",