refactor: DRY — extract shared responses, health check, config timeout

Albert · claude · Albert · commit e08696fafadc · 2026-03-17T20:25:34.000-03:00
- Add utils/responses.ts: textContent(), errorResponse(), extractError()
  eliminates 12x "type: text as const" and 4x error extraction duplication
- Add services/health-check.ts: shared checkService() + checkAllServices()
  used by both system-status tool and system-status resource
- Move health check timeout to config.healthCheckTimeoutMs
- Simplify all 5 tools and resources to use shared helpers

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/src/resources/index.ts b/src/resources/index.ts
@@ -1,11 +1,9 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { getPrompts, getPromptByName } from "../services/prompt-registry.js";
-import { config } from "../services/config.js";
-import { HttpClient } from "../services/http-client.js";
+import { checkAllServices } from "../services/health-check.js";
 
 export function registerResources(server: McpServer): void {
-  // Static resource: system status
   server.registerResource(
     "system-status",
     "toad://system/status",
@@ -15,53 +13,30 @@ export function registerResources(server: McpServer): void {
       mimeType: "application/json",
     },
     async (uri) => {
-      const checks = await Promise.all(
-        [
-          { name: "Semantic Search API", baseUrl: config.semanticSearch.baseUrl },
-          { name: "Eval Framework", baseUrl: config.evalFramework.baseUrl },
-        ].map(async ({ name, baseUrl }) => {
-          const client = new HttpClient({ baseUrl, timeoutMs: 5_000 });
-          const start = Date.now();
-          try {
-            const res = await client.get<unknown>("/health");
-            return { name, url: baseUrl, healthy: res.ok, latencyMs: Date.now() - start };
-          } catch (error) {
-            return {
-              name,
-              url: baseUrl,
-              healthy: false,
-              latencyMs: Date.now() - start,
-              error: error instanceof Error ? error.message : String(error),
-            };
-          }
-        }),
-      );
+      const status = await checkAllServices();
 
       return {
         contents: [
           {
             uri: uri.href,
-            text: JSON.stringify({ services: checks, allHealthy: checks.every((c) => c.healthy) }, null, 2),
+            text: JSON.stringify(status, null, 2),
             mimeType: "application/json",
           },
         ],
       };
     },
   );
 
-  // Dynamic resource: prompt by name
   const promptTemplate = new ResourceTemplate("toad://prompts/{name}", {
-    list: async () => {
-      return {
-        resources: getPrompts().map((p) => ({
-          uri: `toad://prompts/${p.name}`,
-          name: p.name,
-          title: `${p.name} (v${p.version})`,
-          description: p.description,
-          mimeType: "application/json",
-        })),
-      };
-    },
+    list: async () => ({
+      resources: getPrompts().map((p) => ({
+        uri: `toad://prompts/${p.name}`,
+        name: p.name,
+        title: `${p.name} (v${p.version})`,
+        description: p.description,
+        mimeType: "application/json",
+      })),
+    }),
   });
 
   server.registerResource(
@@ -84,13 +59,7 @@ export function registerResources(server: McpServer): void {
       }
 
       return {
-        contents: [
-          {
-            uri: uri.href,
-            text: JSON.stringify(prompt, null, 2),
-            mimeType: "application/json",
-          },
-        ],
+        contents: [{ uri: uri.href, text: JSON.stringify(prompt, null, 2), mimeType: "application/json" }],
       };
     },
   );
diff --git a/src/services/config.ts b/src/services/config.ts
@@ -5,4 +5,5 @@ export const config = {
   evalFramework: {
     baseUrl: process.env.EVAL_FRAMEWORK_URL ?? "http://localhost:3002",
   },
+  healthCheckTimeoutMs: 5_000,
 } as const;
diff --git a/src/services/health-check.ts b/src/services/health-check.ts
@@ -0,0 +1,44 @@
+import { HttpClient } from "./http-client.js";
+import { config } from "./config.js";
+import { extractError } from "../utils/responses.js";
+
+export interface HealthCheck {
+  name: string;
+  url: string;
+  healthy: boolean;
+  latencyMs: number;
+  error?: string;
+}
+
+export async function checkService(name: string, baseUrl: string): Promise<HealthCheck> {
+  const client = new HttpClient({ baseUrl, timeoutMs: config.healthCheckTimeoutMs });
+  const start = Date.now();
+
+  try {
+    const response = await client.get<unknown>("/health");
+    return {
+      name,
+      url: baseUrl,
+      healthy: response.ok,
+      latencyMs: Date.now() - start,
+      ...(!response.ok && { error: `HTTP ${response.status}` }),
+    };
+  } catch (error) {
+    return {
+      name,
+      url: baseUrl,
+      healthy: false,
+      latencyMs: Date.now() - start,
+      error: extractError(error),
+    };
+  }
+}
+
+export async function checkAllServices(): Promise<{ checks: HealthCheck[]; allHealthy: boolean }> {
+  const checks = await Promise.all([
+    checkService("Semantic Search API", config.semanticSearch.baseUrl),
+    checkService("Eval Framework", config.evalFramework.baseUrl),
+  ]);
+
+  return { checks, allHealthy: checks.every((c) => c.healthy) };
+}
diff --git a/src/tools/get-prompt.ts b/src/tools/get-prompt.ts
@@ -1,6 +1,7 @@
 import { z } from "zod/v4";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { getPromptByName } from "../services/prompt-registry.js";
+import { textContent, errorResponse } from "../utils/responses.js";
 
 export function registerGetPromptTool(server: McpServer): void {
   server.tool(
@@ -23,21 +24,11 @@ export function registerGetPromptTool(server: McpServer): void {
       const prompt = getPromptByName(name);
 
       if (!prompt) {
-        return {
-          isError: true,
-          content: [
-            {
-              type: "text" as const,
-              text: `Prompt "${name}" not found. Use toad_list_prompts to see available prompts.`,
-            },
-          ],
-        };
+        return errorResponse(`Prompt "${name}" not found. Use toad_list_prompts to see available prompts.`);
       }
 
       if (response_format === "json") {
-        return {
-          content: [{ type: "text" as const, text: JSON.stringify(prompt, null, 2) }],
-        };
+        return textContent(JSON.stringify(prompt, null, 2));
       }
 
       const scoreHistory = prompt.scoreHistory.length
@@ -61,9 +52,7 @@ export function registerGetPromptTool(server: McpServer): void {
         scoreHistory,
       ];
 
-      return {
-        content: [{ type: "text" as const, text: lines.join("\n") }],
-      };
+      return textContent(lines.join("\n"));
     },
   );
 }
diff --git a/src/tools/list-prompts.ts b/src/tools/list-prompts.ts
@@ -1,6 +1,7 @@
 import { z } from "zod/v4";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { getPrompts } from "../services/prompt-registry.js";
+import { textContent } from "../utils/responses.js";
 
 export function registerListPromptsTool(server: McpServer): void {
   server.tool(
@@ -29,14 +30,7 @@ export function registerListPromptsTool(server: McpServer): void {
       const hasMore = offset + limit < total;
 
       if (response_format === "json") {
-        return {
-          content: [
-            {
-              type: "text" as const,
-              text: JSON.stringify({ prompts: page, total, offset, limit, has_more: hasMore }, null, 2),
-            },
-          ],
-        };
+        return textContent(JSON.stringify({ prompts: page, total, offset, limit, has_more: hasMore }, null, 2));
       }
 
       const lines = [
@@ -50,9 +44,7 @@ export function registerListPromptsTool(server: McpServer): void {
         hasMore ? `_More results available. Use offset=${offset + limit} to continue._` : "_End of list._",
       ];
 
-      return {
-        content: [{ type: "text" as const, text: lines.join("\n") }],
-      };
+      return textContent(lines.join("\n"));
     },
   );
 }
diff --git a/src/tools/run-eval.ts b/src/tools/run-eval.ts
@@ -2,6 +2,7 @@ import { z } from "zod/v4";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { HttpClient } from "../services/http-client.js";
 import { config } from "../services/config.js";
+import { textContent, errorResponse, extractError } from "../utils/responses.js";
 
 interface EvalResult {
   suite: string;
@@ -36,21 +37,12 @@ export function registerRunEvalTool(server: McpServer): void {
     },
     async ({ suite, variant }) => {
       try {
-        const response = await httpClient.post<EvalResult>("/api/eval/run", {
-          suite,
-          variant,
-        });
+        const response = await httpClient.post<EvalResult>("/api/eval/run", { suite, variant });
 
         if (!response.ok) {
-          return {
-            isError: true,
-            content: [
-              {
-                type: "text" as const,
-                text: `Eval Framework returned ${response.status}. Ensure the service is running at ${config.evalFramework.baseUrl}`,
-              },
-            ],
-          };
+          return errorResponse(
+            `Eval Framework returned ${response.status}. Ensure the service is running at ${config.evalFramework.baseUrl}`,
+          );
         }
 
         const { score, passed, failed, total, details } = response.data;
@@ -68,20 +60,11 @@ export function registerRunEvalTool(server: McpServer): void {
           ),
         ].join("\n");
 
-        return {
-          content: [{ type: "text" as const, text: summary }],
-        };
+        return textContent(summary);
       } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return {
-          isError: true,
-          content: [
-            {
-              type: "text" as const,
-              text: `Failed to reach Eval Framework at ${config.evalFramework.baseUrl}: ${message}`,
-            },
-          ],
-        };
+        return errorResponse(
+          `Failed to reach Eval Framework at ${config.evalFramework.baseUrl}: ${extractError(error)}`,
+        );
       }
     },
   );
diff --git a/src/tools/search-documents.ts b/src/tools/search-documents.ts
@@ -2,6 +2,7 @@ import { z } from "zod/v4";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { HttpClient } from "../services/http-client.js";
 import { config } from "../services/config.js";
+import { textContent, errorResponse, extractError } from "../utils/responses.js";
 
 interface SearchResult {
   id: string;
@@ -33,21 +34,12 @@ export function registerSearchDocumentsTool(server: McpServer): void {
     },
     async ({ query, limit }) => {
       try {
-        const response = await httpClient.post<SearchResponse>("/api/search", {
-          query,
-          limit,
-        });
+        const response = await httpClient.post<SearchResponse>("/api/search", { query, limit });
 
         if (!response.ok) {
-          return {
-            isError: true,
-            content: [
-              {
-                type: "text" as const,
-                text: `Semantic Search API returned ${response.status}. Ensure the service is running at ${config.semanticSearch.baseUrl}`,
-              },
-            ],
-          };
+          return errorResponse(
+            `Semantic Search API returned ${response.status}. Ensure the service is running at ${config.semanticSearch.baseUrl}`,
+          );
         }
 
         const { results, total } = response.data;
@@ -59,25 +51,11 @@ export function registerSearchDocumentsTool(server: McpServer): void {
           )
           .join("\n\n---\n\n");
 
-        return {
-          content: [
-            {
-              type: "text" as const,
-              text: `Found ${total} results for "${query}" (showing ${results.length}):\n\n${formatted}`,
-            },
-          ],
-        };
+        return textContent(`Found ${total} results for "${query}" (showing ${results.length}):\n\n${formatted}`);
       } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return {
-          isError: true,
-          content: [
-            {
-              type: "text" as const,
-              text: `Failed to reach Semantic Search API at ${config.semanticSearch.baseUrl}: ${message}`,
-            },
-          ],
-        };
+        return errorResponse(
+          `Failed to reach Semantic Search API at ${config.semanticSearch.baseUrl}: ${extractError(error)}`,
+        );
       }
     },
   );
diff --git a/src/tools/system-status.ts b/src/tools/system-status.ts
diff --git a/src/utils/responses.ts b/src/utils/responses.ts
