{
  "markdown": "# UpgradeLens\n\n**Evidence-backed dependency upgrade intelligence for AI coding agents.**\n\nAnonymous free evaluation quota — no signup and no API key required. Read-only.\nnpm and PyPI only.\n\n> Release status: v0.4.1 is deployed on the public Worker with every v0.3.1\n> route and tool retained. The official MCP Registry serves v0.4.1 through a\n> signed-tag GitHub OIDC release; Bazaar indexing remains pending.\n\nOne deterministic, source-cited call answers: *should this dependency move from\nversion A to version B, and what must be handled?*\n\n- **Remote MCP:** `https://upgradelens.mattpicone.workers.dev/mcp` (streamable HTTP)\n- **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)\n- **Decisions:** `proceed | review_required | block | unknown` — `unknown` rather than fabricated certainty\n- **Action gate:** edit dependency files only when `action_allowed` is `true`; target discovery always requires a follow-up check\n- **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.\n\n## Install\n\n### GitHub dependency pull requests\n\n```yaml\nname: UpgradeLens dependency review\non:\n  pull_request:\n    types: [opened, synchronize, reopened]\npermissions:\n  contents: read\n  id-token: write\njobs:\n  review:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n        with:\n          fetch-depth: 0\n      - uses: mattpicone/upgradelens-action@v0\n        with:\n          max-spend-usd: \"0.03\"\n```\n\nThe [UpgradeLens Action](https://github.com/mattpicone/upgradelens-action)\nhandles Dependabot, Renovate, and ordinary dependency PRs. It receives one\nrepository-bound free review per rolling 30 days through GitHub OIDC, uploads\nno repository source, and can automatically pay for additional $0.01 reviews\nwhen a compatible wallet secret is configured.\n\n### Cursor\n\n[Add UpgradeLens to Cursor](https://cursor.com/install-mcp?name=upgradelens&config=eyJ1cmwiOiJodHRwczovL3VwZ3JhZGVsZW5zLm1hdHRwaWNvbmUud29ya2Vycy5kZXYvbWNwIn0=)\n(official `cursor.com/install-mcp` installer; also works as\n`cursor://anysphere.cursor-deeplink/mcp/install?name=upgradelens&config=eyJ1cmwiOiJodHRwczovL3VwZ3JhZGVsZW5zLm1hdHRwaWNvbmUud29ya2Vycy5kZXYvbWNwIn0=`).\n\nOr add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):\n\n```json\n{\n  \"mcpServers\": {\n    \"upgradelens\": {\n      \"url\": \"https://upgradelens.mattpicone.workers.dev/mcp\"\n    }\n  }\n}\n```\n\nA checked-in example is at [`examples/cursor/.cursor/mcp.json`](examples/cursor/.cursor/mcp.json).\nThis is a docs/config install, not a Cursor Marketplace listing.\n\n### Claude Code\n\n```bash\nclaude mcp add --transport http upgradelens https://upgradelens.mattpicone.workers.dev/mcp\n```\n\n### Codex CLI\n\n```bash\ncodex mcp add upgradelens --url https://upgradelens.mattpicone.workers.dev/mcp\n```\n\nOr configure it directly:\n\n```toml\n# ~/.codex/config.toml\n[mcp_servers.upgradelens]\nurl = \"https://upgradelens.mattpicone.workers.dev/mcp\"\n```\n\nThe CLI install path was verified end-to-end on 2026-08-30 with Codex\n`0.150.0-alpha.8`: enabled connection, tool discovery, and a real\n`check_dependency_upgrade` call. The verification used an environment-backed\nowner Bearer token so it could not count as business demand; public evaluation\ninstalls need no token.\n\n### Gemini CLI\n\nThis repository includes `gemini-extension.json` and `GEMINI.md`:\n\n```bash\ngemini extensions install https://github.com/mattpicone/upgradelens\n```\n\nThe Gemini extension gallery indexes public repos that have the\n`gemini-cli-extension` GitHub topic. That topic is set on this repository;\ngallery listing is a separate crawl and is not claimed here.\n\n### GitHub Copilot Agent Plugins\n\n```bash\ncopilot plugin install mattpicone/upgradelens\n```\n\nPortable Agent Plugins 1.0 `plugin.json` plus Copilot's root `.mcp.json` are\nchecked in and point at the remote HTTPS server. The existing `mcp.json` remains\nfor other Agent Plugins-compatible clients. No credential is embedded.\nMaintainer-directory indexing is separate from these files.\n\n### Microsoft APM\n\n```bash\napm install --mcp io.github.mattpicone/upgradelens --transport http\n```\n\n### PydanticAI\n\n```python\nfrom pydantic_ai import Agent\nfrom pydantic_ai.mcp import MCPServerStreamableHTTP\n\nserver = MCPServerStreamableHTTP(\"https://upgradelens.mattpicone.workers.dev/mcp\")\nagent = Agent(\"your-model\", toolsets=[server])\n```\n\n### LangChain / LangGraph\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\n\nclient = MultiServerMCPClient({\n    \"upgradelens\": {\n        \"transport\": \"streamable_http\",\n        \"url\": \"https://upgradelens.mattpicone.workers.dev/mcp\",\n    }\n})\ntools = await client.get_tools()\n```\n\n### Plain REST\n\n```bash\ncurl -X POST https://upgradelens.mattpicone.workers.dev/v1/upgrade/review \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"ecosystem\": \"npm\",\n    \"package\": \"express\",\n    \"current_version\": \"4.19.2\",\n    \"target_version\": \"5.1.0\",\n    \"runtime\": {\"node\": \"22\"},\n    \"detail\": \"compact\"\n  }'\n```\n\nOne anonymous evaluation unit is shared across MCP and REST for a rolling\n30-day network identity. When paid mode is enabled, additional units use x402\nv2 USDC at $0.01 per analysis (10,000 atomic USDC); the public endpoint stays\nfail-closed in validation until the external testnet acceptance gate is\nrecorded. `POST /v1/keys` is intentionally retired.\n\n## MCP tools\n\n| Tool | Use when | Do not use when |\n|---|---|---|\n| `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 |\n| `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 |\n| `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 |\n| `plan_dependency_upgrade` | A target is selected and you need ordered, source-cited migration actions | General tutorials |\n\nResponse (abbreviated):\n\n```json\n{\n  \"next_action\": \"review_migration_plan\",\n  \"billing\": {\n    \"mode\": \"validation\",\n    \"units\": 1,\n    \"price_usd\": 0.01,\n    \"trial_remaining\": null,\n    \"network\": null,\n    \"payment_status\": \"validation_free\"\n  },\n  \"decision\": \"review_required\",\n  \"action_allowed\": false,\n  \"risk_score\": 37,\n  \"latest_stable\": \"5.2.1\",\n  \"security_delta\": {\n    \"advisories_fixed_by_target\": [{\"id\": \"GHSA-qw6h-vgh9-j6wx\", \"aliases\": [\"CVE-2024-43796\"]}]\n  },\n  \"compatibility\": {\n    \"runtime_supported\": true,\n    \"dependency_changes\": {\"added\": [\"router\"], \"removed\": [\"depd\"], \"changed\": []}\n  },\n  \"reasons\": [\"Major version jump (4.19.2 -> 5.1.0).\", \"Upgrade fixes 1 known advisory: GHSA-qw6h-vgh9-j6wx.\"],\n  \"coverage\": {\"registry\": {\"status\": \"complete\"}, \"osv\": {\"status\": \"complete\"}},\n  \"evidence\": [{\"id\": \"ev_...\", \"source_type\": \"osv\", \"source_url\": \"https://osv.dev/vulnerability/GHSA-qw6h-vgh9-j6wx\", \"fetched_at\": \"...\"}],\n  \"confidence\": 0.95,\n  \"freshness\": \"...\"\n}\n```\n\n## Why call this instead of doing it yourself?\n\nAn 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:\n\n- **security delta** (advisories affecting current vs. fixed by / still affecting target — including \"this target is itself affected, pick a newer one\"),\n- **runtime compatibility** (`engines.node` / `requires_python` evaluated against your runtime),\n- **direct dependency diff** between the two versions,\n- **yanked/deprecated/EOL flags**,\n- **documented breaking changes** (deterministically extracted from official release notes, with URLs),\n- **provenance for every claim**, cacheable and repeatable.\n\n## Architecture\n\nCloudflare 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).\n\n## API stability\n\nVersioned under `/v1`. Response schemas only gain fields; existing fields are not repurposed. `analysis_version` identifies scoring-logic revisions.\n\n## License\n\nMIT — see [LICENSE](LICENSE). Security policy: [SECURITY.md](SECURITY.md).\n",
  "bytes": 9023,
  "sha": "9558a1ad77a7746751709776062d137fce25ebcf125b8a8a3fd38025a3c33c37",
  "repo_slug": "mattpicone/upgradelens",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mattpicone_upgradelens_6ebe189b/readme"
}