4da-mcp-server

@4da/mcp-server

为 AI 编码 Agent 提供升级情报。 在 Agent 升级依赖之前，它会根据你自己的锁文件，在你的机器上了解你当前使用的版本与目标版本之间有哪些变化、会影响哪些文件，以及此次升级能修复哪些漏洞。此外，还提供与 osv-scanner 同等能力的漏洞扫描、排序后的升级计划和决策记忆。零配置，无需账户。

You:     "Upgrade axum to 0.8"
Agent →  upgrade_impact { package: "axum", to_version: "0.8.4" }

         axum 0.7.9 -> 0.8.4: 5 releases (0.8.2 yanked), changelog from the 0.8.4 crate.
         12 breaking entries, 8 touch your code (Path, Query, Router, extract, serve):
           breaking  Remove OptionalFromRequestParts impl for `Query`        (you use Query)
           breaking  Require `Sync` for all handlers added to `Router`       (you use Router)
           ...
         Your code: 10 files import axum.

（真实输出，已删节，基于本仓库于 2026-10-02 运行。）

一条命令即可安装。无需 API 密钥，无需账户。你的代码绝不会离开你的机器。

安装

需要 Node.js 22 或更高版本。

该服务使用 Node 内置的 node:sqlite（Node 22.13 及更高版本），因此不需要安装脚本，也兼容 npm 12 默认阻止安装脚本的行为。在 Node 22.0-22.12 上，它会使用可选的 better-sqlite3，其原生模块由 npm 10 和 11 在安装时构建。运行 npx @4da/mcp-server --doctor 可查看当前使用的是哪一种。

claude mcp add 4da -- npx @4da/mcp-server

作为 Claude Code 插件（MCP 服务加钩子）：

claude plugin marketplace add 4DA-Systems/4da-mcp-server
claude plugin install 4da@4da

当 Agent 在 package.json、Cargo.toml、pyproject.toml、requirements.txt 或 go.mod 中修改依赖版本时，钩子会告知哪些软件包发生了变动，并提供确切的 dependency_check 和 upgrade_impact 调用，要求 Agent 在安装和构建之前执行。该钩子使用纯 Node，不会连接任何地方，其他编辑操作也不会触发任何提示。

{
  "mcpServers": {
    "4da": {
      "command": "npx",
      "args": ["@4da/mcp-server"]
    }
  }
}

{
  "servers": {
    "4da": {
      "type": "stdio",
      "command": "npx",
      "args": ["@4da/mcp-server"]
    }
  }
}

{
  "mcpServers": {
    "4da": {
      "command": "npx",
      "args": ["@4da/mcp-server"]
    }
  }
}

npx @4da/mcp-server --setup --dry-run   # show each file and entry, write nothing
npx @4da/mcp-server --setup

然后询问你的 AI：“将 X 升级到 Y 会有哪些变化？”、“扫描漏洞”或“我应该先升级什么？”

工作原理

该服务会读取其启动目录下项目的每个锁文件，包括根目录下方独立锁定的项目（例如，src-tauri/Cargo.lock 与根目录的 pnpm-lock.yaml 并列的仓库会被整体扫描），并跳过 .gitignore 排除的内容：package-lock.json / npm-shrinkwrap.json、pnpm-lock.yaml（v5–v9）、yarn.lock（v1 和 berry）、bun.lock、Cargo.lock（包括 Cargo 工作区）、poetry.lock、uv.lock、pdm.lock、Pipfile.lock、requirements 固定版本文件（*requirements*.txt、requirements/*.txt，包括 -r 和 -c）、go.mod / go.sum（Go 的构建列表）、Gemfile.lock（RubyGems；git 和路径 gem 是本地代码，不是发行版）以及 composer.lock（Packagist）。文件夹中的每个 Python 源文件都会被读取，而不只是第一个。每个已安装副本都会被扫描，而不是每个名称只扫描一个版本，并采用锁文件自身的 dev 标记。每当锁文件发生变化时，服务都会重新读取；对于 npm，还会检查 node_modules 中实际安装的内容。遍历会深入 4 层，最多扫描 256 个项目。未纳入扫描的内容，以及所有没有锁文件的清单文件（其声明的版本范围并非已安装内容，因此不会扫描），都会列在回答的 coverage 块中，绝不会悄然省略。未读取其清单文件的生态系统（Maven pom.xml、Gradle、.NET *.csproj / packages.lock.json、Pub、Hex、SwiftPM、CocoaPods：coverage.not_covered），存在但无法读取的锁文件（合并冲突标记、无效 JSON：coverage.unreadable_lockfiles），以及测试夹具目录（tests/、test/、fixtures/、testdata/、__fixtures__/、conformance/ 等）中的锁文件也会列出；除非传入 include_test_fixtures: true，否则这些目录不会作为项目自身内容扫描（coverage.not_scanned）。

不完整的回答绝不会被视为干净。 当 OSV.dev 无法回答某些依赖项的查询时（服务中断、HTTP 错误、超时、查询预算用尽），vulnerability_scan 会以 summary: "NOT CHECKED: ... N of M dependencies have no vulnerability answer" 开头，在 coverage.unchecked_dependencies 中统计这些依赖项，并将 total_vulnerable_packages 和 by_severity 设为 null（已检查部分的结果位于 found_in_checked_dependencies）；dependency_health 不会提供评分和漏洞数量，upgrade_planner 则会将 vulnerabilityDataAvailable: false 设为 false。大型依赖树会根据 OSV 的预算分批查询，每批 1,000 个，因此超过 10,000 个依赖项的树也会得到完整回答。

在 19 个公开仓库（npm、pnpm v5-v9、yarn v1 和 berry、bun、Cargo、Poetry、uv、Pipfile、requirements、Go；2026-10-10）上与 osv-scanner 对比，所有差异均由 OSV 自身的 API 判定：19,115 条结果的精确率为 1.00；在该工具会读取的锁文件中，召回 19,116 条中的 19,115 条（不会读取 Maven/Gradle）。新纳入读取的 requirements 文件也通过 pip-audit 进行了检查。

• OSV.dev：用于查询已知漏洞，并与精确的已安装版本匹配
• npm 注册表、crates.io、PyPI、Go 模块代理（registry.npmjs.org、crates.io 和 index.crates.io、pypi.org、proxy.golang.org）：用于查询版本、弃用状态和撤回状态
• npm 下载量（api.npmjs.org）：用于提供 dependency_health 的每周下载量数据
• 软件包自身的注册表归档（registry.npmjs.org、static.crates.io、files.pythonhosted.org、proxy.golang.org）：用于读取 upgrade_impact 所需的变更日志；只有在选择启用下文所述的 FOURDA_GITHUB_CHANGELOG=true 时才会使用 GitHub
• npm 完整 packument、crates.io 版本 API、PyPI JSON API 和 Go 代理的版本列表：供 dependency_check 使用（发布时间、撤回状态和 yanked 状态；在 npm 和 crates.io 上还包括发布者、安装脚本和各版本的依赖项）。这些请求只携带软件包名称；除 Go 代理的版本列表不包含日期，因此会针对正在评估的版本请求 .info（与 go get 发出的请求相同）外，绝不会向注册表发送已安装的版本。软件包的 OSV.dev 公告列表可让 dependency_check 在约束条件中列出安全版本。packument 会缓存在磁盘上，并通过 If-None-Match 重新验证；对 crates.io API 的读取请求间隔为每秒一次。
• Hacker News Algolia API（hn.algolia.com）：仅在调用 ecosystem_pulse 时使用
• GitHub（api.github.com、raw.githubusercontent.com）：仅在设置 FOURDA_GITHUB_CHANGELOG=true 时使用
• 你的嵌入服务提供商：仅在配置语义召回时使用（本地 Ollama URL 或 api.openai.com；见下文）

这些就是该服务会联系的所有主机。

结果会按数据来源进行限流，并缓存一段时间（注册表数据缓存 24 小时，漏洞数据缓存 1 小时，新闻缓存 30 分钟）。

**通过网络发送的内容：**软件包名称和版本（与锁定文件中可见的数据相同）；仅对于 ecosystem_pulse，还会将你的少数几个依赖项名称作为搜索词发送。不会发送源代码、文件路径或个人数据。upgrade_impact 的调用点扫描在本地运行。设置 FOURDA_OFFLINE=true 可禁用所有网络调用。

**GitHub 发行说明（选择启用，默认关闭）。**许多软件包的注册表归档中不包含变更日志（vite、zod、cobra 和大多数 Go 模块都如此）。在服务的环境中设置 FOURDA_GITHUB_CHANGELOG=true 后，如果归档中没有对应版本范围的变更日志，upgrade_impact 就会读取该代码库的 GitHub 发行版信息（对于 PyPI 软件包，则会先读取项目通过其 project_urls 链接的 GitHub 变更日志文件）。此时 GitHub 会收到代码库名称和版本，不会收到其他内容。服务使用未经身份验证的 REST API（每小时 60 次请求），或在设置 GITHUB_TOKEN 时使用该令牌（每小时 5,000 次请求）；达到速率限制时会报告重置时间，不会在循环中重试，并且结果会被缓存。关闭此功能时，如果回答中没有变更日志，服务会如实说明并指出相关设置；不会进行猜测。

写入磁盘的内容及位置：仅写入服务自身拥有的文件，存放于用户数据目录下的服务文件夹中（%LOCALAPPDATA%\4da-mcp、~/Library/Application Support/4da-mcp 或 ~/.local/share/4da-mcp；可通过 FOURDA_MCP_HOME 更改位置）：cache.db（注册表、OSV 和变更日志响应；可安全删除）和 standalone.db（未使用桌面应用时：项目扫描结果，以及你记录的决策、Agent 记忆和反馈）。不会在你的代码库中写入任何内容。 安装 4DA 桌面应用后，服务会通过只读连接读取应用的数据库（4da.db），绝不会在其中创建或修改任何内容：没有表、没有列，也没有缓存。唯一的写入操作是向工具要填充的四个应用自有表中写入行，以便应用能够看到这些内容：决策（decision_memory -> developer_decisions）、Agent 记忆（agent_memory）和反馈（record_feedback -> interactions 和 feedback，应用的校准功能会读取这些内容）。这些写入通过单独的写入连接进行，该连接会短暂等待应用释放锁。如果你的应用版本缺少记录所需的表或列，该记录会改写入 standalone.db，并在 _meta 中说明。（6.1 之前，服务还会在应用数据库中创建 live_cache 表；现在则将该缓存保存在 cache.db 中。）

**配置和数据库的来源：**如果已设置 FOURDA_DB_PATH，则使用该路径（相对路径会基于服务的工作目录解析，且必须指向已有文件；若绝对路径指向的文件不存在，且其所在目录存在，则会将其创建为新的独立数据库，并在第一个工具响应的 _meta.database_note 中说明；否则会拒绝并报错）；否则使用桌面应用数据目录中的数据库；再否则使用服务自己的 standalone.db。嵌入设置来自 FOURDA_SETTINGS_PATH；若未设置，则来自与 FOURDA_DB_PATH 同目录的 settings.json；再否则来自桌面应用的数据目录。服务不会从其启动目录读取任何内容：在 6.2.5 之前，工作目录中或其旁边的 data/settings.json 或 data/4da.db 会被采用，因此克隆的仓库可能会将语义检索重定向到其选择的任意主机，或植入“决策”。

唯一例外是：如果你明确为语义检索配置了 OpenAI 嵌入提供方（FOURDA_EMBED_PROVIDER=openai），你存储的决策／记忆文本会发送给 OpenAI 进行嵌入。默认情况下——不使用嵌入提供方，或使用本地 Ollama 提供方——所有内容都保留在你的设备上；无论如何，FOURDA_OFFLINE=true 都会覆盖这些设置。

**支持的生态系统：**npm、crates.io（Rust）、PyPI（Python）、Go；vulnerability_scan 还会读取 RubyGems（Gemfile.lock）和 Packagist（composer.lock）。不会读取 Maven、Gradle 和 .NET，并将其列为不在覆盖范围内。upgrade_impact 会读取 npm、crates.io、PyPI 和 Go。PyPI：版本和日期来自 PyPI JSON API，变更日志来自该版本的 sdist；导入位置则根据发行包安装的模块进行匹配：优先从虚拟环境的元数据中读取（.venv、venv、env：top_level.txt 或 RECORD），其次使用一张常见差异表（PyYAML -> yaml、Pillow -> PIL），否则使用发行包名称，并在答案中将其标记为推测。Go：版本和日期来自 proxy.golang.org，变更日志来自模块 zip；如果主版本为 2 或更高，则会将其报告为模块路径的变化（github.com/jackc/pgx/v4 -> /v5），并列出导入旧路径的文件。dependency_check 也会读取上述四种生态系统；对于 PyPI 和 Go，由于注册表不提供发布者身份或安装钩子信息，这些信号会标注为“不适用”。 明确说明已知限制： 不带锁文件的 requirements.txt 只列出直接固定的依赖项，因此不会扫描它们的传递依赖（请使用 uv lock、poetry lock 或 pip-compile）。许多软件包在其注册表归档中不附带变更日志（fastembed、vite、zod 等就是如此）；此时，upgrade_impact 会说明这一点，并提供发行说明 URL，而不是妄加猜测。系统会根据变更日志的标题和措辞标记破坏性变更，并为每条记录附上其所属标题（under）。在涵盖 npm、crates.io、PyPI 和 Go 的 40 次真实升级样本中进行测量（共 1,618 条记录，三位盲评者根据原文证据给出基准标注；样本和测量结果均在测试套件中）：在规则制定期间未使用的 20 次升级中，被标记为破坏性变更的记录有 95% 确实属于破坏性变更（95% CI 89-98%），约 72% 的破坏性变更记录被标记出来；以散文形式撰写的 Go 发行说明效果最弱（召回率约为 54%）。请将这些标记视为预排序结果：重大版本升级的每条记录都要阅读。每个回答都会在 _meta.classification 中说明这一点。

你可以询问的内容

"What changes if I upgrade axum to 0.8?"      -> upgrade_impact
"Check my dependency health"                  -> dependency_health
"Scan for vulnerabilities"                    -> vulnerability_scan
"Which deps should I upgrade first?"          -> upgrade_planner
"Is it safe to bump axios to 1.14.1?"         -> dependency_check
"Pin ws to a 7.x version"                     -> dependency_check (to: "7.x")
"I'm about to bump fastembed 5 -> 7"          -> what_should_i_know
"What's happening in the ecosystem?"          -> ecosystem_pulse
"What's my tech stack?"                       -> get_context
"Record a decision: we chose Postgres"        -> decision_memory
"Does switching to MySQL align?"              -> check_decision_alignment
"Remember: never use ORM for batch inserts"   -> agent_memory

全部 16 个工具

依赖项安全

智能分析

决策与记忆

身份

* 需使用 4DA 桌面应用 才能获取完整数据。

提示词：deps

由用户调用的工作流（支持 MCP 提示词的宿主会将其显示为斜杠命令）。它会指示 Agent 运行 upgrade_planner，用 dependency_check 检查每项拟议的升级；分小批次仅应用 proceed 项，并在每批之后运行项目自己的测试；停止处理并报告每项 review / avoid / wait / unknown 项及其证据；最后重新运行 vulnerability_scan。可选参数 scope（例如 security only）。

独立模式与完整模式

MCP 服务无需桌面应用即可运行。它会在用户数据文件夹（%LOCALAPPDATA%\4da-mcp、~/Library/Application Support/4da-mcp 或 ~/.local/share/4da-mcp，绝不会放在你的代码库内）中保留一个小型本地数据库，并在每次启动时扫描你的项目：

下载 4DA，体验完整功能。

传输方式

stdio（默认）——适用于所有 MCP 主机：

npx @4da/mcp-server

Streamable HTTP——适用于远程或多客户端场景：

npx @4da/mcp-server --http --port 4840

HTTP 传输默认绑定到 127.0.0.1，并对每个请求应用 Host 标头 DNS 重绑定防护。若要将其暴露到本机之外，则需要共享密钥：

MCP_AUTH_SECRET=<same value as the relay's JWT_SECRET> \
MCP_ALLOWED_HOSTS=mcp.internal \
  npx @4da/mcp-server --http --host 0.0.0.0

如果未设置 MCP_AUTH_SECRET，启动时会拒绝非环回绑定。设置后，每个请求都必须携带 Bearer 令牌，其 HMAC-SHA256 签名必须通过该密钥验证；令牌的角色也会针对每个工具进行强制执行（viewer 为只读；member 和 admin 可以写入）。请在其前方配置 TLS。

HTTP 模式为单租户。 系统会验证令牌的 team_id，但不会用它来隔离数据：所有通过身份验证的客户端共享同一个数据库、一份 Agent 记忆和一组决策，并且 project_path 允许任何通过身份验证的客户端扫描服务器可读取的任意目录。每个团队（或每个信任边界）运行一个服务，并且只允许你愿意授予此类访问权限的客户端连接。

CLI 参考

npx @4da/mcp-server              # Start server (stdio)
npx @4da/mcp-server --http       # Start server (Streamable HTTP)
npx @4da/mcp-server --setup      # Auto-configure your editors
npx @4da/mcp-server --doctor     # Verify installation health
npx @4da/mcp-server --version    # Print version

环境变量

常见问题

这会把我的代码发送到其他地方吗？ 不会。该服务会向公共 API 发送包名称和版本（OSV.dev、npm registry、crates.io、PyPI、Go proxy），通过包自身的注册表下载目标版本的归档文件以执行 upgrade_impact（只有在设置 FOURDA_GITHUB_CHANGELOG=true 时才会读取 GitHub 发布说明），并且仅在调用 ecosystem_pulse 时，才会将少量依赖名称作为搜索词发送到 HN Algolia。不会发送源代码、文件路径或个人数据：调用点扫描在本地运行。设置 FOURDA_OFFLINE=true 可禁用所有网络调用。（唯一例外是选择启用的 OpenAI 嵌入向量，详见上文的网络说明。）

我需要安装 4DA 桌面应用吗？ 不需要。11 个工具可独立运行：升级影响分析、安装前依赖检查、漏洞扫描、依赖健康度、升级规划、生态系统新闻、任务前简报、项目上下文、决策记忆、对齐检查和 Agent 记忆。桌面应用是日常运行同一引擎的地方：在这台机器上的所有项目间共享一个工作清单、了解技术栈变更的晨间简报，以及升级计划。安装后，你的 Agent 还能使用另外 5 个工具：信号、知识缺口、根据你的技术栈评估的开发者新闻、Developer DNA 和反馈。

它兼容哪些 AI 工具？ 任何支持 MCP 的工具：Claude Code、Claude Desktop、Cursor、Windsurf、VS Code（Copilot）以及任何自定义 MCP 客户端。

从源代码构建

git clone https://github.com/4DA-Systems/4da-mcp-server.git
cd 4da-mcp-server
pnpm install
pnpm build
pnpm test    # offline

许可证

Apache License 2.0（Apache-2.0）。请参阅 LICENSE。

由 4DA 构建