@createsomething/ground-mcp 0.1.1 → 0.2.1

package/README.md

@@ -1,7 +1,12 @@
 # @createsomething/ground-mcp
 
+[![npm version](https://img.shields.io/npm/v/@createsomething/ground-mcp.svg)](https://www.npmjs.com/package/@createsomething/ground-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 Grounded claims for code. An MCP server that prevents AI hallucination in code analysis.
 
+**[View Landing Page →](https://createsomething.agency/products/ground)**
+
 ## The Problem
 
 AI agents are confident. Too confident.
@@ -19,15 +24,63 @@ Ground is an MCP server that:
 - Requires verification before claims
 - Blocks hallucinated analysis
 
-## Installation
+---
+
+## Quick Install
+
+### Cursor (One-Click)
+
+[**Install in Cursor →**](cursor://anysphere.cursor-deeplink/mcp/install?name=ground&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAY3JlYXRlc29tZXRoaW5nL2dyb3VuZC1tY3AiXX0%3D)
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ground": {
+      "command": "npx",
+      "args": ["@createsomething/ground-mcp"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+Settings → MCP → View raw config, add:
+
+```json
+{
+  "mcpServers": {
+    "ground": {
+      "command": "npx",
+      "args": ["@createsomething/ground-mcp"]
+    }
+  }
+}
+```
+
+### VS Code + Copilot
+
+1. Open Extensions panel
+2. Filter by "MCP Server"
+3. Search "ground"
+
+### Codex CLI
 
 ```bash
-npm install -g @createsomething/ground-mcp
+codex mcp add ground --command "npx @createsomething/ground-mcp"
 ```
 
-## MCP Configuration
+### npm (Global Install)
+
+```bash
+npm install -g @createsomething/ground-mcp
+```
 
-Add to `.cursor/mcp.json`:
+Then add to your tool's MCP config:
 
 ```json
 {
@@ -39,21 +92,57 @@ Add to `.cursor/mcp.json`:
 }
 ```
 
-Restart Cursor. Ground tools are now available.
-
 ## Available Tools
 
+### Core Analysis
+
+| Tool | What it does |
+|------|--------------|
+| `ground_compare` | Compare two files for similarity (0.0-1.0 score) |
+| `ground_count_uses` | Count symbol uses; distinguishes runtime vs type-only usages |
+| `ground_check_connections` | Check if module is connected (understands Cloudflare Workers) |
+| `ground_find_duplicate_functions` | Find duplicates across AND within files; supports monorepos |
+
+### Verified Claims (Audit Trail)
+
+| Tool | What it does |
+|------|--------------|
+| `ground_claim_dead_code` | Claim code is dead — **blocked** until you've counted uses |
+| `ground_claim_orphan` | Claim module is orphaned — **blocked** until you've checked connections |
+
+### Discovery Tools
+
 | Tool | What it does |
 |------|--------------|
-| `ground_compare` | Compare two files for similarity |
-| `ground_count_uses` | Count symbol uses (distinguishes definitions vs actual uses) |
-| `ground_check_connections` | Check if a module is connected (understands Workers) |
-| `ground_find_duplicate_functions` | Find copied functions across files |
 | `ground_find_orphans` | Find modules nothing imports |
 | `ground_find_dead_exports` | Find exports never imported elsewhere |
 | `ground_check_environment` | Detect Workers/Node.js API leakage |
-| `ground_analyze` | Batch analysis: duplicates + orphans + dead exports |
-| `ground_claim_*` | Make verified claims (requires checking first) |
+| `ground_suggest_fix` | Get suggestions for fixing duplications |
+
+### Graph-Based Analysis (Fast Repo-Wide Scans)
+
+| Tool | What it does |
+|------|--------------|
+| `ground_build_graph` | Build symbol graph for repo-wide analysis |
+| `ground_query_dead` | Query graph for dead exports (filters framework conventions) |
+
+### AI-Native Tools
+
+| Tool | What it does |
+|------|--------------|
+| `ground_analyze` | Batch analysis: duplicates + dead exports + orphans + environment |
+| `ground_diff` | Incremental analysis vs git baseline (only NEW issues) |
+| `ground_verify_fix` | Verify a fix was applied correctly |
+
+### Design System Analysis (v2.1)
+
+| Tool | What it does |
+|------|--------------|
+| `ground_find_drift` | Find design token violations (hardcoded colors, spacing, etc.) |
+| `ground_adoption_ratio` | Calculate token adoption percentage with health thresholds |
+| `ground_suggest_pattern` | Suggest tokens to replace hardcoded values |
+| `ground_mine_patterns` | Discover implicit patterns that should become tokens |
+| `ground_explain` | AI-native traceability — explain why files are excluded |
 
 ## Usage Examples
 
@@ -71,6 +160,20 @@ Check if the old-utils module is still connected to anything
 Run ground_analyze on packages/sdk to find dead code
 ```
 
+```
+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
+
+- **`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)
+- **Context system** — Configure intentional exclusions in `.ground.yml` with full audit trail
+
 ## Philosophy
 
 Ground is based on a simple principle: **no claim without evidence**.
@@ -81,6 +184,16 @@ Ground is based on a simple principle: **no claim without evidence**.
 
 This prevents AI hallucination by requiring computation before synthesis.
 
+## Configuration
+
+Ground loads `.ground.yml` from your project root for:
+- Ignore patterns (functions, files, directories)
+- Known drift exceptions with documented reasons
+- Context declarations for intentional exclusions
+- Similarity thresholds
+
+See [Full Documentation](https://github.com/createsomethingtoday/create-something-monorepo/tree/main/packages/ground) for configuration reference.
+
 ## Links
 
 - [Full Documentation](https://github.com/createsomethingtoday/create-something-monorepo/tree/main/packages/ground)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@createsomething/ground-mcp",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Grounded claims for code. MCP server that prevents AI hallucination in code analysis.",
   "author": "CREATE SOMETHING <hello@createsomething.io>",
   "license": "MIT",
@@ -26,8 +26,7 @@
     "cursor"
   ],
   "bin": {
-    "ground-mcp": "bin/ground-mcp",
-    "ground": "bin/ground"
+    "ground-mcp": "bin/ground-mcp"
   },
   "scripts": {
     "postinstall": "node install.js"