MCP-сервер, который превращает дифф lock-файла в читаемый план обновления пакетов.
Направьте своего ИИ-ассистента (Cursor, Claude Desktop, Claude Code) на Dependabot PR, на вывод npm outdated или на любую пару версий пакетов — и получите ранжированный план обновления: класс semver, ломающие изменения из релизных заметок GitHub, CVE, исправленные в диапазоне версий, ссылки на руководства по миграции и чёткую рекомендацию по каждому пакету.
Одна команда — на уровне пользователя (доступно в каждом проекте):
claude mcp add -s user dep-diff -- npx -y @digicatalyst/dep-diff-mcpНа уровне проекта (записывает .mcp.json в корень репозитория, общий для команды):
claude mcp add -s project dep-diff -- npx -y @digicatalyst/dep-diff-mcpС явным токеном (пропустите этот шаг, если CLI gh уже авторизован — см. Токен GitHub ниже):
claude mcp add -s user --env GITHUB_TOKEN=ghp_xxx dep-diff -- npx -y @digicatalyst/dep-diff-mcpПроверка:
claude mcp listПерезапустите сессию Claude Code, чтобы сервер подхватился.
Добавьте в конфигурацию вашего MCP-клиента:
Cursor: ~/.cursor/mcp.json
Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или %APPDATA%\Claude\claude_desktop_config.json (Windows)
{
"mcpServers": {
"dep-diff": {
"command": "npx",
"args": ["-y", "@digicatalyst/dep-diff-mcp"]
}
}
}Перезапустите MCP-клиента. Спросите что-то вроде «что тут рискованного в этом Dependabot PR?» — и инструменты будут вызваны автоматически.
Размещённый экземпляр работает по адресу https://dep-diff.digicatalyst.ca/mcp по протоколу streamable HTTP, так что от пакета npm можно полностью отказаться:
claude mcp add -s user -t http dep-diff https://dep-diff.digicatalyst.ca/mcpИли в конфигурации клиента:
{
"mcpServers": {
"dep-diff": {
"type": "http",
"url": "https://dep-diff.digicatalyst.ca/mcp"
}
}
}Если нужны более высокие лимиты запросов, передайте токен GitHub в URL с параметром ?githubToken=ghp_xxx. Размещённый экземпляр не сохраняет состояние и не ведёт логи ваших запросов — см. PRIVACY.md. Если вы предпочитаете, чтобы токен никогда не покидал вашу машину, запускайте пакет npm локально.
Related MCP server: PatchEvergreen MCP Server
Сервер обращается к GitHub API, чтобы читать релизные заметки. Без токена доступно 60 запросов в час (анонимный лимит GitHub) — этого достаточно для отдельных запросов по одному пакету, но недостаточно для массового анализа lock-файла.
Сервер определяет токен в следующем порядке:
Переменная окружения GITHUB_TOKEN, если она задана.
gh auth token — если GitHub CLI установлен и авторизован, сервер использует этот токен автоматически. Изменять конфигурацию не нужно.
Анонимный доступ (60 запросов/час).
ghЕсли у вас уже установлен gh (brew install gh && gh auth login), на этом можно остановиться — сервер сам подхватит вашу текущую авторизацию. Токен нигде не хранится в открытом виде.
Создайте fine-grained токен на странице https://github.com/settings/tokens:
Имя токена: dep-diff-mcp
Срок действия: 90 дней (периодически перевыпускайте)
Доступ к репозиториям: Public Repositories (read-only) — без доступа к приватным репозиториям
Разрешения: только публичное чтение по умолчанию — не выдавайте области repo, workflow, user или любые другие разрешения на запись
Затем укажите токен в конфигурации MCP:
{
"mcpServers": {
"dep-diff": {
"command": "npx",
"args": ["-y", "@digicatalyst/dep-diff-mcp"],
"env": { "GITHUB_TOKEN": "github_pat_xxx" }
}
}
}Этот конфигурационный файл хранится на вашем диске в открытом виде. Держите права доступа жёсткими (chmod 600) и не вставляйте токен в AI-чаты, issues или общие демонстрации экрана — записи таких сессий часто сохраняются.
Токен в конфиге должен иметь наименьшие привилегии (только чтение публичных репозиториев). Даже при утечке он сможет прочитать только те публичные данные, которые вы и так можете прочитать.
Периодически перевыпускайте токены. Отзывайте любой токен, который мог быть раскрыт, на https://github.com/settings/tokens.
Сервер никогда не выводит токен в stdout/stderr и не включает его в ответ (response payload).
analyze_package_changeАнализирует обновление одного пакета. Входные данные: ecosystem (npm или pypi), name, fromVersion, toVersion.
analyze_packages_bulkАнализирует до 50 обновлений пакетов параллельно. Возвращает пакеты, отсортированные по уровню риска (security > caution > review > likely-safe > safe), плюс сводные счётчики по категориям.
Классификация semver — major / minor / patch / downgrade / unknown
Ломающие изменения — извлечённые из заголовков релизных заметок GitHub
Исправления безопасности — CVE, присутствующие в fromVersion, но устранённые в toVersion (через OSV)
Ссылки для миграции — URL руководств по обновлению, найденные в релизных заметках
Рекомендация — вердикт в одну строку + уровень риска
npm
PyPI
npm install
npm run build
GITHUB_TOKEN=ghp_xxx npm run inspect # MCP InspectorMIT
Given one package and two versions (from -> to), returns a structured upgrade analysis: semver classification, GitHub release notes summary, detected breaking changes, security advisories fixed in the range, migration guide links, and a clear recommendation. Use when the user asks about a specific package upgrade ('what changed between react 18 and 19', 'is it safe to bump axios from 0.27 to 1.0', 'what does upgrading lodash 4.17.20 to 4.17.21 fix'). Supports npm, pypi, and github-actions (use the action reference as the name, e.g. actions/checkout). For analyzing many packages at once or a Dependabot batch, use analyze_packages_bulk instead.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Package name (e.g. 'react', 'requests') | |
| ecosystem | Yes | Package ecosystem | |
| toVersion | Yes | Target version (e.g. '19.0.0') | |
| fromVersion | Yes | Current version (e.g. '18.2.0') |
| Name | Required | Description |
|---|---|---|
| package | Yes | Package name that was analyzed |
| repoUrl | Yes | Source repository URL, or null when none could be resolved |
| ecosystem | Yes | Package ecosystem |
| toVersion | Yes | Version being upgraded to |
| fromVersion | Yes | Version being upgraded from |
| semverClass | Yes | Semver relationship between the two versions |
| releaseCount | Yes | Number of GitHub releases found strictly between the two versions |
| securityFixes | Yes | Advisories affecting fromVersion that are resolved at toVersion |
| migrationLinks | Yes | Migration or upgrade guide URLs found in release notes |
| recommendation | Yes | Single-line verdict explaining the recommendation level |
| breakingChanges | Yes | Breaking changes extracted from release notes; empty when none were found |
| releaseExcerpts | No | Raw release-note excerpts, present only as a fallback when a major/minor bump yielded no breaking changes |
| recommendationLevel | Yes | Risk classification, used to rank packages in bulk results |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly, idempotent, and non-destructive behavior, so the description does not need to restate those. It adds useful behavioral context by enumerating the analysis components returned (semver classification, release notes, breaking changes, advisories, migration links, recommendation) and by specifying supported ecosystems and the github-actions naming convention. No contradiction with annotations is present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences carry the full message with no filler: the core action and output are front-loaded, examples make the intended queries concrete, and the sibling tool handoff is compressed into a single clause. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides all essential invocation context: required inputs, output content, supported ecosystems, and when to choose the sibling tool instead. Output schema and annotations already cover return structure and safety semantics, so nothing critical is missing for correct selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter has a basic description, so the baseline is solid. The description adds meaningful semantic detail beyond the schema: concrete version examples and the rule that github-actions names should use the action reference like 'actions/checkout'. This extra guidance helps an agent supply correctly formatted parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('returns a structured upgrade analysis') and identifies the exact resource: one package plus a from/to version pair. It clearly distinguishes itself from the sibling analyze_packages_bulk by emphasizing the single-dependency scope. There is no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly gives the trigger condition: use when the user asks about a specific package upgrade, backed by concrete example queries. It also names the alternative analyze_packages_bulk for many packages or Dependabot batches, making the routing decision unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyzes a list of package upgrades in parallel and returns a unified risk report with packages ranked by recommendation level (security > caution > review > likely-safe > safe). Use when the user provides many dependency changes from a Dependabot PR, npm outdated output, lockfile diff, or batch upgrade. Returns: total count, breakdown by semver class, total security fixes found, packages with breaking changes, and per-package details. Limit 50 packages per call (chunk larger lists).
| Name | Required | Description | Default |
|---|---|---|---|
| changes | Yes | List of package changes to analyze |
| Name | Required | Description |
|---|---|---|
| packages | Yes | Per-package results, ranked security > caution > review > likely-safe > safe |
| bySemverClass | Yes | Breakdown of the batch by semver class |
| totalPackages | Yes | Number of package changes submitted |
| securityFixesTotal | Yes | Total security advisories resolved across the whole batch |
| packagesWithBreakingChanges | Yes | How many packages had at least one breaking change |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral detail beyond the annotations: it discloses parallel execution, the unified risk report structure, the explicit recommendation ordering (security > caution > review > likely-safe > safe), the returned aggregates, and the 50-package limit with a chunking instruction. The readOnlyHint, openWorldHint, and idempotentHint are already provided by annotations, and the description does not contradict them. This is a strong, transparent behavioral profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly structured: purpose first, then use case, then return content, then a practical limit. It is four sentences with no filler, and every sentence adds information an agent needs to invoke correctly or set expectations. The limit and chunking guidance is efficiently placed at the end.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one well-schematized parameter, a rich output schema, and annotations covering safety and idempotency, the description is complete. It covers what the tool does, common triggers, output content, and operational constraints (parallel, 50-item limit, chunking). Nothing an agent needs to decide between this and the singular sibling is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3; the schema already documents the 'changes' array and the ecosystem enum. The description adds contextual color by calling the items 'package upgrades' and referencing batch sources, but it does not add significant semantic detail about the fromVersion or toVersion fields, which remain self-explanatory. This meets the adequate threshold without exceeding the schema-driven baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Analyzes a list of package upgrades in parallel and returns a unified risk report with packages ranked by recommendation level.' It clearly distinguishes itself from the singular sibling tool by explicitly targeting 'many dependency changes' and listing concrete batch sources like Dependabot PRs, npm outdated output, lockfile diffs, and batch upgrades. The ranking order further clarifies the tool's specific output, leaving no ambiguity about what it does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear when-to-use context: 'Use when the user provides many dependency changes from a Dependabot PR, npm outdated output, lockfile diff, or batch upgrade.' This strongly implies that single changes belong to the sibling analyze_package_change tool, but it does not explicitly name the alternative or state a when-not condition. That is a clear usage context without formal exclusions, so it misses the top score only slightly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.3.2analyze_package_change2 fields changedInput schema / properties / ecosystem / enumPrevious value: -[
- "npm",
- "pypi"
-]New value: +[
+ "npm",
+ "pypi",
+ "github-actions"
+]Output schema / (root)Previous value: -nullNew value: +{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "additionalProperties": false,
+ "properties": {
+ "breakingChanges": {
+ "description": "Breaking changes extracted from release notes; empty when none were found",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "ecosystem": {
+ "description": "Package ecosystem",
+ "enum": [
+ "npm",
+ "pypi",
+ "github-actions"
+ ],
+ "type": "string"
+ },
+ "fromVersion": {
+ "description": "Version being upgraded from",
+ "type": "string"
+ },
+ "migrationLinks": {
+ "description": "Migration or upgrade guide URLs found in release notes",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "package": {
+ "description": "Package name that was analyzed",
+ "type": "string"
+ },
+ "recommendation": {
+ "description": "Single-line verdict explaining the recommendation level",
+ "type": "string"
+ },
+ "recommendationLevel": {
+ "description": "Risk classification, used to rank packages in bulk results",
+ "enum": [
+ "safe",
+ "likely-safe",
+ "review",
+ "caution",
+ "security"
+ ],
+ "type": "string"
+ },
+ "releaseCount": {
+ "description": "Number of GitHub releases found strictly between the two versions",
+ "type": "number"
+ },
+ "releaseExcerpts": {
+ "description": "Raw release-note excerpts, present only as a fallback when a major/minor bump yielded no breaking changes",
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "excerpt": {
+ "description": "Short excerpt of the release notes",
+ "type": "string"
+ },
+ "tag": {
+ "description": "Release tag the excerpt came from",
+ "type": "string"
+ }
+ },
+ "required": [
+ "tag",
+ "excerpt"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "repoUrl": {
+ "description": "Source repository URL, or null when none could be resolved",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "securityFixes": {
+ "description": "Advisories affecting fromVersion that are resolved at toVersion",
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "id": {
+ "description": "Advisory identifier (e.g. 'GHSA-29mw-wpgm-hmr9' or a CVE)",
+ "type": "string"
+ },
+ "severity": {
+ "description": "Severity as reported by OSV (e.g. 'LOW', 'MODERATE', 'HIGH', 'CRITICAL')",
+ "type": "string"
+ },
+ "summary": {
+ "description": "One-line description of the advisory",
+ "type": "string"
+ }
+ },
+ "required": [
+ "id",
+ "summary",
+ "severity"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "semverClass": {
+ "description": "Semver relationship between the two versions",
+ "enum": [
+ "major",
+ "minor",
+ "patch",
+ "downgrade",
+ "unknown"
+ ],
+ "type": "string"
+ },
+ "toVersion": {
+ "description": "Version being upgraded to",
+ "type": "string"
+ }
+ },
+ "required": [
+ "package",
+ "ecosystem",
+ "fromVersion",
+ "toVersion",
+ "semverClass",
+ "repoUrl",
+ "releaseCount",
+ "breakingChanges",
+ "securityFixes",
+ "migrationLinks",
+ "recommendation",
+ "recommendationLevel"
+ ],
+ "type": "object"
+}analyze_packages_bulk2 fields changedInput schema / properties / changes / items / properties / ecosystem / enumPrevious value: -[
- "npm",
- "pypi"
-]New value: +[
+ "npm",
+ "pypi",
+ "github-actions"
+]Output schema / (root)Previous value: -nullNew value: +{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "additionalProperties": false,
+ "properties": {
+ "bySemverClass": {
+ "additionalProperties": false,
+ "description": "Breakdown of the batch by semver class",
+ "properties": {
+ "major": {
+ "description": "Count of major bumps",
+ "type": "number"
+ },
+ "minor": {
+ "description": "Count of minor bumps",
+ "type": "number"
+ },
+ "patch": {
+ "description": "Count of patch bumps",
+ "type": "number"
+ }
+ },
+ "required": [
+ "major",
+ "minor",
+ "patch"
+ ],
+ "type": "object"
+ },
+ "packages": {
+ "description": "Per-package results, ranked security > caution > review > likely-safe > safe",
+ "items": {
+ "anyOf": [
+ {
+ "additionalProperties": false,
+ "properties": {
+ "breakingChanges": {
+ "description": "Breaking changes extracted from release notes; empty when none were found",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "ecosystem": {
+ "description": "Package ecosystem",
+ "enum": [
+ "npm",
+ "pypi",
+ "github-actions"
+ ],
+ "type": "string"
+ },
+ "fromVersion": {
+ "description": "Version being upgraded from",
+ "type": "string"
+ },
+ "migrationLinks": {
+ "description": "Migration or upgrade guide URLs found in release notes",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "package": {
+ "description": "Package name that was analyzed",
+ "type": "string"
+ },
+ "recommendation": {
+ "description": "Single-line verdict explaining the recommendation level",
+ "type": "string"
+ },
+ "recommendationLevel": {
+ "description": "Risk classification, used to rank packages in bulk results",
+ "enum": [
+ "safe",
+ "likely-safe",
+ "review",
+ "caution",
+ "security"
+ ],
+ "type": "string"
+ },
+ "releaseCount": {
+ "description": "Number of GitHub releases found strictly between the two versions",
+ "type": "number"
+ },
+ "releaseExcerpts": {
+ "description": "Raw release-note excerpts, present only as a fallback when a major/minor bump yielded no breaking changes",
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "excerpt": {
+ "description": "Short excerpt of the release notes",
+ "type": "string"
+ },
+ "tag": {
+ "description": "Release tag the excerpt came from",
+ "type": "string"
+ }
+ },
+ "required": [
+ "tag",
+ "excerpt"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "repoUrl": {
+ "description": "Source repository URL, or null when none could be resolved",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "securityFixes": {
+ "description": "Advisories affecting fromVersion that are resolved at toVersion",
+ "items": {
+ "additionalProperties": false,
+ "properties": {
+ "id": {
+ "description": "Advisory identifier (e.g. 'GHSA-29mw-wpgm-hmr9' or a CVE)",
+ "type": "string"
+ },
+ "severity": {
+ "description": "Severity as reported by OSV (e.g. 'LOW', 'MODERATE', 'HIGH', 'CRITICAL')",
+ "type": "string"
+ },
+ "summary": {
+ "description": "One-line description of the advisory",
+ "type": "string"
+ }
+ },
+ "required": [
+ "id",
+ "summary",
+ "severity"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "semverClass": {
+ "description": "Semver relationship between the two versions",
+ "enum": [
+ "major",
+ "minor",
+ "patch",
+ "downgrade",
+ "unknown"
+ ],
+ "type": "string"
+ },
+ "toVersion": {
+ "description": "Version being upgraded to",
+ "type": "string"
+ }
+ },
+ "required": [
+ "package",
+ "ecosystem",
+ "fromVersion",
+ "toVersion",
+ "semverClass",
+ "repoUrl",
+ "releaseCount",
+ "breakingChanges",
+ "securityFixes",
+ "migrationLinks",
+ "recommendation",
+ "recommendationLevel"
+ ],
+ "type": "object"
+ },
+ {
+ "additionalProperties": false,
+ "properties": {
+ "error": {
+ "description": "Why the analysis could not be completed",
+ "type": "string"
+ },
+ "package": {
+ "description": "Package name whose analysis failed",
+ "type": "string"
+ },
+ "recommendationLevel": {
+ "const": "review",
+ "description": "Always 'review' — a package that could not be analyzed cannot be cleared automatically",
+ "type": "string"
+ }
+ },
+ "required": [
+ "package",
+ "error",
+ "recommendationLevel"
+ ],
+ "type": "object"
+ }
+ ]
+ },
+ "type": "array"
+ },
+ "packagesWithBreakingChanges": {
+ "description": "How many packages had at least one breaking change",
+ "type": "number"
+ },
+ "securityFixesTotal": {
+ "description": "Total security advisories resolved across the whole batch",
+ "type": "number"
+ },
+ "totalPackages": {
+ "description": "Number of package changes submitted",
+ "type": "number"
+ }
+ },
+ "required": [
+ "totalPackages",
+ "bySemverClass",
+ "securityFixesTotal",
+ "packagesWithBreakingChanges",
+ "packages"
+ ],
+ "type": "object"
+}v0.1.1analyze_package_changeanalyze_packages_bulkScored across 2 tools
The two tools are clearly separated by scope: one handles a single package upgrade, the other handles multiple packages in bulk. Each description explicitly references the other, so an agent can unambiguously choose based on input size.
Both tools follow the same analyze_package_* pattern, with the singular 'change' and plural 'bulk' clearly differentiating them. This is a consistent and predictable verb_noun convention.
Two tools is minimal, but the server's narrow purpose of dependency upgrade analysis is well served by one individual and one bulk entry point. It is slightly thin but not unreasonable for the domain.
The pair covers both single-package and multi-package analysis, which covers most workflows. A minor gap is the lack of direct lockfile/diff parsing, but users can supply the package list from those sources.
Check exact npm/PyPI upgrades for evidence-backed breaking changes; query APIs and components.
Scan packages and lockfiles (npm, PyPI, Go, Maven, Cargo, NuGet) for vulnerabilities and malware.
Risk-scan a diff, flag AI-generated-code tells, find secrets. 5 of 7 tools need no account.
npm/PyPI/Django dependency upgrades: security, runtime compatibility, migration, package ranking.