lurq

Official16 toolsLive

by jadenryu · TypeScript

Verify npm packages before your AI agent installs them: hallucinations, advisories, API drift.

io.github.jadenryu/lurq MCP Server

The io.github.jadenryu/lurq MCP server verifies npm packages before your AI agent installs them. Its purpose is to check for issues such as hallucinations, advisories, and API drift, reducing the risk that an agent proceeds with incorrect or outdated package information.

🛠️ Key Features

NPM package verification prior to installation

🚀 Use Cases

Preventing installation of problematic npm packages by AI agents
Detecting hallucinations, advisories, and API drift before install

⚡ Developer Benefits

Improves package correctness checks for agent workflows

Captured live from the server via tools/list.

evaluate

Full evidence read for one npm package: health and quality scores and the signals behind them, advisories, the shared safety verdict, a summary and a usage guide. Use it when a choice needs more than verify's install gate. Enforces the account's dependency policy. A package lurq has never tracked is fetched and scored on demand, waiting up to ~4 seconds; if scoring takes longer the result is `tracked: false` with a note to retry in a few seconds, which is not an answer about the package.

Parameters1

package

string

required

npm package name

Raw schema

{
  "type": "object",
  "properties": {
    "package": {
      "type": "string",
      "minLength": 1,
      "maxLength": 214,
      "pattern": "^(?:@[a-z0-9-][a-z0-9-._]*\\/)?[a-z0-9-][a-z0-9-._]*$",
      "description": "npm package name"
    }
  },
  "required": [
    "package"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

policy

The rules this account's selection policy enforces on which packages you may add: denied packages (with the reason), license allowlist, confidence, advisory, adoption, staleness and bundle-size floors. Read it once before choosing dependencies so you pick an allowed package first; evaluate already enforces it. Read-only.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

compare

Side-by-side comparison of 2–5 npm packages you are choosing between, ranked by health score. Untracked names are fetched on demand; one still being scored comes back under `pending` (retry shortly), and a name not on npm under `notFound`.

Parameters1

packages

array

required

2–5 npm package names

Raw schema

{
  "type": "object",
  "properties": {
    "packages": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 214,
        "pattern": "^(?:@[a-z0-9-][a-z0-9-._]*\\/)?[a-z0-9-][a-z0-9-._]*$"
      },
      "minItems": 2,
      "maxItems": 5,
      "description": "2–5 npm package names"
    }
  },
  "required": [
    "packages"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

compat

Check whether a set of packages forms a coherent stack. Resolves the whole set the way npm would and returns a definitive verdict: compatible, conflict (with the exact clashing constraints), or unknown. Checks peer-dependency and engine ranges from declared metadata, plus any recorded sandbox conflicts. Read-only: never installs or executes package code. Not always instant: a set checked before answers immediately, but a new set is resolved live from registry metadata, which can take up to ~25 seconds. Call once with the whole stack before committing to it.

Parameters3

packages	array	required	The full candidate stack to check together, 2–30 npm package names — a whole package.json dependency list is the intended input. Pass every package in one call: conflicts routinely appear only across the whole set (a peer range three packages deep), so checking pairs separately misses them and costs a round trip each.
versions	object	optional	Optional exact versions keyed by package name, e.g. {"react":"19.0.0"} (use when not checking latest). Must be exact semver versions, not ranges.
node	string	optional	Optional target Node runtime (e.g. "20" or "20.20.2") for engines.node checks

Raw schema

{
  "type": "object",
  "properties": {
    "packages": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 214,
        "pattern": "^(?:@[a-z0-9-][a-z0-9-._]*\\/)?[a-z0-9-][a-z0-9-._]*$"
      },
      "minItems": 2,
      "maxItems": 30,
      "description": "The full candidate stack to check together, 2–30 npm package names — a whole package.json dependency list is the intended input. Pass every package in one call: conflicts routinely appear only across the whole set (a peer range three packages deep), so checking pairs separately misses them and costs a round trip each."
    },
    "versions": {
      "type": "object",
      "additionalProperties": {
        "type": "string",
        "maxLength": 256
      },
      "description": "Optional exact versions keyed by package name, e.g. {\"react\":\"19.0.0\"} (use when not checking latest). Must be exact semver versions, not ranges."
    },
    "node": {
      "type": "string",
      "description": "Optional target Node runtime (e.g. \"20\" or \"20.20.2\") for engines.node checks"
    }
  },
  "required": [
    "packages"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

verify

Confirm an npm package is real, healthy, and not risky before installing: guards against hallucinated or typosquatted names, deprecations and known advisories, and returns a safety verdict with its reasons and what was not checked. Checks the live registry. The cheap gate to call before every install; use evaluate when you need the full scores.

Parameters1

package

string

required

npm package name to verify

Raw schema

{
  "type": "object",
  "properties": {
    "package": {
      "type": "string",
      "minLength": 1,
      "maxLength": 214,
      "pattern": "^(?:@[a-z0-9-][a-z0-9-._]*\\/)?[a-z0-9-][a-z0-9-._]*$",
      "description": "npm package name to verify"
    }
  },
  "required": [
    "package"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

usage

A package version's TYPED API: exported symbols and their signatures from its shipped .d.ts (or DefinitelyTyped), exact to the version, none of it in the model's training data. Use before writing code against a package whose API may have moved. For whether a name exists at RUNTIME (what decides if an import throws) use resolve_surface; for is-it-safe-to-install use verify. Pass knownVersion (e.g. the version you were trained on) to get the precise delta: added, removed, renamed, changed. Also returns the version's declared engines (Node/runtime floor). Large surfaces are paged, 80 symbols per call: `totalSymbols` is the size, `query` filters by name, `offset` pages. `shallow: true` means the API lives on an interface's members that are not listed, and the note says where to read them. For framework file/convention changes (not exported symbols), consult the official migration guide / Context7 instead.

Parameters5

package	string	required	npm package name
version	string	optional	Target version (defaults to latest)
knownVersion	string	optional	A version you already know; returns the API delta from it to the target
query	string	optional	Part of a symbol name (case-insensitive); returns only matching symbols
offset	integer	optional	Index of the first symbol to return, to page past the first 80

Raw schema

{
  "type": "object",
  "properties": {
    "package": {
      "type": "string",
      "minLength": 1,
      "maxLength": 214,
      "pattern": "^(?:@[a-z0-9-][a-z0-9-._]*\\/)?[a-z0-9-][a-z0-9-._]*$",
      "description": "npm package name"
    },
    "version": {
      "type": "string",
      "description": "Target version (defaults to latest)"
    },
    "knownVersion": {
      "type": "string",
      "description": "A version you already know; returns the API delta from it to the target"
    },
    "query": {
      "type": "string",
      "maxLength": 100,
      "description": "Part of a symbol name (case-insensitive); returns only matching symbols"
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "description": "Index of the first symbol to return, to page past the first 80"
    }
  },
  "required": [
    "package"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

diagram

Emit a reference-architecture Mermaid diagram for a stack you have already chosen (package names). A labeled starting point keyed by layer, not a validated architecture, and not an architecture designer.

Parameters1

stack

array

optional

Package names that make up the stack; omit or empty to get usage guidance

Raw schema

{
  "type": "object",
  "properties": {
    "stack": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 214,
        "pattern": "^(?:@[a-z0-9-][a-z0-9-._]*\\/)?[a-z0-9-][a-z0-9-._]*$"
      },
      "description": "Package names that make up the stack; omit or empty to get usage guidance"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

resolve_surface

What a package version ACTUALLY exports at runtime, extracted from its shipped JavaScript rather than from documentation or the model's memory: names and arity, not type signatures (use usage for those). Call before writing code against a package whose API may have moved. Runtime existence is what decides whether an import throws; a removed type breaks tsc, a removed runtime symbol breaks the program. A miss returns UNKNOWN and queues extraction, UNKNOWN never means the symbol is absent.

Parameters2

package	string	required	npm package name
version	string	optional	Exact version; omit for the latest extracted

Raw schema

{
  "type": "object",
  "properties": {
    "package": {
      "type": "string",
      "minLength": 1,
      "maxLength": 214,
      "pattern": "^(?:@[a-z0-9-][a-z0-9-._]*\\/)?[a-z0-9-][a-z0-9-._]*$",
      "description": "npm package name"
    },
    "version": {
      "type": "string",
      "description": "Exact version; omit for the latest extracted"
    }
  },
  "required": [
    "package"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

diff_surface

What changed in a package's runtime surface between two versions: symbols removed, added, and arity changes, plus renames the package itself proves (a removed name that shared one declaration with a name the new version still exports). Removals break `node`; type-only removals are returned separately because they break `tsc` instead. Answers "when did this stop working" from static comparison, with no install required. Use before an upgrade, and to explain a break after one.

Parameters3

package	string	required	npm package name
fromVersion	string	required	Version you are on
toVersion	string	required	Version you are moving to

Raw schema

{
  "type": "object",
  "properties": {
    "package": {
      "type": "string",
      "minLength": 1,
      "maxLength": 214,
      "pattern": "^(?:@[a-z0-9-][a-z0-9-._]*\\/)?[a-z0-9-][a-z0-9-._]*$",
      "description": "npm package name"
    },
    "fromVersion": {
      "type": "string",
      "description": "Version you are on"
    },
    "toVersion": {
      "type": "string",
      "description": "Version you are moving to"
    }
  },
  "required": [
    "package",
    "fromVersion",
    "toVersion"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

mcp_stack

Check whether a set of MCP servers can be wired into one agent together. The npm question does not apply — servers are separate processes with nothing to resolve between them. They clash in the single flat TOOL NAMESPACE the agent assembles from all of them: two servers exposing the same tool name leave the agent unable to express which it means, and nothing errors, one simply shadows the other. Also reports the standing context cost, since every tool's schema rides in every request. Pass `tools` for a server when you already hold its tool list (any server: remote, PyPI, Docker, private) and it is analysed as-is; otherwise the npm server's probed surface is used, and one that has not been probed makes the answer UNKNOWN, never clean.

Parameters1

servers

array

required

The servers configured into one agent

Raw schema

{
  "type": "object",
  "properties": {
    "servers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "server": {
            "type": "string",
            "minLength": 1,
            "maxLength": 300,
            "description": "npm package name of the MCP server, or any label when `tools` is given"
          },
          "version": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 100
              },
              {
                "type": "null"
              }
            ]
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 256
                },
                "annotations": {
                  "type": "object",
                  "additionalProperties": {}
                }
              },
              "required": [
                "name"
              ],
              "additionalProperties": false
            },
            "maxItems": 2000,
            "description": "The tool list as the agent received it; names and annotations are enough"
          }
        },
        "required": [
          "server"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 50,
      "description": "The servers configured into one agent"
    }
  },
  "required": [
    "servers"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

mcp_surface

What an MCP server ACTUALLY exposes: every tool, its required and optional parameters, and its behaviour annotations, read from a live `tools/list` handshake in a sandbox rather than from a README or the model's memory. Call before wiring an agent to a server, or when a tool call is failing for reasons the error does not explain. Also returns `requires` — the API keys and settings the server declares it needs — and `configRequest`, a ready-made line to put in front of your user when something is missing, so 'it needs a token' never presents as 'it is broken'. A miss returns UNKNOWN and queues a probe; UNKNOWN never means the server has no tools.

Parameters2

server	string	required	npm package name of the MCP server
version	string	optional	Exact version; omit for the latest probed

Raw schema

{
  "type": "object",
  "properties": {
    "server": {
      "type": "string",
      "minLength": 1,
      "maxLength": 214,
      "pattern": "^(?:@[a-z0-9-][a-z0-9-._]*\\/)?[a-z0-9-][a-z0-9-._]*$",
      "description": "npm package name of the MCP server"
    },
    "version": {
      "type": "string",
      "description": "Exact version; omit for the latest probed"
    }
  },
  "required": [
    "server"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

mcp_drift

What moved in an MCP server's tool contract between two versions: tools removed, parameters that became required, types narrowed, and annotation flips. Two findings here have no npm equivalent and are why this exists. SILENT DRIFT is a schema that changed while its description stayed byte-identical, invisible to anyone reading a changelog. PRIVILEGE WIDENING is a tool that stopped being read-only or started being destructive, which does not break anything and is worse than a break. Use before upgrading a server an agent depends on.

Parameters3

server	string	required	npm package name of the MCP server
fromVersion	string	required	Version you are on
toVersion	string	required	Version you are moving to

Raw schema

{
  "type": "object",
  "properties": {
    "server": {
      "type": "string",
      "minLength": 1,
      "maxLength": 214,
      "pattern": "^(?:@[a-z0-9-][a-z0-9-._]*\\/)?[a-z0-9-][a-z0-9-._]*$",
      "description": "npm package name of the MCP server"
    },
    "fromVersion": {
      "type": "string",
      "description": "Version you are on"
    },
    "toVersion": {
      "type": "string",
      "description": "Version you are moving to"
    }
  },
  "required": [
    "server",
    "fromVersion",
    "toVersion"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

connect_check

Before wiring an MCP server into a client, find out whether it will work there and exactly what it takes. Accepts an endpoint URL, an official-registry server name, or an npm package name. Answers per client (Claude Code, Claude.ai, ChatGPT, Cursor, VS Code, Codex, Gemini CLI and more): WORKS; NEEDS_SETUP with the steps (a key to send as a header, an OAuth client to pre-register and the redirect URIs to allow, a URL placeholder to fill); BLOCKED with the reason and which side causes it; or UNKNOWN when a decisive fact is not established. Built from a credential-free probe of the endpoint (whether it answers, how it authenticates, which OAuth registration methods it offers, spec deviations strict clients refuse, tool names and schemas) and from primary-sourced client constraints. Returns ready-to-paste config in each client's own format, with placeholder values. Tell the user what it found, including which client it was checked for. UNKNOWN never means it will not work.

Parameters2

server	string	required	Endpoint URL (https://…), official registry name (io.github.acme/weather), or npm package name
client	string	optional	One client to check, e.g. claude-code, cursor, chatgpt; omit for every client

Raw schema

{
  "type": "object",
  "properties": {
    "server": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048,
      "description": "Endpoint URL (https://…), official registry name (io.github.acme/weather), or npm package name"
    },
    "client": {
      "type": "string",
      "enum": [
        "claude-code",
        "claude-desktop",
        "claude-ai",
        "claude-api",
        "chatgpt",
        "openai-responses",
        "codex",
        "gemini-cli",
        "cursor",
        "vscode",
        "windsurf",
        "zed",
        "jetbrains-ai",
        "junie",
        "cline",
        "continue",
        "goose",
        "lovable",
        "replit",
        "bolt",
        "v0"
      ],
      "description": "One client to check, e.g. claude-code, cursor, chatgpt; omit for every client"
    }
  },
  "required": [
    "server"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

audit

Assess an entire project's dependencies in ONE call: which packages are outdated, deprecated or carry advisories for the exact installed version, and which configured MCP servers have drifted, need credentials, or cannot be observed at all. Send the inventory you read locally (names and versions only — never source). Returns a per-item verdict plus an explicit coverage count: how many were answered, how many are queued because the index has not seen them, and how many were skipped and why. An item lurq could not assess is reported as unassessed, never as clean.

Parameters2

packages	array	optional	npm dependencies read from package.json + lockfile
mcpServers	array	optional	MCP servers read from .mcp.json / agent configs

Raw schema

{
  "type": "object",
  "properties": {
    "packages": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 214,
            "pattern": "^(?:@[a-z0-9-][a-z0-9-._]*\\/)?[a-z0-9-][a-z0-9-._]*$"
          },
          "range": {
            "type": "string",
            "description": "Declared range, e.g. ^6.4.0"
          },
          "installed": {
            "type": [
              "string",
              "null"
            ],
            "description": "Resolved version from the lockfile or node_modules — what actually runs"
          }
        },
        "required": [
          "name"
        ],
        "additionalProperties": false
      },
      "maxItems": 600,
      "description": "npm dependencies read from package.json + lockfile"
    },
    "mcpServers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "alias": {
            "type": "string",
            "maxLength": 200
          },
          "kind": {
            "type": "string",
            "enum": [
              "npm-stdio",
              "remote",
              "local",
              "other-registry"
            ],
            "description": "How it launches; decides whether lurq can read its contract"
          },
          "packageName": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 300
              },
              {
                "type": "null"
              }
            ]
          },
          "version": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 100
              },
              {
                "type": "null"
              }
            ]
          },
          "endpoint": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 300
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "additionalProperties": false
      },
      "maxItems": 200,
      "description": "MCP servers read from .mcp.json / agent configs"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

capabilities

Look up which lurq tool answers a situation, and what to run next. Call when you're unsure whether lurq covers something (an upgrade, a licence rule, a version's exact exports, publishing a package) instead of guessing or skipping it. Returns matching capabilities with the tool or command to use.

Parameters1

query

string

optional

What you are trying to do, in plain words. Omit for the full menu.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "maxLength": 300,
      "description": "What you are trying to do, in plain words. Omit for the full menu."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

report_outcome

Opt-in feedback after you act on lurq's evidence about a package (verify, evaluate, compare, compat): whether you went with it and whether it built. No source code, only the coarse decision + a build signal. Helps lurq learn which packages agents actually succeed with; safe to skip.

Parameters4

package	string	required	The package you decided on
accepted	boolean	required	Did you go with this package?
buildSignal	string	optional	Coarse post-install result, if known
need	string	optional	What you needed the package for, in plain words (no source code)

Raw schema

{
  "type": "object",
  "properties": {
    "package": {
      "type": "string",
      "minLength": 1,
      "maxLength": 214,
      "pattern": "^(?:@[a-z0-9-][a-z0-9-._]*\\/)?[a-z0-9-][a-z0-9-._]*$",
      "description": "The package you decided on"
    },
    "accepted": {
      "type": "boolean",
      "description": "Did you go with this package?"
    },
    "buildSignal": {
      "type": "string",
      "enum": [
        "installed",
        "compiled",
        "tests_passed",
        "failed"
      ],
      "description": "Coarse post-install result, if known"
    },
    "need": {
      "type": "string",
      "maxLength": 500,
      "description": "What you needed the package for, in plain words (no source code)"
    }
  },
  "required": [
    "package",
    "accepted"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

README.md20 KBView on GitHub

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.

Install · For AI agents · MCP tools · CLI · Autopilot · Docs

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:

Opens lurq in your browser. Sign in and the key comes back to the terminal by itself.
Detects every coding agent on the machine.
Writes a keyed remote MCP entry for each, in the shape that agent expects.
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.

Claude Code plugin, no terminal needed:

text

/plugin marketplace add jadenryu/lurq
/plugin install lurq@lurq

One-click links for Cursor and VS Code are in the quickstart.

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. Run setup.

bash

npx lurqrun setup

In your shell it does not prompt: it prints a one-time sign-in link and exits right away. Give the user that link. When they sign in on this computer, lurq stores a key and connects every detected coding agent by itself. Never invent a key.

2. Or configure non-interactively when the user already has a key from lurq.run/dashboard/keys, or on a cloud, SSH or CI machine, where a sign-in link on this computer can't work:

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.

Some checks need no key at all. npx lurqrun check-upgrade --upgrade <package>@<from>..<to> compares an upgrade against the names your code actually imports, locally.

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

Writing the MCP config by hand

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>" }

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 · 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.

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

# Finding your way
lurq can "will this upgrade break my code" # which capability answers this?

Full reference: CLI docs.

Autopilot

lurq keeps a repository's dependencies current, and names the code an upgrade breaks before it merges.

The check reads the symbol-level API diff between versions and matches it against what your code actually references. It needs no tests.

code

blocking   a referenced symbol or deep import disappears,
           or require() of a now-ESM package breaks         → the code will throw
warning    a call's argument count no longer fits, a new type
           error, or a Node / peer version the repo lacks   → it may misbehave or not build
ok         nothing referenced is affected
unverified could not be established                         → never counted as safe

Step	Runs on	Needs
1. `lurq upgrade-plan`: drift, plus what each upgrade removes	your runner	lurq key
2. `lurq check-upgrade`: matched against your source, with `file:line`	your runner	nothing
3. `lurq fix`: applies what the package itself proves — renames, and the range bump in every manifest	your runner	nothing
4. `claude-code-action`: migrates what a rule cannot, and runs your tests	your runner	Anthropic credential
5. `create-pull-request`: one branch, one PR	your runner	`GITHUB_TOKEN`
6. Outcomes post back: names and counts, never source	lurq	nothing

Three modes, and editing is opt-in. The workflow starts in comment: it plans, checks, writes the brief to the run summary, and changes nothing. fix opens a pull request containing only what the package itself proves — renamed call sites, and the range bump in every manifest — so it needs no Anthropic credential, and it is what a newly armed repo gets. pr is fix plus the agent, for the changes a rule cannot make. Step 4 above is the only one that needs a model, so only pr does.

The dashboard setting governs repos that already installed the workflow: each run reads the mode from the plan response rather than from the committed file.

Cadence follows scope — weekly for the scopes that track breakage, since majors arrive slowly enough that a daily run mostly reports nothing new; daily for a repo set to advisories-only, because weekly can mean seven days sitting on a known CVE.

Trust model. lurq's GitHub App holds Contents: read-only and Actions: write. It can read your manifests and start the workflow you committed — it cannot write a byte to your repository, change this file, or set a repository variable. Every write is made by the workflow itself using your own ephemeral GITHUB_TOKEN, bounded by the permissions: block in the file you control. The agent's allowlist is Read,Edit,Write,Bash(<pkg-manager>:*), so it edits files but never touches version control. Removing it is git rm .github/workflows/lurq-upgrade.yml.

What leaves your machine

Package names and versions, never your source code. audit receives the inventory your agent reads locally, check-upgrade matches symbols against your code on your own runner, and outcomes report names and counts only.

lurq mcp-scan is the one exception worth knowing: by default it records what your MCP servers expose (tool names, descriptions and parameters, with secrets redacted) to your account, so it can tell you what changed. --no-upload keeps the scan on your machine.

Where the evidence comes from

Readable: npm, GitHub, deps.dev and OSV, re-synced daily. Downloads, release cadence, maintenance, advisories, deprecations, license and bundle cost.

Executed: an isolated sandbox installs and imports package versions and records the results in a compatibility matrix. compat reads those edges alongside declared peer and engine ranges, which is why lurq can say whether a whole stack holds together.

Ranking is deterministic and public. No model sits in the scoring path:

code

health    = maintenance 0.35 · adoption 0.30 · reliability 0.25 · efficiency 0.10
quality   = types · tests · docs · changelog · dep count · license · provenance
composite = blend at a single tunable λ (default 0.35)

Every weight lives in src/scoring/weights.ts and prints with lurq weights.

Plans

Plan	Price	Hosted calls
Free	$0	1,000 a month
Pro	$15/mo	10,000 a month
Team	$25/seat/mo, 3-seat minimum	15,000 per seat, pooled
Business	from $1,000/mo	Uncapped, with SSO and audit export

Past the limit, calls slow to 20 a day rather than stopping. The CLI run against your own database is never metered. Details: pricing.

Uninstall, reinstall, and where setup writes

Setup is safe to re-run: npx lurqrun again overwrites the previous entries.

bash

lurq uninstall                  # MCP entries, agent instructions, the stored key
lurq uninstall --agent cursor   # just one agent
npm uninstall -g lurqrun        # then remove the `lurq` command

It lists what it will remove and asks first (--yes skips the question).

Agent	MCP config	Instructions
Claude Code	`~/.claude.json`	`~/.claude/skills/lurq/SKILL.md`
Cursor	`~/.cursor/mcp.json`	none (tool descriptions carry the guidance)
Windsurf	`~/.codeium/windsurf/mcp_config.json`	`~/.codeium/windsurf/memories/global_rules.md`
VS Code / Copilot	`<VS Code user dir>/mcp.json`	none
Codex	`~/.codex/config.toml`	`~/.codex/AGENTS.md`
Gemini CLI	`~/.gemini/settings.json`	`~/.gemini/GEMINI.md`
Antigravity	`~/.gemini/config/mcp_config.json`	`~/.gemini/GEMINI.md`
Kiro	`~/.kiro/settings/mcp.json`	`~/.kiro/steering/lurq.md`

lurq logout only clears the CLI's stored key. A copy stays in each MCP entry until lurq uninstall removes it, and the key keeps working until you revoke it in the dashboard.

Self-hosting

lurq runs against your own Postgres too: lurq serve (stdio MCP) or lurq serve-http (a rate-limited HTTP service), with DATABASE_URL set. The published CLI installs only what hosted use needs; the first self-hosting command prints the exact npm install line for the server packages. Guide: self-hosting.

Contact

Inquiries, partnerships or proposals: jadenryu@lurq.run

License

MIT

Install

Tools (16)

evaluatepolicycomparecompatverifyusagediagramresolve_surface

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://api.lurq.run/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "lurq": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.lurq.run/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

io.github.jadenryu/lurq MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

evaluate

policy

compare

compat

verify

usage

diagram

resolve_surface

diff_surface

mcp_stack

mcp_surface

mcp_drift

connect_check

audit

capabilities

report_outcome

lurq

Why your agent needs this

Install

For AI agents

When to call lurq

MCP tools

CLI

Autopilot

What leaves your machine

Where the evidence comes from

Plans

Contact

License

Install

Remote endpoint

Related servers