io.github.rm-rf-prod/groundtruth

Install

Config snippet generator goes here (5 client tabs)

README

<div align="center">
<table><tr><td>
<pre>
   ██████╗ ████████╗    ███╗   ███╗  ██████╗ ██████╗
  ██╔════╝ ╚══██╔══╝    ████╗ ████║ ██╔════╝ ██╔══██╗
  ██║  ███╗   ██║       ██╔████╔██║ ██║      ██████╔╝
  ██║   ██║   ██║       ██║╚██╔╝██║ ██║      ██╔═══╝
  ╚██████╔╝   ██║       ██║ ╚═╝ ██║ ╚██████╗ ██║
</pre>
</td></tr></table>
</div>

<h3 align="center">Your AI assistant just mass-produced deprecated code again.<br/>You merged it because the formatting was clean.<br/><br/>GroundTruth fixes that.</h3>

<p align="center">
  <a href="https://www.npmjs.com/package/@groundtruth-mcp/gt-mcp"><img src="https://img.shields.io/npm/v/@groundtruth-mcp/gt-mcp?color=00d4aa&label=npm" alt="npm version" /></a>
  <a href="https://github.com/rm-rf-prod/GroundTruth-MCP/actions/workflows/ci.yml"><img src="https://github.com/rm-rf-prod/GroundTruth-MCP/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-ELv2-orange" alt="Elastic License 2.0" /></a>
  <img src="https://img.shields.io/badge/libraries-422%2B-teal" alt="422+ curated libraries" />
  <img src="https://img.shields.io/badge/audit_patterns-107%2B-red" alt="107+ audit patterns" />
  <img src="https://img.shields.io/badge/tests-758-brightgreen" alt="758 tests" />
  <img src="https://img.shields.io/badge/tools-12-blue" alt="12 tools" />
  <img src="https://img.shields.io/badge/node-%3E%3D24-green" alt="Node 24+" />
</p>

<h4 align="center">Self-hosted MCP server. 422+ curated libraries. 100+ audit patterns. No rate limits. No API keys.<br/>Ships updates continuously — your MCP client picks them up on restart.</h4>

---

## The problem

Your model doesn't know that React 19 killed `forwardRef`, that Next.js made `cookies()` async, or that Tailwind v4 nuked `@tailwind` directives. It writes deprecated patterns with full confidence. It hands you SQL injection dressed up as a query builder and uses `any` in TypeScript like it's a feature.

**GroundTruth runs on your machine.** Fetches docs from the source — `llms.txt`, Jina Reader, GitHub — right when you ask. 422+ curated libraries, plus npm, PyPI, crates.io, and pkg.go.dev as fallback. The audit tool reads your actual files, finds issues at exact `file:line` locations, and fetches the current fix from the real spec.

---

<p align="center">
  <img src="./diagram.webp" alt="GroundTruth architecture — library nodes connected to a central hub, code audit panel, live documentation fetch" width="100%" />
</p>

---

## Install

### Claude Code

```bash
claude mcp add gt -- npx -y @groundtruth-mcp/gt-mcp@latest
```

### Cursor / Claude Desktop / VS Code

Add to your MCP config (`claude_desktop_config.json`, `.cursor/mcp.json`, or `.vscode/mcp.json`):

```json
{
  "mcpServers": {
    "gt": {
      "command": "npx",
      "args": ["-y", "@groundtruth-mcp/gt-mcp@latest"]
    }
  }
}
```

No build step. No config file. Node.js 24+. Using `@latest` means npx pulls the newest version on every session start — you always get the latest libraries, audit patterns, and fixes without doing anything.

### Optional: GitHub token

GroundTruth fetches README files, release notes, migration guides, and code examples from GitHub. Unauthenticated requests are limited to 60/hr. A token with no extra scopes takes it to 5,000/hr.

```bash
# Claude Code
claude mcp add gt -e GT_GITHUB_TOKEN=ghp_yourtoken -- npx -y @groundtruth-mcp/gt-mcp@latest

# Cursor / Claude Desktop / VS Code — add env to your config:
"env": { "GT_GITHUB_TOKEN": "ghp_yourtoken" }
```

---

## What it does

Twelve tools. Each does one thing.

| Tool | What it does |
|---|---|
| `gt_resolve_library` | Find a library by name. Falls back to npm, PyPI, crates.io, pkg.go.dev |
| `gt_get_docs` | Fetch live docs for a specific topic |
| `gt_best_practices` | Patterns, anti-patterns, and config guidance for any library |
| `gt_auto_scan` | Read your manifest, fetch best practices for every dependency |
| `gt_search` | Search OWASP, MDN, web.dev, W3C, AI provider docs, Google APIs |
| `gt_audit` | Scan source files — issues at exact `file:line` with live fixes |
| `gt_changelog` | Release notes before you upgrade |
| `gt_compat` | Browser and runtime compatibility via MDN + caniuse |
| `gt_compare` | Compare 2-3 libraries side-by-side |
| `gt_examples` | Real-world code examples from GitHub |
| `gt_migration` | Migration guides and breaking changes |
| `gt_batch_resolve` | Resolve up to 20 libraries in one call |

---

## How to use it

You don't need to memorize tool names. Just talk to your AI assistant.

```
use gt for nextjs
use gt for drizzle migrations
gt audit
use gt to check WCAG focus indicators
use gt for OpenTelemetry setup
find all issues and fix with gt
use gt for Google Gemini API
use gt for Claude tool use
```

Or call tools directly:

```typescript
gt_resolve_library({ libraryName: "nestjs" })
gt_get_docs({ libraryId: "nestjs/nest", topic: "guards" })
gt_best_practices({ libraryId: "vercel/next.js", topic: "