@createsomething/ground-mcp 0.2.3 → 0.3.0

package/README.md

@@ -3,10 +3,52 @@
 [![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.
+**Grounded claims for code.** An MCP server that prevents AI hallucination in code analysis.
+
+Works with Claude Code, Cursor, Windsurf, VS Code Copilot, Claude Desktop, and any MCP-compatible AI coding assistant.
 
 **[View Landing Page →](https://createsomething.agency/products/ground)**
 
+## Why Ground?
+
+| Capability | Without Ground | With Ground |
+|------------|---------------|-------------|
+| Duplicate detection | "These look 95% similar" | Computed 87.3% similarity via AST + token analysis |
+| Dead code claims | "This appears unused" | Verified: 0 imports, 0 type references |
+| Orphan detection | "Nothing imports this" | Checked: not a Worker entry point, not framework-implicit |
+| Design drift | "Colors look hardcoded" | Adoption ratio: 73% tokens, 27% violations |
+
+**The difference**: Ground requires computation before claims. No hallucinated analysis.
+
+## Recommended agent path
+
+Use CTX and Ground for different evidence:
+
+- **CTX** retrieves the history of earlier agent work.
+- **Ground** computes facts about the code that is on disk now.
+
+For a current-source review, start with the compact verified loop:
+
+1. `ground_analyze` — get machine-readable findings for a directory.
+2. `ground_diff` — restrict the same checks to changes since a Git baseline.
+3. `ground_verify_fix` — confirm the specific reported issue is gone.
+4. `ground_explain` — inspect why Ground included, excluded, or scored a result.
+
+The MCP server also retains targeted and graph tools for deeper investigations.
+The installed CLI exposes the same batch and Git-aware entry points:
+
+```bash
+ground analyze ./src --checks duplicates,dead_exports
+ground diff ./src --base origin/main --checks duplicates
+```
+
+Both commands print JSON evidence. `ground diff` only returns files inside the
+requested directory and resolves Git paths from the repository root, so it is
+safe to run from a package inside a monorepo.
+
+The release package includes the native Apple Silicon binaries directly; other
+supported platforms download the matching verified release asset during install.
+
 ## The Problem
 
 AI agents are confident. Too confident.
@@ -23,6 +65,7 @@ Ground is an MCP server that:
 - Finds duplicates, dead code, and orphaned modules
 - Requires verification before claims
 - Blocks hallucinated analysis
+- Provides confidence scores with evidence
 
 ---
 
@@ -303,6 +346,27 @@ Ground loads `.ground.yml` from your project root for:
 
 See [Full Documentation](https://github.com/createsomethingtoday/create-something-monorepo/tree/main/packages/ground) for configuration reference.
 
+## Native service pilot
+
+The CRE-1473 pilot keeps TypeScript as the control plane and invokes the existing Rust `ground-mcp` binary through a small, typed MCP adapter. It is a bounded proof for analysis workloads, not a production routing change or a broad language migration.
+
+The pilot owns four things:
+
+- `pilot/ground-native-client.ts` — discovers and calls `ground_analyze` over stdio MCP with explicit timeout and error behavior
+- `pilot/benchmark.ts` — captures repeated native samples plus a directional comparison with the existing TypeScript duplicate-analysis script
+- `pilot/ground-benchmark-receipt.schema.json` — makes the retained evidence machine-checkable
+- `pilot/validate-receipt.ts` — independently rejects incomplete, failed, or inconsistent receipts
+
+From the repository root, run:
+
+```bash
+pnpm --filter @createsomething/ground-mcp run pilot:verify
+```
+
+The benchmark defaults to `packages/mcp-core/src`, five retained samples, one warmup, and the release binary at `packages/ground/target/release/ground-mcp`. Metrics between the Rust MCP path and TypeScript script are directional only because the implementations do not use identical parsers or algorithms.
+
+Rollback is removal of the pilot adapter, benchmark, and package-local development scripts. No existing Ground command, npm installer path, Cloudflare surface, or production consumer is redirected by this pilot.
+
 ## Links
 
 - [Full Documentation](https://github.com/createsomethingtoday/create-something-monorepo/tree/main/packages/ground)
@@ -312,3 +376,13 @@ See [Full Documentation](https://github.com/createsomethingtoday/create-somethin
 ## License
 
 MIT
+
+---
+
+## Related
+
+Looking for task coordination? Use Linear with the CREATE SOMETHING `pnpm linear:*` wrappers for tracked work, ownership, status, and delivery evidence.
+
+## Keywords
+
+MCP server, Model Context Protocol, AI code analysis, static analysis, duplicate detection, dead code detection, orphan detection, code quality, hallucination prevention, LLM tools, Claude Code, Cursor IDE, Windsurf, VS Code Copilot, Anthropic Claude, AI coding assistant, Rust, TypeScript, JavaScript, monorepo analysis, design tokens, CSS analysis, code verification.

package/install.js

@@ -14,6 +14,8 @@ const zlib = require('zlib');
 
 const REPO = 'createsomethingtoday/create-something-monorepo';
 const VERSION = require('./package.json').version;
+const SKIP_INSTALL = process.env.GROUND_MCP_SKIP_BINARY_INSTALL === '1';
+const IS_SOURCE_TREE_INSTALL = fs.existsSync(path.resolve(__dirname, '../Cargo.toml'));
 
 // Platform mapping
 // Note: macOS Intel uses arm64 binary via Rosetta 2
@@ -44,10 +46,25 @@ function getBinaryName() {
   return name;
 }
 
-function getDownloadUrl(binaryName) {
-  const ext = process.platform === 'win32' ? 'zip' : 'tar.gz';
-  // Tag format: v0.2.0
-  return `https://github.com/${REPO}/releases/download/v${VERSION}/ground-${binaryName}.${ext}`;
+function getDownloadUrl(binaryName, platform = process.platform) {
+  const ext = platform === 'win32' ? 'zip' : 'tar.gz';
+  return `https://github.com/${REPO}/releases/download/ground-v${VERSION}/ground-${binaryName}.${ext}`;
+}
+
+function hasBundledNativeBinaries() {
+  // The npm artifact includes a release-built Apple Silicon bootstrap pair.
+  // Other platforms continue through the release-asset downloader below.
+  if (getPlatformKey() !== 'darwin-arm64') return false;
+
+  const binDir = path.join(__dirname, 'bin');
+  return ['ground', 'ground-mcp'].every((name) => {
+    const binary = path.join(binDir, name);
+    try {
+      return fs.statSync(binary).isFile() && (fs.statSync(binary).mode & 0o111) !== 0;
+    } catch {
+      return false;
+    }
+  });
 }
 
 async function download(url) {
@@ -92,6 +109,21 @@ async function extractZip(buffer, destDir) {
 }
 
 async function install() {
+  if (SKIP_INSTALL) {
+    console.log('Ground MCP: Skipping binary install because GROUND_MCP_SKIP_BINARY_INSTALL=1');
+    return;
+  }
+
+  if (IS_SOURCE_TREE_INSTALL) {
+    console.log('Ground MCP: Skipping binary install in source checkout');
+    return;
+  }
+
+  if (hasBundledNativeBinaries()) {
+    console.log('Ground MCP: Using bundled darwin-arm64 binaries');
+    return;
+  }
+
   console.log('Ground MCP: Installing binary...');
   
   const binaryName = getBinaryName();
@@ -166,5 +198,10 @@ async function install() {
   }
 }
 
-// Run installer
-install();
+if (require.main === module) {
+  install();
+}
+
+module.exports = {
+  getDownloadUrl,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@createsomething/ground-mcp",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Grounded claims for code. MCP server that prevents AI hallucination in code analysis.",
   "author": "CREATE SOMETHING <hello@createsomething.io>",
   "license": "MIT",
@@ -15,21 +15,57 @@
   },
   "keywords": [
     "mcp",
+    "mcp-server",
     "model-context-protocol",
     "ai",
+    "ai-coding",
+    "ai-agent",
     "code-analysis",
+    "static-analysis",
     "duplicate-detection",
     "dead-code",
+    "dead-code-detection",
+    "orphan-detection",
+    "code-quality",
+    "hallucination-prevention",
     "grounding",
+    "verification",
     "llm",
+    "llm-tools",
     "claude",
-    "cursor"
+    "claude-code",
+    "cursor",
+    "windsurf",
+    "copilot",
+    "codex",
+    "anthropic",
+    "openai",
+    "rust",
+    "typescript",
+    "javascript",
+    "monorepo",
+    "design-tokens",
+    "css-analysis"
   ],
   "bin": {
+    "ground": "bin/ground",
     "ground-mcp": "bin/ground-mcp"
   },
   "scripts": {
-    "postinstall": "node install.js"
+    "postinstall": "node install.js",
+    "pilot:build": "cargo build --release --manifest-path ../Cargo.toml --bin ground --bin ground-mcp",
+    "pilot:benchmark": "tsx pilot/benchmark.ts",
+    "pilot:check": "tsc --noEmit -p pilot/tsconfig.json",
+    "pilot:receipt:validate": "tsx pilot/validate-receipt.ts",
+    "pilot:test": "pnpm run pilot:build && tsx --test pilot/*.test.ts",
+    "pilot:verify": "pnpm run pilot:check && pnpm run pilot:test && pnpm run pilot:benchmark && pnpm run pilot:receipt:validate -- pilot/evidence/ground-native-benchmark-receipt.v1.json"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "@types/node": "^24.10.9",
+    "ajv": "^8.17.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
   },
   "files": [
     "bin",