@createsomething/ground-mcp

Grounded claims for code. An MCP server that computes evidence before code-analysis claims.

The verified setup contract covers Claude Code, Codex, Cursor, and Windsurf.

View Landing Page →

Why Ground?

| Capability | Without Ground | With Ground | |------------|---------------|-------------| | Duplicate detection | "These look similar" | Computed AST + token similarity evidence | | 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" | Token usage and violation counts |

The difference: Ground requires computation before its claim tools accept a claim.

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:

ground analyze ./src --checks duplicates,dead_exports
ground diff ./src --base origin/main --checks duplicates
ground doctor . --json

ground doctor fails on invalid policy and reports the native build, effective policy SHA-256, workspace package count, and internal dependency count. Run it before treating a repository result as authoritative.

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.

Diff coverage

Every batch, diff, and duplicate-function response has a verification_status; ground diff also returns the same status per requested check in check_coverage.<check>.status. The contract is explicit:

• PASS: the check completed for the relevant supported files and found no issue.
• FAIL: the check found an issue or could not complete because of a read/parse failure.
• NOT_APPLICABLE: no changed file needs that check.
• UNSUPPORTED: relevant source exists, but the requested check cannot analyze its language.
• TIMEOUT: duplicate analysis reached its deadline before a complete result was available.

ground analyze and ground diff accept --timeout-ms (120000 by default). The MCP equivalents accept timeout_ms; a deadline returns TIMEOUT, never a clean result. ground diff includes .mjs with JavaScript source analysis. Its changed_files and changed_file_list fields remain the analyzable-file view; read discovered_changed_files, analyzable_changed_files, and excluded_changed_files for the full Git scope. Per-check coverage also names unsupported_changed_files and excluded_changed_files, so a clean claim is valid only with PASS.

Ground 0.4.0 supports TypeScript (.ts, .tsx), JavaScript (.js, .jsx, .mjs), and Svelte (.svelte) in the declared analysis lane. Svelte component scripts participate in duplicate analysis, while SvelteKit configuration, routes, aliases, actions, stores, and framework entry points inform reachability and dead-export evidence. Svelte dead-export checks analyze module-context scripts only; instance-script exports such as legacy export let props are component API and are excluded. Inputs outside that contract remain unsupported rather than being reported as clean.

Ground 0.3.5 extended source-bearing orphan evidence to nested Cloudflare Worker configurations: wrangler.toml and wrangler.json main entries are protected with their exact config source. The legacy ground find orphans command now returns the same verified canonical report as ground analyze --checks orphans. Promptfoo and manual Ground configurations remain recognized alongside package scripts, and broad duplicate scans retain their explicit safety bound.

The release package ships thin command wrappers for every platform. Install downloads the matching versioned release asset and verifies its SHA-256 against that release's SHA256SUMS manifest before extracting it. Record the artifact that produced a receipt with:

ground build-info --json

Ground rejects malformed or unknown native policy fields instead of using defaults. Claim commands recompute current evidence and reject a stored result when source, scope, or the current engine's computation has changed. Duplicate suggestions remain review-only unless a planner produces and validates a concrete patch; similarity alone does not authorize a rewrite.

Maintainers: trusted publishing

Ground tags publish through npm Trusted Publishing rather than a local one-time-password or a long-lived write token. Configure the package's Trusted Publisher in npm with:

• Provider: GitHub Actions
• Organization or user: createsomethingtoday
• Repository: create-something-monorepo
• Workflow filename: ground-release.yml
• Allowed action: npm publish

Do not configure an environment unless the release workflow adds one. The workflow publishes only after its matching GitHub Release and SHA256SUMS manifest have completed successfully.

If a release was built successfully but npm publication was blocked (for example, during Trusted Publishing setup), rerun Ground Release manually with its exact ground-v<version> tag and publish only enabled. That path checks out the tag, executes the governed calibration fixture suite, binds its result to the exact source, recomputes the ledger thresholds, requires the tag to match package.json, and verifies the existing release checksum manifest before publishing; it does not rebuild or replace GitHub Release assets.

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 its claim tools record a finding
• Keeps checked inputs with the recorded claim
• Provides confidence scores with evidence

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)

claude mcp add --scope user --transport stdio ground -- npx --yes -p @createsomething/ground-mcp 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:

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

Claude Code will prompt you to approve it on first use.

Cursor

Add to .mcp.json at your project root:

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

Windsurf

Settings → MCP → View raw config, add:

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

Codex CLI

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

Global Install (When npx Isn't Your Thing)

npm install -g @createsomething/ground-mcp

Now ground-mcp is in your PATH. Use it in any config:

{
  "mcpServers": {
    "ground": {
      "command": "ground-mcp"
    }
  }
}

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:

# Check if the binary exists
ls node_modules/@createsomething/ground-mcp/bin/native/

# 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:

{
  "mcpServers": {
    "ground": {
      "command": "npx",
      "args": ["--yes", "-p", "@createsomething/ground-mcp", "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

| 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_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 (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 |

MCP Apps (Interactive UIs)

Ground supports the MCP Apps extension 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 | |------|--------------| | 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 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

What's the CSS token adoption ratio in packages/canon?

Find design drift in my CSS files only (use extensions: "css")

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)
• Context system — Configure intentional exclusions in .ground.yml with full audit trail

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 keeps Ground's recorded claims tied to prerequisite computation.

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
• Explicit manual CLI entry points for orphan review
• Similarity thresholds

Declare a documented operator CLI by exact path relative to the directory you pass to ground diff. Ground keeps it in duplicate coverage, excludes it only from orphan findings, and records manual_entry_point in check coverage:

entry_points:
  manual:
    - "scripts/rebuild-search-index.mjs"

For ground_find_orphans and ground_analyze, orphan coverage includes entry_point_evidence: the exact path, entry-point type, and source Ground used to protect it. Alongside package, framework, test, and script entry points, Ground recognizes exact entry_points.manual declarations, nested wrangler.toml and wrangler.json Worker main entries, and local providers[].id, prompts[].id, and assertion-value file://… references in promptfooconfig*.yaml. The config adapters accept only existing source files beneath their configuration file; they do not scan arbitrary YAML or follow parent/absolute paths. The legacy ground find orphans command returns this same canonical orphan evidence.

See Full Documentation 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:

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
• Case Study: Kickstand Triad Audit
• CREATE SOMETHING Agency

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.