@ehrocks/fe-mcp-server 1.0.7 → 1.0.9

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,69 +8,92 @@ 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() {
     const server = new McpServer({ name: "hero-design-mcp-server", version }, {
         instructions: "Invoke for any @hero-design/react implementation task: selecting the right component for a UI need, retrieving JSX code examples, or exploring design patterns and design system resources.",
     });
-    server.tool("search_hero_design_component_examples", `Retrieve Hero Design System examples, patterns, and references using natural language.
+    server.registerTool("search_hero_design_component_examples", {
+        description: `Retrieve Hero Design System examples, patterns, and references using natural language.
 
 Describe the UI behavior, component, or pattern you need. Covers component selection guidance, JSX code examples, design patterns, and use cases across @hero-design/react. Not a prop API reference — use the component library docs for precise prop signatures.
 
@@ -80,35 +103,52 @@ Returns for each match:
 - Component name and similarity score
 - Component and example descriptions
 - Code example (JSX)
-- Technical details, design patterns, and props context when available`, {
-        query: z
-            .string()
-            .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)
-                return 5;
-            return num;
-        })
-            .optional()
-            .default("5")
-            .describe("Maximum number of distinct component examples to return"),
-        threshold: z
-            .string()
-            .transform((val) => {
-            const num = parseFloat(val);
-            if (isNaN(num) || num <= 0)
-                return 0.4;
-            return num;
-        })
-            .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"),
+- Technical details, design patterns, and props context when available`,
+        inputSchema: {
+            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))
+                    return 5;
+                return Math.min(Math.max(Math.round(num), 1), 5);
+            })
+                .optional()
+                .default("5")
+                .describe("Maximum number of distinct component examples to return (1–5)"),
+            threshold: z
+                .string()
+                .transform((val) => {
+                const num = parseFloat(val);
+                if (isNaN(num))
+                    return 0.4;
+                return Math.min(Math.max(num, 0), 0.99);
+            })
+                .optional()
+                .default("0.4")
+                .describe("Minimum similarity score (0.0 to 0.99) for returned examples. Lower values return more results but might be less relevant"),
+        },
+        annotations: {
+            title: "Search Hero Design Component Examples",
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
     }, 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.9",
   "description": "MCP server for searching Hero Design System components",
   "type": "module",
   "main": "dist/index.js",
@@ -23,7 +23,8 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.9.0"
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.0"
   },
   "devDependencies": {
     "@types/node": "^22.14.1",