@ehrocks/fe-mcp-server 1.0.6 → 1.0.8

package/README.md

@@ -22,7 +22,7 @@ An MCP server for searching Hero Design System components.
 ## Troubleshooting
 - MCP connection gets `Client closed` error: *Ensure that Node.js is accessible globally.* Example: If you're using `asdf`, you can set the default Node.js version with:
 ```
-asdf set -u nodejs 20.19.0
+asdf set -u nodejs 22.22.0
 ```
 - Connect error or timeout: Because our MCP service is deployed to Employment Hero staging cluster, ensure you have the connection via VPN. [Read more](https://employmenthero.atlassian.net/wiki/spaces/PLAT/pages/1648525859/VPN+-+Internal+services+and+sandbox+accessibility)
 

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 export interface TextContent {
     [key: string]: unknown;
-    type: 'text';
+    type: "text";
     text: string;
 }
 export interface HeroDesignComponentExample {
@@ -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

@@ -1,120 +1,144 @@
 #!/usr/bin/env node
+import { createRequire } from "node:module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-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 require = createRequire(import.meta.url);
+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";
+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}`);
         }
-        const examples = await response.json();
-        if (!examples.length) {
-            return [{
-                    type: 'text',
-                    text: "I couldn't find any relevant component examples for your query."
-                }];
+        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 [{
-                type: 'text',
-                text: 'Here are the most relevant component examples I found:\n' + responseParts.join('\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 {
+        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: "1.0.0"
+    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", `Search for React component examples from the Hero Design System using semantic search.
+    server.tool("search_hero_design_component_examples", `Retrieve Hero Design System examples, patterns, and references using natural language.
 
-This tool performs semantic search across multiple specialized collections to find the most relevant component examples based on your query. The search covers:
+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.
 
-1. Full Component Information: Searches across complete component documentation including names, descriptions, and examples
-2. Code Examples: Specifically searches through code implementations and syntax
-3. Component Descriptions: Focuses on component usage descriptions and explanations
-4. Purpose & Use Cases: Matches queries about component purposes and intended use cases
-5. Technical Details: Searches through technical implementation details and specifications
-6. Props & Configuration: Finds examples based on prop usage and configuration options
-7. Design Patterns: Matches React patterns and best practices demonstrated in examples
-8. Use Case Scenarios: Searches through real-world application scenarios
+Common queries: button loading state, form validation error, dropdown with search, empty state, date picker range, modal confirmation dialog, toast notification.
 
-You can use this tool to:
-- Find examples of specific components (e.g., "Button with icon")
-- Search for implementation patterns (e.g., "how to handle form validation")
-- Look up prop usage (e.g., "Button with custom colors")
-- Find examples of specific features (e.g., "dropdown with search")
-- Search for specific use cases (e.g., "loading state in forms")
-- Find technical implementations (e.g., "async data loading pattern")
-
-The tool will return the most relevant examples, including:
-- Component name and description
-- Example code with explanations
-- Technical details and implementation notes
-- Purpose and use case descriptions
-- Props and configuration details
-- Design patterns and best practices`, {
+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()
+            .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 => {
+            .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 => {
+            .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.6",
+  "version": "1.0.8",
   "description": "MCP server for searching Hero Design System components",
   "type": "module",
   "main": "dist/index.js",