@groundtruth MCP/gt

Install (60 seconds)

Requires Node.js 24 or newer.

Claude Code

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

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

VS Code (.vscode/mcp.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):

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.

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.

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:

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

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.

CLI

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.

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 the tool
gt-mcp call gt_compare '{"libraries":["prisma","drizzle-orm"]}'
echo '{"libraryName":"drizzle"}' | gt-mcp call gt_resolve_library -

Exit codes: 0 ok, 1 tool error, 2 usage error. Logs stay quiet on stderr unless something goes wrong (GT_LOG_LEVEL defaults to warn for commands). The server flags still work: --version, --health, --routing-table, --help.

Performance

Measured on one machine with the same harness, published 7.5.0 against 8.0.0. Network timings depend on your connection and on the docs site.

Fewer tokens per session and per answer:

More of the answer reaches the model in clients that display structuredContent instead of the text:

Where the time went: the binary is a small bootstrap that loads the server lazily and uses the Node compile cache; docs pages are requested as markdown; the reader service is only a fallback; and cached pages are served stale-while-revalidate. A page up to 7 days old is returned at once and refreshed in the background.

How it works

1. Resolve. The library name is matched against the curated registry, then npm, PyPI, crates.io and Go modules.
2. Cache. An in-memory LRU, bounded by entry count and by characters, then the disk cache in ~/.gt-mcp-cache.
3. Fetch. Sources are tried in order and the first useful one wins:
   1. llms.txt / llms-full.txt, the files maintainers publish for LLMs. A nested llms.txt resolves to the library's own index.
   2. The docs page as markdown, via Accept: text/markdown content negotiation where the site supports it. The Next.js caching page is 715 KB as HTML and 16 KB as markdown.
   3. The HTML page, converted to markdown directly.
   4. GitHub: README, docs files, releases. GitHub-hosted libraries read their own README, not GitHub's site-wide llms.txt.
   5. The Jina reader, as a hedged fallback that starts after 1.5 s or after a direct fetch fails.
4. Sanitize. Prompt-injection filter, SSRF guard, navigation and boilerplate stripped.
5. Rank. BM25 scores each section against the topic and fills the token budget with the ones that mention it.
6. Check. The evidence gate (below) decides whether the answer covers the topic.
7. Answer. Ranked excerpts with source URLs, fetch date and topic coverage.

The fetch layer keeps connections alive for 60 s, shares one in-flight request between identical callers, honours per-call cancellation and the GT_TOOL_TIMEOUT_MS deadline, caches 404s and oversized bodies so they are not retried, and skips a host for a while after repeated failures.

Evidence, not vibes

The failure mode of every docs tool is the confident non-answer: you ask about row-level security, the tool hands back the Postgres landing page, and your model writes something plausible from it.

GroundTruth checks the content it fetched against the question before returning it. The check counts how many of your topic's terms appear, how often, and whether they show up in a heading or inside a code block. Link targets and URL query strings don't count, so a 404 page whose navigation happens to contain your topic doesn't pass.

• Weak coverage triggers a second, topic-targeted fetch instead of shipping the first page that loaded.
• Zero coverage returns an explicit miss. You get the sources that were checked, an outline of what those pages do cover, and what to try next. Treat it as a true negative.
• Every successful answer ends with an ## Evidence footer: source URLs, fetch date and topic-coverage numbers, so you can check where it came from.

The check is synonym-aware: an rls query is satisfied by a page that says "row level security", and a page found by expanding "migration" to "upgrade guide" isn't failed for lacking the literal word.

Accuracy, 7.5.0 against 8.0.0:

Both routing corpora run in the test suite.

Coverage

793 curated libraries across 21 language ecosystems, plus automatic fallback to npm, PyPI, crates.io and Go modules for anything outside the registry.

Release 8.0.0 adds 195 libraries: Python, data and AI tooling, Java, Kotlin and Spring, .NET, Go, Rust, Ruby, PHP, Swift, Dart and Flutter, Elixir, C and C++, infrastructure, databases, observability and more JavaScript and TypeScript. Every one of the 598 existing entries was probed live: 35 broken docs roots fixed, 115 moved docs sites updated, about 190 verified llms.txt indexes added. The curated URL tables (2,638 URLs) were re-checked.

The full list is the registry source: src/sources/registry.ts.

Security

GroundTruth fetches untrusted web content and hands it to a model, so the fetch path is hardened:

• SSRF guard blocks private, loopback, link-local and ULA ranges, on redirects too. IP-literal URLs are checked against the full blocklist, including cloud metadata at 100.100.100.200 and fd00:ec2::254, NAT64 and 6to4.
• Prompt-injection sanitizer decodes HTML entities and strips zero-width and bidi characters before scanning, then redacts the exact matching span using an offset map. It is best-effort pattern redaction; treat fetched docs as untrusted input.
• Tokens stay on their origin. GT_GITHUB_TOKEN and GT_JINA_API_KEY are never forwarded to another origin, including on redirects.
• Audit patterns are ReDoS-safe. The worst-case input went from 9.5 s to 1 ms.
• HTTP mode binds 127.0.0.1 by default, validates Host and Origin, and compares the bearer token in constant time.
• No user data on disk. The disk cache holds fetched documentation under hashed keys, not prompts or tool inputs.

Report vulnerabilities privately through GitHub Security Advisories. Scope and threat model: SECURITY.md.

HTTP and Docker

Set GT_HTTP_PORT and GroundTruth serves Streamable HTTP instead of stdio. It speaks MCP spec 2026-07-28 and still serves 2025-era clients.

Local, loopback only:

GT_HTTP_PORT=3100 npx -y @groundtruth-mcp/gt-mcp@latest

It binds 127.0.0.1. Without GT_AUTH_TOKEN it starts open to local callers and logs a warning. With a token, every path, /health and /metrics included, needs Authorization: Bearer <token>.

Docker:

docker build -t gt-mcp .
export GT_AUTH_TOKEN="$(openssl rand -hex 32)"
docker run -d --name gt -p 127.0.0.1:3100:3100 -e GT_AUTH_TOKEN gt-mcp
claude mcp add --transport http gt http://localhost:3100/mcp --header "Authorization: Bearer $GT_AUTH_TOKEN"

The image is 277 MB, runs as the unprivileged gt user, and binds 0.0.0.0 inside the container, so it refuses to start without GT_AUTH_TOKEN. Its healthcheck sends the token. The -p 127.0.0.1: prefix keeps the port on the host's loopback; drop it to serve other machines.

Behind a reverse proxy: the server speaks plain HTTP. Terminate TLS at the proxy and add the public hostname to GT_HTTP_ALLOWED_HOSTS, otherwise requests carrying it get 403. On a non-loopback bind the server will not start without GT_AUTH_TOKEN.

Sessions: stateless by default. GT_HTTP_STATEFUL=1 gives each 2025-era client its own session, closed after 30 minutes without a request.

An authenticated caller can make the server fetch public URLs and run gt_audit and gt_auto_scan on any directory the process can read. Don't mount anything into the container you wouldn't want read.

Configuration

Everything is optional. Invalid numeric or enum values fail at startup instead of falling back silently.

gt-mcp --help prints the same list.

Upgrading from 7.x

8.0.0 has four breaking changes. Stdio users on Node 24 or newer who read the text content are not affected by any of them.

Also new under the hood: the MCP TypeScript SDK v2 (@modelcontextprotocol/server), tools/list cache hints, and a fixed HTTP mode (7.5.0 answered only the first HTTP request). Production dependencies went from 169 packages (27 MB) to 13 (7.7 MB), and the Docker image from 566 MB to 277 MB. Full list: CHANGELOG.md.

vs. Context7

Context7 is a good product. The differences:

Context7 indexes docs into a vector database, which is fast but lags behind new releases. GroundTruth fetches from the source at query time and tells the model when it found nothing on the topic.

Contributing

Adding a library is a pull request to src/sources/registry.ts with id, name, docsUrl, and llmsTxtUrl if the project publishes one.

pnpm install
pnpm typecheck
pnpm test        # 2063 tests across 267 files
pnpm build

CI runs the suite on Node 24 and 26. Issues and requests: github.com/rm-rf-prod/GroundTruth-MCP/issues.

Reference

Star history

License

Elastic License 2.0. Free to use, self-host and build on. The one thing you can't do is offer it as a managed service.