@createsomething/ground-mcp 0.2.1 → 0.2.3

package/README.md

@@ -26,16 +26,65 @@ Ground is an MCP server that:
 
 ---
 
-## Quick Install
+## Installation
+
+Pick your tool. We've tested these so you don't have to discover config file locations through trial and error.
+
+### Claude Code (CLI)
+
+This is the one everyone gets wrong. Claude Code doesn't read `.claude/mcp.json`. It reads `~/.claude.json` for user-scoped servers and `.mcp.json` at project root for project-scoped servers. Two different files. Two different places. Now you know.
+
+**Option A: User scope (available everywhere)**
+
+```bash
+npm install @createsomething/ground-mcp
+claude mcp add --scope user --transport stdio ground -- npx @createsomething/ground-mcp
+```
+
+Restart Claude Code, run `/mcp`, and you should see "ground" connected.
+
+**Option B: Project scope (shared with team)**
+
+Create `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "ground": {
+      "command": "npx",
+      "args": ["@createsomething/ground-mcp"]
+    }
+  }
+}
+```
+
+Claude Code will prompt you to approve it on first use.
 
 ### Cursor (One-Click)
 
 [**Install in Cursor →**](cursor://anysphere.cursor-deeplink/mcp/install?name=ground&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAY3JlYXRlc29tZXRoaW5nL2dyb3VuZC1tY3AiXX0%3D)
 
+Or add to `.mcp.json` at your project root:
+
+```json
+{
+  "mcpServers": {
+    "ground": {
+      "command": "npx",
+      "args": ["@createsomething/ground-mcp"]
+    }
+  }
+}
+```
+
 ### Claude Desktop
 
 Add to `claude_desktop_config.json`:
 
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
 ```json
 {
   "mcpServers": {
@@ -74,13 +123,13 @@ Settings → MCP → View raw config, add:
 codex mcp add ground --command "npx @createsomething/ground-mcp"
 ```
 
-### npm (Global Install)
+### Global Install (When npx Isn't Your Thing)
 
 ```bash
 npm install -g @createsomething/ground-mcp
 ```
 
-Then add to your tool's MCP config:
+Now `ground-mcp` is in your PATH. Use it in any config:
 
 ```json
 {
@@ -92,6 +141,43 @@ Then add to your tool's MCP config:
 }
 ```
 
+## Troubleshooting
+
+**"Server not showing up"**
+
+Run `/mcp` in your tool. If ground isn't listed, your config file is in the wrong place or has a typo. Claude Code in particular has... opinions about where configs live.
+
+**"Connection closed" or "Download failed: HTTP 404"**
+
+The npm package downloads a platform-specific binary on install. If that failed:
+
+```bash
+# Check if the binary exists
+ls node_modules/@createsomething/ground-mcp/bin/
+
+# Re-install
+npm install @createsomething/ground-mcp
+```
+
+**"No files analyzed" or "0 results"**
+
+Ground needs to know where your code is. For project-specific analysis, run it from your project directory, or pass `--workspace`:
+
+```json
+{
+  "mcpServers": {
+    "ground": {
+      "command": "npx",
+      "args": ["@createsomething/ground-mcp", "--workspace", "/path/to/your/project"]
+    }
+  }
+}
+```
+
+**CSS/HTML analysis shows "100% adoption" or "0 drift"**
+
+Ground's sweet spot is TypeScript/JavaScript projects with design tokens (CSS variables). If you're analyzing plain HTML with inline styles and no token system defined, there's nothing to measure drift against—it's a vacuous pass. For CSS-only linting, try Stylelint.
+
 ## Available Tools
 
 ### Core Analysis
@@ -134,6 +220,24 @@ Then add to your tool's MCP config:
 | `ground_diff` | Incremental analysis vs git baseline (only NEW issues) |
 | `ground_verify_fix` | Verify a fix was applied correctly |
 
+## MCP Apps (Interactive UIs)
+
+Ground supports the [MCP Apps extension](https://modelcontextprotocol.io/docs/concepts/apps) for interactive visualization directly in the conversation.
+
+### Duplicate Explorer UI
+
+When you call duplicate analysis tools (`ground_find_duplicate_functions`, `ground_compare`, `ground_suggest_fix`), supported MCP clients can render an interactive duplicate explorer:
+
+- Visual similarity scores with color-coded badges
+- Expandable cards showing side-by-side file comparison
+- Adjustable similarity threshold slider
+- One-click compare and suggest fix actions
+- Real-time filtering and search
+
+**Supported Clients**: Claude.ai, VS Code (Insiders), ChatGPT, Goose
+
+The UI is served via `ui://ground/duplicate-explorer` resource and communicates with the server via postMessage.
+
 ### Design System Analysis (v2.1)
 
 | Tool | What it does |
@@ -168,7 +272,12 @@ What's the CSS token adoption ratio in packages/components?
 Find design drift in my CSS files only (use extensions: "css")
 ```
 
-## What's New in 0.2.1
+## What's New in 0.2.2
+
+- **Fixed npm installer** — Binary downloads now work correctly across all platforms
+- **Improved documentation** — Claude Code setup instructions (because nobody should have to discover `~/.claude.json` vs `.mcp.json` the hard way)
+
+### 0.2.1
 
 - **`ground_explain`** — AI-native context traceability. Explains why files are excluded from violation checks (e.g., video-rendering contexts, third-party CSS)
 - **`ground_find_drift` extensions filter** — Analyze specific file types (e.g., `extensions: "css"` for CSS-only analysis)

package/install.js

@@ -46,8 +46,8 @@ function getBinaryName() {
 
 function getDownloadUrl(binaryName) {
   const ext = process.platform === 'win32' ? 'zip' : 'tar.gz';
-  // Tag format: ground-v0.1.0
-  return `https://github.com/${REPO}/releases/download/ground-v${VERSION}/ground-${binaryName}.${ext}`;
+  // Tag format: v0.2.0
+  return `https://github.com/${REPO}/releases/download/v${VERSION}/ground-${binaryName}.${ext}`;
 }
 
 async function download(url) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@createsomething/ground-mcp",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Grounded claims for code. MCP server that prevents AI hallucination in code analysis.",
   "author": "CREATE SOMETHING <hello@createsomething.io>",
   "license": "MIT",