Upgradelens MCP Server

UpgradeLens

Evidence-backed dependency upgrade intelligence for AI coding agents.

One deterministic, source-cited call answers: should this dependency move from version A to version B, and what must be handled? — instead of separately combining registry metadata, OSV vulnerability queries, dependency graphs, runtime constraints, EOL data, changelogs and release notes.

• Ecosystems: npm, PyPI
• Remote MCP endpoint: https://upgradelens.mattpicone.workers.dev/mcp (streamable HTTP)
• REST API: /openapi.json · /llms.txt · /pricing.json
• Decisions: proceed | review_required | block | unknown — unknown is returned rather than fabricated certainty
• Action gate: agents may edit dependency files only when action_allowed is true; target discovery always requires a follow-up check
• Sources: deps.dev, OSV.dev, registry.npmjs.org, pypi.org, endoflife.date. Every semantic claim carries evidence with a source URL and fetch timestamp.
• Read-only: the service never executes commands, never clones repos, never fetches caller-supplied URLs.
• Free evaluation quota, no signup. Higher limits with an instant free key (POST /v1/keys).

MCP tools

Setup

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "upgradelens": {
      "url": "https://upgradelens.mattpicone.workers.dev/mcp"
    }
  }
}

Claude Code

claude mcp add --transport http upgradelens https://upgradelens.mattpicone.workers.dev/mcp

Codex CLI

# ~/.codex/config.toml
[mcp_servers.upgradelens]
url = "https://upgradelens.mattpicone.workers.dev/mcp"

PydanticAI

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

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

curl -X POST https://upgradelens.mattpicone.workers.dev/v1/upgrade/check \
  -H 'content-type: application/json' \
  -d '{
    "ecosystem": "npm",
    "package": "express",
    "current_version": "4.19.2",
    "target_version": "5.1.0",
    "runtime": {"node": "20.11.0"}
  }'

Response (abbreviated):

{
  "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.

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. Security policy: SECURITY.md.