@ehrocks/fe-mcp-server 1.0.7 → 1.0.8

package/dist/index.d.ts

@@ -18,4 +18,10 @@ export interface HeroDesignComponentExample {
     similarity_score: number;
     matched_embedding_type: string;
 }
-export declare const searchHeroDesignComponentExamples: (query: string, limit?: number, threshold?: number) => Promise<TextContent[]>;
+export declare const searchHeroDesignComponentExamples: (query: string, limit?: number, threshold?: number) => Promise<{
+    ok: true;
+    content: TextContent[];
+} | {
+    ok: false;
+    message: string;
+}>;

package/dist/index.js

@@ -8,62 +8,84 @@ const { version } = require("../package.json");
 const HERO_DESIGN_COMPONENT_EXAMPLES_HOST = process.env.ENVIRONMENT === "LOCAL"
     ? "http://localhost:8000"
     : "https://fe-mcp-service.staging.ehrocks.com";
-export const searchHeroDesignComponentExamples = async (query, limit = 5, threshold = 0.4) => {
-    try {
-        const response = await fetch(`${HERO_DESIGN_COMPONENT_EXAMPLES_HOST}/retrieve_hero_design`, {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-            },
-            body: JSON.stringify({ query, limit, threshold }),
-        });
-        if (!response.ok) {
-            throw new Error(`HTTP error status: ${response.status}`);
-        }
-        const examples = await response.json();
-        if (!examples.length) {
-            return [
+const TIMEOUT_MS = 15000;
+const IS_LOCAL = process.env.ENVIRONMENT === "LOCAL";
+const CONNECTION_ERROR = IS_LOCAL
+    ? "fe-mcp-service is unreachable. Is the local service running?"
+    : "fe-mcp-service is unreachable. VPN connection is required.";
+const TIMEOUT_ERROR = IS_LOCAL
+    ? "fe-mcp-service timed out. Is the local service running?"
+    : "fe-mcp-service timed out. Check VPN. If already connected, the service may be degraded — retry.";
+const classifyError = (err) => {
+    if (err instanceof Error && err.name === "TimeoutError")
+        return TIMEOUT_ERROR;
+    if (err instanceof TypeError && err.message === "fetch failed")
+        return CONNECTION_ERROR;
+    return `An error occurred while processing your request: ${err}`;
+};
+const fetchWithTimeout = async (url, body) => {
+    const response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body,
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    if (!response.ok) {
+        throw new Error(`HTTP error status: ${response.status}`);
+    }
+    return response.json();
+};
+const buildContent = (examples) => {
+    if (!examples.length) {
+        return {
+            ok: true,
+            content: [
                 {
                     type: "text",
                     text: "I couldn't find any relevant component examples for your query.",
                 },
-            ];
+            ],
+        };
+    }
+    const responseParts = [];
+    examples.forEach((example, index) => {
+        responseParts.push(`\n${index + 1}. ${example.component_name} - ${example.example_name}`, `\nSimilarity Score: ${example.similarity_score.toFixed(2)}`, `\nComponent Description: ${example.component_description}`);
+        if (example.purpose_description) {
+            responseParts.push(`\nPurpose: ${example.purpose_description}`);
+        }
+        if (example.technical_description) {
+            responseParts.push(`\nTechnical Details: ${example.technical_description}`);
+        }
+        if (example.code) {
+            responseParts.push(`\nCode Example:\n\`\`\`jsx\n${example.code}\n\`\`\``);
         }
-        const responseParts = [];
-        examples.forEach((example, index) => {
-            responseParts.push(`\n${index + 1}. ${example.component_name} - ${example.example_name}`, `\nSimilarity Score: ${example.similarity_score.toFixed(2)}`, `\nComponent Description: ${example.component_description}`);
-            if (example.purpose_description) {
-                responseParts.push(`\nPurpose: ${example.purpose_description}`);
-            }
-            if (example.technical_description) {
-                responseParts.push(`\nTechnical Details: ${example.technical_description}`);
-            }
-            if (example.code) {
-                responseParts.push(`\nCode Example:\n\`\`\`jsx\n${example.code}\n\`\`\``);
-            }
-            if (example.props_description) {
-                responseParts.push(`\nProps Description: ${example.props_description}`);
-            }
-            if (example.matched_embedding_type) {
-                responseParts.push(`\nMatched Embedding Type: ${example.matched_embedding_type}`);
-            }
-            responseParts.push("\n" + "=".repeat(80) + "\n");
-        });
-        return [
+        if (example.props_description) {
+            responseParts.push(`\nProps Description: ${example.props_description}`);
+        }
+        if (example.matched_embedding_type) {
+            responseParts.push(`\nMatched Embedding Type: ${example.matched_embedding_type}`);
+        }
+        responseParts.push("\n" + "=".repeat(80) + "\n");
+    });
+    return {
+        ok: true,
+        content: [
             {
                 type: "text",
                 text: "Here are the most relevant component examples I found:\n" +
                     responseParts.join("\n"),
             },
-        ];
+        ],
+    };
+};
+export const searchHeroDesignComponentExamples = async (query, limit = 5, threshold = 0.4) => {
+    const url = `${HERO_DESIGN_COMPONENT_EXAMPLES_HOST}/retrieve_hero_design`;
+    const body = JSON.stringify({ query, limit, threshold });
+    try {
+        return buildContent(await fetchWithTimeout(url, body));
     }
-    catch (error) {
-        return [
-            {
-                type: "text",
-                text: `An error occurred while processing your request: ${error}`,
-            },
-        ];
+    catch (err) {
+        return { ok: false, message: classifyError(err) };
     }
 };
 async function startServer() {
@@ -83,32 +105,40 @@ Returns for each match:
 - Technical details, design patterns, and props context when available`, {
         query: z
             .string()
+            .trim()
+            .min(1, "query must not be empty")
             .describe("The search query describing what you're looking for in the component examples. Be specific about what aspects you're interested in (code, usage, props, patterns, etc.)"),
         limit: z
             .string()
             .transform((val) => {
             const num = Number(val);
-            if (isNaN(num) || num <= 0)
+            if (isNaN(num))
                 return 5;
-            return num;
+            return Math.min(Math.max(Math.round(num), 1), 5);
         })
             .optional()
             .default("5")
-            .describe("Maximum number of distinct component examples to return"),
+            .describe("Maximum number of distinct component examples to return (1–5)"),
         threshold: z
             .string()
             .transform((val) => {
             const num = parseFloat(val);
-            if (isNaN(num) || num <= 0)
+            if (isNaN(num))
                 return 0.4;
-            return num;
+            return Math.min(Math.max(num, 0), 0.99);
         })
             .optional()
             .default("0.4")
-            .describe("Minimum similarity score (0.0 to 1.0) for returned examples. Lower values return more results but might be less relevant"),
+            .describe("Minimum similarity score (0.0 to 0.99) for returned examples. Lower values return more results but might be less relevant"),
     }, async ({ query, limit, threshold }) => {
-        const content = await searchHeroDesignComponentExamples(query, limit, threshold);
-        return { content };
+        const result = await searchHeroDesignComponentExamples(query, limit, threshold);
+        if (result.ok) {
+            return { content: result.content };
+        }
+        return {
+            content: [{ type: "text", text: result.message }],
+            isError: true,
+        };
     });
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ehrocks/fe-mcp-server",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "MCP server for searching Hero Design System components",
   "type": "module",
   "main": "dist/index.js",