@ehrocks/fe-mcp-server 1.0.3

package/README.md

@@ -0,0 +1,32 @@
+# Frontend MCP Server
+
+An MCP server for searching Hero Design System components.
+
+## Installation
+
+- Ensure you have configured `EH_GITHUB_PKG_TOKEN` to read the internal npm package. [Read more](https://employmenthero.atlassian.net/wiki/spaces/WEBPLATFORM/pages/3314778914/PRD+Experimental+migrating+private+package+hosting+to+Github+Packages#Prerequisite)
+- Update mcp config from Cursor, e.g. on macOS `~/.cursor/mcp.json`
+```
+{
+  "mcpServers": {
+    "fe-mcp-service": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "--@thinkei:registry=https://npm.pkg.github.com",
+        "--//npm.pkg.github.com/:_authToken=${EH_GITHUB_PKG_TOKEN}",
+        "@thinkei/fe-mcp-server"
+      ]
+    }
+  }
+}
+```
+
+## 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
+```
+- 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)
+
+For more detailed troubleshooting, please refer to the [full guide](https://employmenthero.atlassian.net/wiki/spaces/WEBPLATFORM/pages/3597567386/Hero+Design+MCP+Trouble+Shooting).

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+export interface TextContent {
+    [key: string]: unknown;
+    type: 'text';
+    text: string;
+}
+export interface HeroDesignComponentExample {
+    component_name: string;
+    component_description: string;
+    example_name: string;
+    example_description: string;
+    code: string;
+    purpose_description?: string;
+    technical_description?: string;
+    props_description?: string;
+    patterns_description?: string;
+    use_cases_description?: string;
+    similarity_score: number;
+    matched_embedding_type: string;
+}
+export declare const searchHeroDesignComponentExamples: (query: string, limit?: number, threshold?: number) => Promise<TextContent[]>;

package/dist/index.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+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 === 'STG' ? 'https://fe-mcp-service.staging.ehrocks.com' : 'http://localhost:8000';
+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 [{
+                    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\`\`\``);
+            }
+            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')
+            }];
+    }
+    catch (error) {
+        return [{
+                type: 'text',
+                text: `An error occurred while processing your request: ${error}`
+            }];
+    }
+};
+async function startServer() {
+    const server = new McpServer({
+        name: "hero-design-mcp-server",
+        version: "1.0.0"
+    });
+    server.tool("search_hero_design_component_examples", `Search for React component examples from the Hero Design System using semantic search.
+
+This tool performs semantic search across multiple specialized collections to find the most relevant component examples based on your query. The search covers:
+
+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
+
+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`, {
+        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")
+    }, async ({ query, limit, threshold }) => {
+        const content = await searchHeroDesignComponentExamples(query, limit, threshold);
+        return { content };
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+// If we're being executed directly (not imported), start the server
+if (process.argv[1]) {
+    startServer().catch((error) => {
+        console.error("Failed to start server:", error);
+        process.exit(1);
+    });
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@ehrocks/fe-mcp-server",
+  "version": "1.0.3",
+  "description": "MCP server for searching Hero Design System components",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "hero-design",
+    "components",
+    "search"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.1",
+    "tsx": "^4.7.1",
+    "typescript": "^5.4.2"
+  },
+  "bin": {
+    "start-mcp-server": "dist/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thinkei/fe-mcp-service.git"
+  }
+}