Ground

Grounded claims for code

An MCP server that requires code analysis before an agent can record a claim. Ground focuses its public support contract on TypeScript, JavaScript, and SvelteKit.

npm install @createsomething/ground-mcp

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.

This is hallucination dressed up as analysis.

The Solution

You can't claim something until you've checked it.

  • 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 makes the checked inputs and the finding inspectable before synthesis.

Installation

Claude Code (CLI)

claude mcp add --scope user --transport stdio ground -- npx --yes -p @createsomething/ground-mcp ground-mcp

Codex CLI

codex mcp add ground -- npx --yes -p @createsomething/ground-mcp ground-mcp

Cursor, Windsurf, and JSON-based clients

Add this server to the client MCP configuration:

{
  "mcpServers": {
    "ground": {
      "command": "npx",
      "args": ["--yes", "-p", "@createsomething/ground-mcp", "ground-mcp"]
    }
  }
}

Supported code

  • TypeScript and JavaScript: duplicate functions, imports, uses, dead exports, entry points, orphans, environment boundaries, and git diffs.
  • Svelte and SvelteKit: component-script duplicates, module-context dead exports, route conventions, $lib imports, actions, stores, hooks, and reachability. Instance-script exports such as legacy export let props are component API and are excluded from dead-export findings.
  • Other languages: some direct checks can parse them, but they are outside the public agent-quality support contract.

Only PASS means a requested check completed cleanly. Ground returns FAIL for findings or incomplete requested checks, UNSUPPORTED when relevant source is outside that analyzer, NOT_APPLICABLE when no requested check applies, and TIMEOUT when duplicate analysis reaches its deadline.

Calibration

Ground remains advisory until the checked-in calibration policy passes. Promotion requires at least 10 independently adjudicated findings, 90% precision, no more than a 10% false-positive rate, stable exclusion accounting, and no execution failures in the representative sample.

Each finding stays classified as confirmed, false positive, or out of scope. Out-of-scope observations never inflate detector accuracy.

The current release calibration combines 10 controlled positive fixtures with one preserved real-repository false positive. That qualifies the declared advisory release gate; it is not a population-wide accuracy estimate.

Available Tools

Core Analysis

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)

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

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_suggest_fix Get suggestions for fixing duplications

Graph-Based Analysis

ground_build_graph Build symbol graph for repo-wide analysis
ground_query_dead Query graph for dead exports (filters framework conventions)

AI-Native Tools

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

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

Ask your AI assistant:

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
What's the CSS token adoption ratio in packages/components?

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

The MCP server stores its registry at .ground/registry.db by default and writes its desire-path log beside that database.

For a disposable evaluation, pass an explicit database outside the repository:

ground-mcp --db /tmp/ground-eval/registry.db --workspace /absolute/path/to/project

Links