@createsomething/ground-mcp 0.1.0

package/README.md

@@ -0,0 +1,92 @@
+# @createsomething/ground-mcp
+
+Grounded claims for code. An MCP server that prevents AI hallucination in code analysis.
+
+## The Problem
+
+AI agents are confident. Too confident.
+
+They'll tell you two files are "95% similar" without ever comparing them. They'll declare code "dead" without checking who uses it. They'll claim a module is "disconnected" while it's serving thousands of requests.
+
+This is hallucination dressed up as analysis.
+
+## The Solution
+
+**You can't claim something until you've checked it.**
+
+Ground is an MCP server that:
+- Finds duplicates, dead code, and orphaned modules
+- Requires verification before claims
+- Blocks hallucinated analysis
+
+## Installation
+
+```bash
+npm install -g @createsomething/ground-mcp
+```
+
+## MCP Configuration
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ground": {
+      "command": "ground-mcp"
+    }
+  }
+}
+```
+
+Restart Cursor. Ground tools are now available.
+
+## Available 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) |
+
+## Usage Examples
+
+Ask Claude:
+
+```
+Find duplicate functions in src/ with at least 10 lines
+```
+
+```
+Check if the old-utils module is still connected to anything
+```
+
+```
+Run ground_analyze on packages/sdk to find dead code
+```
+
+## Philosophy
+
+Ground is based on a simple principle: **no claim without evidence**.
+
+- **Duplicates** → You have to compare the files first
+- **Dead code** → You have to count the uses first  
+- **Orphans** → You have to check the connections first
+
+This prevents AI hallucination by requiring computation before synthesis.
+
+## Links
+
+- [Full Documentation](https://github.com/createsomethingtoday/create-something-monorepo/tree/main/packages/ground)
+- [Case Study: Kickstand Triad Audit](https://createsomething.io/papers/kickstand-triad-audit)
+- [CREATE SOMETHING Agency](https://createsomething.agency)
+
+## License
+
+MIT

package/bin/.gitkeep

@@ -0,0 +1,4 @@
+# Binary files are downloaded during npm install
+# This directory will contain:
+# - ground-mcp (or ground-mcp.exe on Windows)
+# - ground (or ground.exe on Windows)

package/install.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+
+/**
+ * Ground MCP - Binary installer
+ * 
+ * Downloads the appropriate pre-built binary for the current platform.
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const https = require('https');
+const path = require('path');
+const zlib = require('zlib');
+
+const REPO = 'createsomethingtoday/create-something-monorepo';
+const VERSION = require('./package.json').version;
+
+// Platform mapping
+const PLATFORMS = {
+  'darwin-arm64': 'darwin-arm64',
+  'darwin-x64': 'darwin-x64',
+  'linux-arm64': 'linux-arm64',
+  'linux-x64': 'linux-x64',
+  'win32-x64': 'win32-x64',
+};
+
+function getPlatformKey() {
+  const platform = process.platform;
+  const arch = process.arch;
+  return `${platform}-${arch}`;
+}
+
+function getBinaryName() {
+  const key = getPlatformKey();
+  const name = PLATFORMS[key];
+  
+  if (!name) {
+    console.error(`Unsupported platform: ${key}`);
+    console.error(`Supported platforms: ${Object.keys(PLATFORMS).join(', ')}`);
+    process.exit(1);
+  }
+  
+  return name;
+}
+
+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}`;
+}
+
+async function download(url) {
+  return new Promise((resolve, reject) => {
+    const request = (url) => {
+      https.get(url, { headers: { 'User-Agent': 'ground-mcp-installer' } }, (response) => {
+        // Handle redirects
+        if (response.statusCode === 302 || response.statusCode === 301) {
+          request(response.headers.location);
+          return;
+        }
+        
+        if (response.statusCode !== 200) {
+          reject(new Error(`Download failed: HTTP ${response.statusCode}`));
+          return;
+        }
+        
+        const chunks = [];
+        response.on('data', (chunk) => chunks.push(chunk));
+        response.on('end', () => resolve(Buffer.concat(chunks)));
+        response.on('error', reject);
+      }).on('error', reject);
+    };
+    
+    request(url);
+  });
+}
+
+async function extractTarGz(buffer, destDir) {
+  const { execSync } = require('child_process');
+  const tmpFile = path.join(destDir, 'archive.tar.gz');
+  
+  fs.writeFileSync(tmpFile, buffer);
+  execSync(`tar -xzf "${tmpFile}" -C "${destDir}"`, { stdio: 'inherit' });
+  fs.unlinkSync(tmpFile);
+}
+
+async function extractZip(buffer, destDir) {
+  const AdmZip = require('adm-zip');
+  const zip = new AdmZip(buffer);
+  zip.extractAllTo(destDir, true);
+}
+
+async function install() {
+  console.log('Ground MCP: Installing binary...');
+  
+  const binaryName = getBinaryName();
+  const url = getDownloadUrl(binaryName);
+  const binDir = path.join(__dirname, 'bin');
+  
+  console.log(`Platform: ${getPlatformKey()}`);
+  console.log(`Downloading: ${url}`);
+  
+  try {
+    // Create bin directory
+    if (!fs.existsSync(binDir)) {
+      fs.mkdirSync(binDir, { recursive: true });
+    }
+    
+    // Download archive
+    const buffer = await download(url);
+    console.log(`Downloaded ${(buffer.length / 1024 / 1024).toFixed(2)} MB`);
+    
+    // Extract based on platform
+    if (process.platform === 'win32') {
+      // For Windows, we need adm-zip (optional dependency)
+      try {
+        await extractZip(buffer, binDir);
+      } catch (e) {
+        // Fallback: use PowerShell
+        const tmpFile = path.join(binDir, 'archive.zip');
+        fs.writeFileSync(tmpFile, buffer);
+        execSync(`powershell -Command "Expand-Archive -Path '${tmpFile}' -DestinationPath '${binDir}' -Force"`, { stdio: 'inherit' });
+        fs.unlinkSync(tmpFile);
+      }
+    } else {
+      await extractTarGz(buffer, binDir);
+    }
+    
+    // Make binaries executable (Unix)
+    if (process.platform !== 'win32') {
+      const groundMcp = path.join(binDir, 'ground-mcp');
+      const ground = path.join(binDir, 'ground');
+      
+      if (fs.existsSync(groundMcp)) {
+        fs.chmodSync(groundMcp, 0o755);
+      }
+      if (fs.existsSync(ground)) {
+        fs.chmodSync(ground, 0o755);
+      }
+    }
+    
+    console.log('Ground MCP: Installation complete!');
+    console.log('');
+    console.log('Add to your .cursor/mcp.json:');
+    console.log('');
+    console.log('  {');
+    console.log('    "mcpServers": {');
+    console.log('      "ground": {');
+    console.log('        "command": "ground-mcp"');
+    console.log('      }');
+    console.log('    }');
+    console.log('  }');
+    console.log('');
+    
+  } catch (error) {
+    console.error('Ground MCP: Installation failed');
+    console.error(error.message);
+    console.error('');
+    console.error('You can manually download from:');
+    console.error(`https://github.com/${REPO}/releases`);
+    console.error('');
+    console.error('Or build from source:');
+    console.error('  cargo install --git https://github.com/' + REPO + ' --path packages/ground');
+    process.exit(1);
+  }
+}
+
+// Run installer
+install();

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@createsomething/ground-mcp",
+  "version": "0.1.0",
+  "description": "Grounded claims for code. MCP server that prevents AI hallucination in code analysis.",
+  "author": "CREATE SOMETHING <hello@createsomething.io>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/createsomethingtoday/create-something-monorepo",
+    "directory": "packages/ground"
+  },
+  "homepage": "https://github.com/createsomethingtoday/create-something-monorepo/tree/main/packages/ground",
+  "bugs": {
+    "url": "https://github.com/createsomethingtoday/create-something-monorepo/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "code-analysis",
+    "duplicate-detection",
+    "dead-code",
+    "grounding",
+    "llm",
+    "claude",
+    "cursor"
+  ],
+  "bin": {
+    "ground-mcp": "bin/ground-mcp",
+    "ground": "bin/ground"
+  },
+  "scripts": {
+    "postinstall": "node install.js"
+  },
+  "files": [
+    "bin",
+    "install.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ]
+}