@dropins/mcp 0.1.0 → 0.3.0

package/README.md

@@ -6,13 +6,7 @@ MCP server that gives AI assistants deep knowledge of Adobe Commerce drop-in com
 
 ## Getting started
 
-### 1. Install
-
-```bash
-npm install -g @dropins/mcp
-```
-
-### 2. Configure your IDE
+### 1. Configure your IDE
 
 The MCP server runs automatically — your IDE spawns the process when needed. The AI passes your project path directly when calling tools that need it.
 
@@ -49,19 +43,30 @@ Add to `.vscode/mcp.json` in your project:
 
 #### Claude Desktop
 
-Add to `claude_desktop_config.json`:
+Claude Desktop spawns processes without the shell's PATH, so `npx` may not resolve. Use the installed binary directly instead:
+
+```bash
+npm install -g @dropins/mcp
+```
+
+Then add to `claude_desktop_config.json`:
 
 ```json
 {
   "mcpServers": {
     "dropins": {
-      "command": "npx",
-      "args": ["@dropins/mcp"]
+      "command": "dropins-mcp"
     }
   }
 }
 ```
 
+If you use `nvm`, replace `dropins-mcp` with the full path to the binary. Run `node --version` to find your version (for example `v22.14.0`):
+
+```text
+~/.nvm/versions/node/<version>/bin/dropins-mcp
+```
+
 #### Codex
 
 Add this to `~/.codex/config.toml`:
@@ -72,7 +77,7 @@ command = "npx"
 args = ["@dropins/mcp"]
 ```
 
-### 3. (Optional) Enable AI-powered documentation search
+### 2. (Optional) Enable AI-powered documentation search
 
 For enhanced semantic search across Adobe Commerce documentation, install the aio CLI:
 
@@ -83,12 +88,20 @@ aio auth login
 
 This enables the `search_commerce_docs` tool. Without aio CLI, the MCP works fully — local documentation snapshots are always available via `search_docs`.
 
-### 4. Verify
+### 3. Verify
 
 Restart your IDE. The dropins MCP should appear with 20 tools and resources enabled. Try a prompt like _"What slots does the CartSummaryList container have?"_ to confirm it works.
 
+If the server does not appear, open your IDE's MCP logs and confirm that `npx @dropins/mcp` runs without errors in a terminal outside the IDE.
+
 > **Note:** You do not need to clone any drop-in repositories. The knowledge base (registry, docs, examples) is pre-generated and committed to this repo. CI validates it on every push.
 
+### Troubleshooting: npx timeout on first run
+
+The first time `npx @dropins/mcp` runs it downloads the package, which can take several seconds. Some IDEs have a short MCP startup timeout and report a connection failure before the download completes.
+
+To avoid this, install globally first and use the binary directly (see Claude Desktop config above). For other IDEs using `npx`, after the first run the package is cached locally and subsequent startups are fast.
+
 ## Tools
 
 | Tool                          | Description                                             |
@@ -226,41 +239,6 @@ In partial mode, only the targeted drop-in repos are branch/version checked, and
 
 Block patterns and SDK package metadata (event-bus, fetch-graphql, etc.) are manually curated in `registry/sdk.json`. Elsie component props, slots, and exported types are auto-generated from StorefrontSDK source. Everything else is auto-generated by `yarn generate`.
 
-### Usage analytics
-
-The MCP server automatically logs every tool call to `.telemetry/usage.jsonl` (inside the MCP repo, gitignored) with timing, parameters, and result metadata.
-
-Run `yarn stats` to view usage patterns:
-
-- Tool call frequency and empty result rates (identifies knowledge gaps)
-- Most queried drop-ins (shows developer interest)
-- Failed search queries (actionable improvement list)
-- Response times and error rates per tool
-
-Example output:
-
-```text
-=== Dropins MCP Usage Stats ===
-Period: last 30 days (247 total calls, 12% empty)
-
-Top tools
-  Tool                   Calls  Empty%  Errors  Avg ms
-  ──────────────────────────────────────────────────────────
-  list_slots                61      2%       0      11
-  search_docs               39     21%       0      34  ← knowledge gap
-  list_graphql_queries      48      4%       0      18
-
-Top empty-result queries (fix these)
-    8x  "reCAPTCHA setup"
-    5x  "B2B quote workflow"
-```
-
-Entries older than 90 days are automatically cleaned up on each run. Use `yarn stats --days 30` to narrow the window. The log file persists across MCP restarts and different projects.
-
-For a visual dashboard with interactive charts, run `yarn dashboard`. This opens a React Spectrum app showing usage over time, tool breakdown, empty result queries, and dropin interest trends.
-
-**Sharing feedback:** Consider sharing your `yarn stats` output with the MCP development team to help prioritize improvements and identify common knowledge gaps.
-
 ### When to regenerate
 
 The knowledge base should be regenerated after every official drop-in release that includes stable versions. This ensures the MCP reflects the latest containers, slots, events, API functions, and documentation available to merchants. Make sure all local drop-in clones are on their default branch and up to date before running `yarn generate`.

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dropins/mcp",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "MCP server for Adobe Commerce Storefront Dropins — provides AI assistants with deep knowledge of blocks, slots, extensions, events, and design tokens",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "Adobe Commerce Storefront Team",
   "type": "module",
   "bin": {
-    "mcp-server-dropins": "dist/index.js"
+    "dropins-mcp": "dist/index.js"
   },
   "engines": {
     "node": ">=18.0.0"