elij-ui-library-mcp 0.3.1 → 1.0.0

package/README.md

@@ -1,20 +1,56 @@
 # Elij UI Library MCP
 
-An MCP server that lets AI clients discover components from the published Elij UI Library registry.
+An MCP server that lets AI clients discover components, props, categories, and Storybook stories from the published Elij UI Library registry.
+
+## What it does
+
+The server exposes three read-only tools:
+
+- `list_components` — list all components or filter by category
+- `search_components` — search names, categories, and descriptions
+- `get_component` — inspect one component's metadata and props
+
+It uses the MCP **stdio** transport. MCP messages stay on stdout and diagnostic logs are written to stderr.
 
 ## Quick start
 
-Run it without installing globally:
+Run the latest published version without installing globally:
 
 ```bash
 npx -y elij-ui-library-mcp
 ```
 
-The server uses the MCP stdio transport. Keep stdout reserved for MCP messages; diagnostic output is written to stderr.
+For a reproducible setup, pin a version instead:
+
+```bash
+npx -y elij-ui-library-mcp@1.0.0
+```
+
+The unpinned command is convenient for trying the latest release. Pinning is recommended for production or shared team configuration.
 
-## MCP client configuration
+## Configure an MCP Host
 
-Add the following server entry to an MCP-compatible client such as Claude Desktop, Cursor, or VS Code:
+### VS Code
+
+Create or open `.vscode/mcp.json` in your workspace and add:
+
+```json
+{
+  "servers": {
+    "elijUiLibrary": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "elij-ui-library-mcp"]
+    }
+  }
+}
+```
+
+You can replace the package argument with `elij-ui-library-mcp@1.0.0` when you need a fixed version. After saving, run `MCP: List Servers` from the Command Palette and start `elijUiLibrary`.
+
+### Claude Desktop and Cursor
+
+Add this entry to the client's MCP configuration:
 
 ```json
 {
@@ -27,27 +63,135 @@ Add the following server entry to an MCP-compatible client such as Claude Deskto
 }
 ```
 
-If the client supports a local executable configuration, the equivalent command is:
+Restart the client after saving the configuration. If the client supports a local executable, the equivalent command is:
 
 ```bash
 elij-ui-library-mcp
 ```
 
-## Available tools
+## Verify the connection
+
+After starting the server, confirm that the Host discovers these tools:
+
+```text
+list_components
+search_components
+get_component
+```
+
+Then try these prompts in the Host chat:
+
+```text
+List all available Elij UI components.
+```
+
+```text
+Find components suitable for a pricing card.
+```
+
+```text
+Show me the props and Storybook story for EventCarousel.
+```
+
+```text
+Search for components related to WhatsApp contact buttons.
+```
+
+## Tool examples
 
 ### `list_components`
 
-Lists all components in the registry. Pass an optional `category` to filter the result.
+Use it to browse the registry:
+
+```text
+List components in the content category.
+```
+
+Optional input:
+
+```json
+{ "category": "content" }
+```
 
 ### `search_components`
 
-Searches component names, categories, and descriptions. It accepts `query`, an optional `category`, and an optional `limit` from 1 to 50.
+Use it to find a component by concept:
+
+```text
+Search for a component that supports event image carousels.
+```
+
+Inputs include `query`, optional `category`, and `limit` from 1 to 50:
+
+```json
+{
+  "query": "carousel",
+  "category": "content",
+  "limit": 10
+}
+```
 
 ### `get_component`
 
-Returns the import path, category, description, props, and Storybook story for a component by name.
+Use it when you need implementation details:
+
+```text
+Get the import path, props, and Storybook story for WhatsAppButton.
+```
+
+Input:
+
+```json
+{ "name": "WhatsAppButton" }
+```
+
+If the component does not exist, the server returns an MCP error response instead of silently returning an empty result.
+
+## Example AI-assisted workflow
+
+```text
+1. Ask the Host to search for a suitable component.
+2. Ask for its props and Storybook story.
+3. Ask for an import example using the returned component name.
+4. Check the Storybook story before adding it to your application.
+```
+
+Example conversation:
+
+```text
+User: Find a component for a pricing card.
+AI: Card is suitable. I can show its props and Storybook story.
+
+User: Show the props and import example.
+AI: Import Card from "elij-ui-library" and use the returned props from the registry.
+```
+
+## Troubleshooting
+
+### Server not found
+
+Check that Node.js and npm are available:
+
+```bash
+node --version
+npm --version
+```
+
+Then test the package directly:
+
+```bash
+npx -y elij-ui-library-mcp
+```
+
+### No tools discovered
+
+Restart the MCP server from the Host, confirm the configuration uses `elij-ui-library-mcp` (not the CLI package), and inspect the Host's MCP output log.
+
+### Registry data is unavailable
+
+The MCP package reads registry metadata from the published `elij-ui-library` dependency. Check npm connectivity and make sure the dependency version is available in the configured registry.
 
-## Development
+### Local development
 
 From the monorepo root:
 
@@ -56,4 +200,4 @@ corepack yarn workspace elij-ui-library-mcp build
 corepack yarn workspace elij-ui-library-mcp test
 ```
 
-The server depends on the published `elij-ui-library` registry package, so the registry data remains versioned with the UI library release.
+The server is read-only and does not modify your application files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "elij-ui-library-mcp",
-  "version": "0.3.1",
+  "version": "1.0.0",
   "description": "MCP server for discovering Elij UI components",
   "type": "module",
   "bin": "./dist/index.js",
@@ -14,7 +14,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/server": "^2.0.0",
-    "elij-ui-library": "^0.3.1",
+    "elij-ui-library": "^1.0.0",
     "zod": "^4.2.0"
   },
   "devDependencies": {