UpgradeLens
npm/PyPI/Django dependency upgrades: security, runtime compatibility, migration, package ranking.
Open source Repository Open in the app JSON README (API)
About
npm/PyPI/Django dependency upgrades: security, runtime compatibility, migration, package ranking.
Details
- Kind
- MCP servers
- Topic
- Developer tools
- Publisher
- mattpicone
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.4.1
- Last push
- 2026-09-06T23:03:41Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:00:29
- Updated
- 2026-09-07 16:08:39
- Origin id
io.github.mattpicone/upgradelens
README
# UpgradeLens
**Evidence-backed dependency upgrade intelligence for AI coding agents.**
Anonymous free evaluation quota — no signup and no API key required. Read-only.
npm and PyPI only.
> Release status: v0.4.1 is deployed on the public Worker with every v0.3.1
> route and tool retained. The official MCP Registry serves v0.4.1 through a
> signed-tag GitHub OIDC release; Bazaar indexing remains pending.
One deterministic, source-cited call answers: *should this dependency move from
version A to version B, and what must be handled?*
- **Remote MCP:** `https://upgradelens.mattpicone.workers.dev/mcp` (streamable HTTP)
- **REST:** [`/openapi.json`](https://upgradelens.mattpicone.workers.dev/openapi.json) · [`/llms.txt`](https://upgradelens.mattpicone.workers.dev/llms.txt) · [`/pricing.json`](https://upgradelens.mattpicone.workers.dev/pricing.json)
- **Decisions:** `proceed | review_required | block | unknown` — `unknown` rather than fabricated certainty
- **Action gate:** edit dependency files only when `action_allowed` is `true`; target discovery always requires a follow-up check
- **Sources:** [deps.dev](https://deps.dev), [OSV.dev](https://osv.dev), [registry.npmjs.org](https://registry.npmjs.org), [pypi.org](https://pypi.org), [endoflife.date](https://endoflife.date). Every semantic claim carries evidence with a source URL and fetch timestamp.
## Install
### GitHub dependency pull requests
```yaml
name: UpgradeLens dependency review
on:
pull_request:
types: [opened, synchronize, reopened]
permissions:
contents: read
id-token: write
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: mattpicone/upgradelens-action@v0
with:
max-spend-usd: "0.03"
```
The [UpgradeLens Action](https://github.com/mattpicone/upgradelens-action)
handles Dependabot, Renovate, and ordinary dependency PRs. It receives one
repository-bound free review per rolling 30 days through GitHub OIDC, uploads
no repository source, and can automatically pay for additional $0.01 reviews
when a compatible wallet secret is configured.
### Cursor
[Add UpgradeLens to Cursor](https://cursor.com/install-mcp?name=upgradelens&config=eyJ1cmwiOiJodHRwczovL3VwZ3JhZGVsZW5zLm1hdHRwaWNvbmUud29ya2Vycy5kZXYvbWNwIn0=)
(official `cursor.com/install-mcp` installer; also works as
`cursor://anysphere.cursor-deeplink/mcp/install?name=upgradelens&config=eyJ1cmwiOiJodHRwczovL3VwZ3JhZGVsZW5zLm1hdHRwaWNvbmUud29ya2Vycy5kZXYvbWNwIn0=`).
Or add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
```json
{
"mcpServers": {
"upgradelens": {
"url": "https://upgradelens.mattpicone.workers.dev/mcp"
}
}
}
```
A checked-in example is at [`examples/cursor/.cursor/mcp.json`](examples/cursor/.cursor/mcp.json).
This is a docs/config install, not a Cursor Marketplace listing.
### Claude Code
```bash
claude mcp add --transport http upgradelens https://upgradelens.mattpicone.workers.dev/mcp
```
### Codex CLI
```bash
codex mcp add upgradelens --url https://upgradelens.mattpicone.workers.dev/mcp
```
Or configure it directly:
```toml
# ~/.codex/config.toml
[mcp_servers.upgradelens]
url = "https://upgradelens.mattpicone.workers.dev/mcp"
```
The CLI install path was verified end-to-end on 2026-08-30 with Codex
`0.150.0-alpha.8`: enabled connection, tool discovery, and a real
`check_dependency_upgrade` call. The verification used an environment-backed
owner Bearer token so it could not count as business demand; public evaluation
installs need no token.
### Gemini CLI
This repository includes `gemini-extension.json` and `GEMINI.md`:
```bash
gemini extensions install https://github.com/mattpicone/upgradelens
```
The Gemini extension gallery indexes public repos that have the
`gemini-cli-extension` GitHub topic. That topic is set on this repository;
gallery listing is a separate crawl and is not claimed here.
### GitHub Copilot Agent Plugins
```bash
copilot plugin install mattpicone/upgradelens
```
Portable Agent Plugins 1.0 `plugin.json` plus Copilot's root `.mcp.json` are
checked in and point at the remote HTTPS server. The existing `mcp.json` remains
for other Agent Plugins-compatible clients. No credential is embedded.
Maintainer-directory indexing is separate from these files.
### Microsoft APM
```bash
apm install --mcp io.github.mattpicone/upgradelens --transport http
```
### PydanticAI
```python
from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStreamableHTTP
server = MCPServerStreamableHTTP("https://upgradelens.mattpicone.workers.dev/mcp")
agent = Agent("your-model", toolsets=[server])
```
### LangChain / LangGraph
```python
from langchain_mcp_adapters.client import MultiServerMCPClient
client = MultiServerMCPClient({
"upgradelens": {
"transport": "streamable_http",
"url": "https://upgradelens.mattpicone.workers.dev/mcp",
}
})
tools = await client.get_tools()
```
### Plain REST
```bash
curl -X POST https://upgradelens.mattpicone.workers.dev/v1/upgrade/review \
-H 'content-type: application/json' \
-d '{
"ecosystem": "npm",
"package": "express",
"current_version": "4.19.2",
"target_version": "5.1.0",
"runtime": {"node": "22"},
"detail": "compact"
}'
```
One anonymous evaluation unit is shared across MCP and REST for a rolling
30-day network identity. When paid mode is enabled, additional units use x402
v2 USDC at $0.01 per analysis (10,000 atomic USDC); the public endpoint stays
fail-closed in validation until the external testnet acceptance gate is
recorded. `POST /v1/keys` is intentionally retired.
## MCP tools
| Tool | Use when | Do not use when |
|---|---|---|
| `review_dependency_upgrade` | **Preferred:** review an exact Dependabot, Renovate, npm, or PyPI version change and return one compact decision plus cited migration actions | The target or current version is unknown, or the task is outside npm/PyPI |
| `check_dependency_upgrade` | You are about to change a package from a known current version to a known target version and need verified compatibility/vulnerability/EOL/breaking-change evidence before editing dependency files | Merely installing a package or searching docs |
| `find_safe_upgrade_target` | A dependency should be upgraded but the target version is not yet known — returns ranked candidates that must each be checked | The target version is already chosen, or as authorization to edit dependency files |
| `plan_dependency_upgrade` | A target is selected and you need ordered, source-cited migration actions | General tutorials |
Response (abbreviated):
```json
{
"next_action": "review_migration_plan",
"billing": {
"mode": "validation",
"units": 1,
"price_usd": 0.01,
"trial_remaining": null,
"network": null,
"payment_status": "validation_free"
},
"decision": "review_required",
"action_allowed": false,
"risk_score": 37,
"latest_stable": "5.2.1",
"security_delta": {
"advisories_fixed_by_target": [{"id": "GHSA-qw6h-vgh9-j6wx", "aliases": ["CVE-2024-43796"]}]
},
"compatibility": {
"runtime_supported": true,
"dependency_changes": {"added": ["router"], "removed": ["depd"], "changed": []}
},
"reasons": ["Major version jump (4.19.2 -> 5.1.0).", "Upgrade fixes 1 known advisory: GHSA-qw6h-vgh9-j6wx."],
"coverage": {"registry": {"status": "complete"}, "osv": {"status": "complete"}},
"evidence": [{"id": "ev_...", "source_type": "osv", "source_url": "https://osv.dev/vulnerability/GHSA-qw6h-vgh9-j6wx", "fetched_at": "..."}],
"confidence": 0.95,
"freshness": "..."
}
```
## Why call this instead of doing it yourself?
An agent can combine deps.dev + OSV + registries + changelogs manually — this service exists to compress those 5–7 fetch/normalize/reconcile steps into one deterministic call with:
- **security delta** (advisories affecting current vs. fixed by / still affecting target — including "this target is itself affected, pick a newer one"),
- **runtime compatibility** (`engines.node` / `requires_python` evaluated against your runtime),
- **direct dependency diff** between the two versions,
- **yanked/deprecated/EOL flags**,
- **documented breaking changes** (deterministically extracted from official release notes, with URLs),
- **provenance for every claim**, cacheable and repeatable.
## Architecture
Cloudflare Worker (TypeScript/Hono) + D1 (SQLite). Version-pair analyses are cached by `(ecosystem, package, from, to, runtime, analysis_version)`. Breaking-change facts are precomputed by a scheduled GitHub Actions job using deterministic extraction from official release notes — no LLM calls at runtime, ever. See [docs/OPERATIONS.md](docs/OPERATIONS.md).
## API stability
Versioned under `/v1`. Response schemas only gain fields; existing fields are not repurposed. `analysis_version` identifies scoring-logic revisions.
## License
MIT — see [LICENSE](LICENSE). Security policy: [SECURITY.md](SECURITY.md).