GroundTruth-MCP

<p align="center">
  <img src="./assets/hero.png" alt="GroundTruth: live, official documentation and code audits for AI coding agents, drawn from llms.txt, docs sites, GitHub, npm, PyPI, MDN and OWASP" width="100%" />
</p>

<h3 align="center">Current, official documentation for coding agents, fetched when they ask.</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-793%2B-teal" alt="793+ 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-2063-brightgreen" alt="2063 tests" />
  <img src="https://img.shields.io/badge/tools-14-blue" alt="14 tools" />
  <img src="https://img.shields.io/badge/node-%3E%3D24-green" alt="Node 24+" />
</p>

GroundTruth is a self-hosted MCP server and command-line tool. Models write code from what they were trained on, so they still wrap components in `forwardRef` after React 19 made `ref` a regular prop, call `cookies()` synchronously after Next.js made it async, and emit `@tailwind` directives that Tailwind v4 replaced with `@import "tailwindcss"`. GroundTruth gives the agent the library's own documentation at request time: it reads `llms.txt`, the docs site as markdown, or the GitHub repository, ranks the sections that answer the question, and checks that the answer covers the topic before returning it. It also audits your source with 107+ patterns and links every finding to the current fix. It runs on your machine. No account, no API key, no rate limit of its own.

---

## Install (60 seconds)

Requires Node.js 24 or newer.

**Claude Code**

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

**Cursor, Claude Desktop, Windsurf** and other clients that use an `mcpServers` block (`.cursor/mcp.json`, `claude_desktop_config.json`, `~/.codeium/windsurf/mcp_config.json`):

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

**VS Code** (`.vscode/mcp.json`):

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

Any other MCP client: run `npx -y @groundtruth-mcp/gt-mcp@latest` as a stdio server.

**Command line** (same tools, no MCP client needed):

```bash
npm install -g @groundtruth-mcp/gt-mcp
gt-mcp bp nextjs caching
```

`@latest` makes npx pick up new releases on the next session start. When a newer version exists, tool responses carry a one-line notice (`GT_NO_UPDATE_CHECK=1` turns the check off).

### Optional: GitHub token

GroundTruth reads READMEs, release notes, migration guides and code examples from GitHub. Without a token GitHub allows 60 requests per hour. A token with no extra scopes raises that to 5,000 and enables code search in `gt_examples`.

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

In a JSON config, add `"env": { "GT_GITHUB_TOKEN": "ghp_yourtoken" }` next to `args`.

---

## What you get

Fourteen tools. Each does one job, and each is also a CLI command.

| Tool | CLI | What it does |
|---|---|---|
| `gt_dispatch` | `ask` | Routes a plain request ("use gt for drizzle migrations") to the right tool and arguments |
| `gt_resolve_library` | `resolve` | Finds a library by name; falls back to npm, PyPI, crates.io and Go modules |
| `gt_get_docs` | `docs` | Live docs for one topic; also accepts a docs URL |
| `gt_best_practices` | `bp` | Patterns, anti-patterns and configuration guidance for a library |
| `gt_auto_scan` | `scan` | Reads your manifest and fetches best practices for each dependency |
| `gt_search` | `search` | Any topic without a library: OWASP, MDN, web.dev, W3C, AI provider docs, Google APIs |
| `gt_audit` | `audit` | Scans source files and reports issues at `file:line` with links to the fix |
| `gt_changelog` | `changelog` | Release notes before you upgrade |
| `gt_compat` | `compat` | Browser and runtime support from MDN browser-compat-data and caniuse |
| `gt_compare` | `compare` | Two or three libraries side by side |
| `gt_examples` | `examples` | Real-world code from GitHub |
| `gt_migration` | `migrate` | Migration guides and breaking changes between versions |
| `gt_batch_resolve` | `batch` | Resolves up to 20 libraries in one call |
| `gt_snippets` | `snippets` | Ranked code snippets per library and version, cached on disk |

The server also exposes 2 MCP resources (`library-registry`, `library-docs`) and 8 prompts (`audit-my-project`, `upgrade-check`, `best-practices-scan`, `compare-libraries`, `security-check`, `migration-guide`, `find-examples`, `dependency-audit`).

You don't need the tool names. Ask in plain language:

```
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
```

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: "caching" })
gt_auto_scan({ projectPath: "." })
gt_search({ query: "OWASP SQL injection prevention" })
gt_audit({ projectPath: ".", categories: ["security", "accessibility"] })
gt_changelog({ libraryId: "vercel/next.js", version: "15" })
gt_compat({ feature: "CSS container queries", environments: ["safari"] })
gt_compare({ libraries: ["prisma", "drizzle-orm"], criteria: "TypeScript support" })
gt_examples({ library: "hono", pattern: "middleware" })
```

### `gt_audit`

Walks your project, runs 107+ patterns across 18 categories, reports each issue at `file:line`, then fetches the fix from the authoritative source.

```
gt_audit({ categories: ["all"] })                      // all 18 categories
gt_audit({ categories: ["security", "node"] })         // OWASP + Node.js
gt_audit({ categories: ["python", "security"] })       // Python OWASP scan
gt_audit({ categories: ["accessibility"] })            // WCAG AA
gt_audit({ categories: ["typescript", "react"] })      // type safety + React rules
```

| Category | What it checks |
|---|---|
| `security` | XSS, SQL injection, command injection, SSRF, path traversal, hardcoded credentials, CORS wildcard |
| `accessibility` | Missing alt text, onClick on div, icon-only buttons, inputs without labels, `outline: none` |
| `react` | forwardRef (React 19), useFormState renamed, index as key, conditional hooks |
| `nextjs` | Sync cookies/headers/params (Next.js 16), Tailwind v3 directives, missing metadata |
| `typescript` | `any` type, non-null assertions, `@ts-ignore`, floating Promises |
| `performance` | Missing lazy loading, useEffect data fetching, missing Suspense boundaries |
| `layout` | CLS-causing images, 100vh on mobile, missing font-display |
| `node` | console.log in production, sync fs ops, unhandled callbacks |
| `python` | SQL injection via f-string, eval/exec, subprocess shell=True, pickle.loads |
| Also | `mobile`, `css`, `vue`, `svelte`, `angular`, `testing`, `seo`, `i18n`, `api` |

Sample output:

```
## [CRITICAL] SQL built via template literal
Category: security | Severity: critical | Count: 2

Fix: db.query('SELECT * FROM users WHERE id = $1', [userId])

Files:
  - src/db/users.ts:47
  - src/api/search.ts:23

Live fix: OWASP SQL Injection Prevention Cheat Sheet
```

### `gt_auto_scan`

Point it at a project root. It reads the manifest and lockfile, works out which libraries you use and at which versions, and returns best practices for each, top libraries first. Default output is about 15K characters.

Reads `package.json`, `deno.json`, `requirements.txt`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`, `build.gradle`, `build.gradle.kts`, `composer.json`, `Gemfile` and `pubspec.yaml`.

### `gt_search`

For anything that isn't one library.

| Area | Topics |
|---|---|
| Security | OWASP Top 10, SQL injection, XSS / CSP, CSRF, HSTS, CORS, JWT, OAuth 2.1, WebAuthn, SSRF, API security |
| Accessibility | WCAG 2.2, WAI-ARIA, keyboard navigation |
| Performance | Core Web Vitals, image optimization, web fonts, Speculation Rules |
| Web APIs | Fetch, Workers, WebSocket, WebRTC, IndexedDB, Web Crypto, Intersection Observer |
| CSS | Grid, Flexbox, Container Queries, View Transitions, Cascade Layers, :has(), Subgrid |
| AI providers | Claude, OpenAI, Gemini, Mistral, Cohere, Groq, LangChain, LlamaIndex |
| Google | Maps, Analytics, Ads, Cloud, Firebase, Vertex AI, YouTube, Gmail, Sheets |
| Infrastructure | Docker, Kubernetes, GitHub Actions, Terraform, Cloudflare Workers |

---

## CLI

<p align="center">
  <img src="./assets/cli.png" alt="Terminal running gt-mcp docs react useEffect: the library resolves in 2 ms, react.dev/llms.txt is fetched, 6 of 48 sections are ranked, the evidence check passes and the answer prints with its sources" width="100%" />
</p>

`gt-mcp <command>` runs the same 14 tools in-process and prints the answer. With no arguments, `gt-mcp` is the stdio MCP server, exactly as before.

```bash
gt-mcp docs react useEffect                  # live docs for one topic
gt-mcp bp nextjs caching                     # best practices
gt-mcp search "OWASP SSRF prevention"
gt-mcp audit .                               # audit the current project
gt-mcp scan .                                # best practices for every dependency
gt-mcp compat "CSS container queries"
gt-mcp ask "how do I paginate with drizzle"  # let gt_dispatch pick t