lurq

<div align="center">

# lurq

**The verification layer for everything your agent installs.**

Your coding agent picks npm packages from memory. lurq checks them against the live
registry, security advisories, shipped type definitions and real co-installs, before
anything lands in `package.json`.

[![npm version](https://img.shields.io/npm/v/lurqrun?color=%230b7285&label=npm)](https://www.npmjs.com/package/lurqrun)
[![npm downloads](https://img.shields.io/npm/dm/lurqrun?color=%230b7285)](https://www.npmjs.com/package/lurqrun)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.jadenryu%2Flurq-6E56CF)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.jadenryu/lurq)
[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![node](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)](https://nodejs.org)

[Install](#install) · [For AI agents](#for-ai-agents) · [MCP tools](#mcp-tools) · [CLI](#cli) · [Autopilot](#autopilot) · [Docs](https://www.lurq.run/docs)

</div>

```text
$ lurq verify lodahs
lodahs  ✗ do not install 0.0.1-security (latest) without review
  • name closely mimics "lodash" — possible typosquat
  • 1 critical/high advisory(ies) recorded against this package
risk flags: possible-typosquat-of:lodash, low-downloads, single-maintainer, has-known-advisory

$ lurq verify zod
zod  ✓ no supply-chain problems found in 4.6.4 (latest)
weekly dl:  209.2M   confidence: proven   advisories: 0

$ lurq compat next @auth/core next-auth
next + @auth/core + next-auth  conflict
peer-deps  next-auth needs peer @auth/core@0.34.3, but the stack uses @auth/core@0.41.3
```

Real output, not a mockup. Your agent gets the same answers over MCP.

---

## Why your agent needs this

A model's knowledge of npm stops at its training cutoff. The registry doesn't.

- **Invented and typosquatted names.** Agents confidently install packages that don't exist, or that
  exist only because someone registered the misspelling.
- **APIs that moved.** Of the 38,752 packages lurq tracks, 2,725 shipped a new major version between
  May 1 and September 13, 2026. Code written from memory calls functions that were renamed or removed.
- **Stacks that don't install together.** Every package can be healthy on its own while the set
  fails on a peer or engine range. That usually surfaces at deploy.

lurq answers from evidence it can show: **47,238 packages scored, 4.2M versions tracked, 34,843 API
surfaces extracted from shipped code, and 27M co-install pairs**, refreshed daily from npm, GitHub,
deps.dev and OSV. Every answer carries a `dataAsOf` timestamp.

> **Scope:** the JavaScript/TypeScript ecosystem (npm).

---

## Install

One command, once per machine. Nothing to install first:

```bash
npx lurqrun
```

The setup wizard:

1. Opens lurq in your browser. Sign in and the key comes back to the terminal by itself.
2. Detects every coding agent on the machine.
3. Writes a keyed remote MCP entry for each, in the shape that agent expects.
4. Installs standing instructions where the agent supports them, so it reaches for lurq instead of
   answering from memory.

Restart your agent afterward. **The free plan includes 1,000 hosted calls a month and never asks
for a card.**

**Works with:** Claude Code · Cursor · Windsurf · VS Code / GitHub Copilot · OpenAI Codex CLI ·
Gemini CLI · Google Antigravity · Kiro

**Check it worked:** ask your agent to *"add zod to this project"*. It should call lurq's `verify`
before installing anything.

The package is published as **`lurqrun`** (the bare name was taken). The command is `lurq`:

```bash
npm install -g lurqrun
lurq --version
```

---

## For AI agents

If you are an AI coding agent and your user asked you to set up lurq, follow these steps.

**1. Get an API key from the user.** Keys come from
[lurq.run/dashboard/keys](https://www.lurq.run/dashboard/keys) and are free to create. Never invent
one. If the user has no key, run `npx lurqrun` so they can sign in through the browser, and let them
finish the wizard.

**2. Configure non-interactively** once you have a key:

```bash
npx lurqrun setup --yes --no-open --api-key <key> --agent <id>
```

| Agent | `--agent` |
|---|---|
| Claude Code | `claude-code` |
| Cursor | `cursor` |
| Windsurf | `windsurf` |
| VS Code / GitHub Copilot | `copilot` |
| OpenAI Codex CLI | `codex` |
| Gemini CLI | `gemini-cli` |
| Google Antigravity | `antigravity` |
| Kiro | `kiro` |

`--agent all` configures every detected agent. With `--yes`, the key can also come from `LURQ_API_KEY`.

**3. Tell the user to restart the agent**, then confirm `lurq` appears in its MCP tool list.

<details>
<summary><b>Writing the MCP config by hand</b></summary>

Endpoint: `https://api.lurq.run/mcp` (streamable HTTP), header `Authorization: Bearer <key>`. The
field names differ by client:

**Claude Code** (`~/.claude.json`, under `mcpServers`) and **VS Code** (`mcp.json`, under `servers`):

```json
"lurq": { "type": "http", "url": "https://api.lurq.run/mcp", "headers": { "Authorization": "Bearer <key>" } }
```

**Cursor** (`~/.cursor/mcp.json`) and **Kiro** (`~/.kiro/settings/mcp.json`), under `mcpServers`:

```json
"lurq": { "url": "https://api.lurq.run/mcp", "headers": { "Authorization": "Bearer <key>" } }
```

**Windsurf** (`~/.codeium/windsurf/mcp_config.json`) and **Antigravity** (`~/.gemini/config/mcp_config.json`), under `mcpServers`:

```json
"lurq": { "serverUrl": "https://api.lurq.run/mcp", "headers": { "Authorization": "Bearer <key>" } }
```

**Gemini CLI** (`~/.gemini/settings.json`, under `mcpServers`). It must be `httpUrl`, because a
plain `url` is read as SSE:

```json
"lurq": { "httpUrl": "https://api.lurq.run/mcp", "headers": { "Authorization": "Bearer <key>" } }
```

**Codex** (`~/.codex/config.toml`). Headers go in an inline table:

```toml
[mcp_servers.lurq]
url = "https://api.lurq.run/mcp"
http_headers = { Authorization = "Bearer <key>" }
```

</details>

### When to call lurq

| You are about to… | Call |
|---|---|
| Install or import a package | `verify` with the exact name, first |
| Choose between libraries | `compare` your candidates, then `verify` the pick |
| Commit to a set of packages | `compat` with the whole set in one call |
| Write code against a package whose API may have moved | `usage`, with the version you remember as `knownVersion` |
| Upgrade, or explain a break | `diff_surface` between the two versions |
| Add dependencies in a team codebase | `policy`, before choosing |
| Review a whole project | `audit` with names and versions from `package.json` and the lockfile |
| Wire an MCP server into an agent | `mcp_surface`, or `mcp_stack` for several |
| Not sure which tool fits | `capabilities` |

When lurq flags something, tell the user what it found and that it came from lurq. An `unknown` or
`UNVERIFIABLE` result means lurq could not check. It never means the package is clean.

Machine-readable docs: [lurq.run/llms.txt](https://www.lurq.run/llms.txt) ·
[lurq.run/docs/llms-full.txt](https://www.lurq.run/docs/llms-full.txt)

---

## MCP tools

Fifteen tools. Responses are compact to save tokens, and package answers carry `dataAsOf`.

**Before installing**

| Tool | What it answers |
|---|---|
| `verify` | Is this package real, healthy and safe? Catches hallucinated and typosquatted names |
| `evaluate` | The full evidence for one package: scores, advisories, usage guide, sandbox verdict |
| `compare` | 2–5 packages ranked head-to-head |
| `policy` | What your team's selection policy refuses, so the agent picks an allowed package first |

**Across a stack**

| Tool | What it answers |
|---|---|
| `compat` | Will these packages install together? Returns the exact clashing peer or engine range |
| `audit` | A whole project's outdated, deprecated and vulnerable dependencies and drifted MCP servers, in one call |
| `diagram` | A reference-architecture Mermaid diagram for a stack |

**Writing code**

| Tool | What it answers |
|---|---|
| `usage` | A version's real public API from its shipped `.d.ts`, and what changed since the version you know |
| `resolve_surface` | What a version actually exports at runtime |
| `diff_surface` | What a version bump adds, removes, renames or changes arity on |

**MCP servers**

| Tool | What it answers |
|---|---|
| `mcp_surface` | A server's real tool contract, from a live `tools/list` handshake, including what each tool can write or reach |
| `mcp_drift` | What a server changed between two versions |
| `mcp_stack` | Do these servers collide in one agent's tool namespace? |

**About lurq**

| Tool | What it answers |
|---|---|
| `capabilities` | Which lurq tool answers this situation |
| `report_outcome` | What happened after a pick shipped, which feeds future rankings |

Inputs, outputs and verdict definitions for each: [MCP tools reference](https://www.lurq.run/docs/mcp-tools).

---

## CLI

The same index, scriptable. Every read command takes `--json`.

```bash
# Before installing
lurq verify jsonwebtoken
lurq evaluate zod
lurq compare date-fns dayjs moment

# Stacks and projects
lurq compat next react react-dom
lurq audit .                               # every dependency and MCP server in the project

# APIs and upgrades
lurq usage zod --known 3.22.4              # what changed since the version you know
lurq upgrade-plan .                        # what's behind, and what each upgrade removes
lurq check-upgrade . --plan lurq-plan.json --exit-code

# Publishing your own package
lurq check-release                         # is the version you're about to publish honest?
lurq check-api --against origin/main       # does this break your API's callers?

# MCP servers
lurq mcp-scan                              # read the servers you have configured, record what changed

# Team policy
lurq policy pull policy.json               # keep the selection policy in a reviewed file
lurq policy push policy.json               # and apply it from CI (needs a policy:write ke