企业官网建设流程全解析

n8n-mcp 贡献指南：本地开发环境、测试体系与自动化发布全流程

【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp

本指南基于 n8n-mcp 仓库的 CONTRIBUTING.md 编写，面向想要为该项目提交代码、修复 Bug 或新增能力的开发者，以及需要维护与发布版本的仓库维护者。读完本文，你将掌握 n8n-mcp 从 Fork 仓库、搭建本地开发环境、运行完整测试套件到通过 GitHub Actions 完成自动化发布（GitHub Release、npm 包、Docker 镜像）的完整链路，并能对照源码理解每一步背后的实现细节。

贡献流程总览

n8n-mcp 欢迎一切形式的贡献。官方推荐的工作流如下：

1. Fork 仓库：将仓库复制到自己的账号下。
2. 允许维护者推送：创建 PR 时勾选 "Allow edits by maintainers"，让维护者可以直接在你的分支上做小幅调整，显著加快评审速度。
3. 创建功能分支：

   git checkout -b feature/your-feature

4. 完成代码修改。
5. 运行测试：npm test。
6. 提交 Pull Request。

从仓库的 .github/workflows/test.yml 可以看到，所有 PR 和 push 到main分支的提交都会自动触发 CI 测试流水线，因此提交 PR 前先在本地跑通测试，能避免无谓的 CI 失败。CI 对文档类改动（**.md、docs/**等）做了paths-ignore过滤，纯文档 PR 不会触发全量测试，可以放心提交。

本地开发环境搭建

环境前置要求

初始化步骤

# 1. 克隆仓库 git clone <项目主页地址> n8n-mcp cd n8n-mcp # 2. 克隆 n8n 官方文档仓库（可选但推荐） # 放置到上级目录 ../n8n-docs，用于生成节点文档数据 git clone <n8n-docs 仓库地址> ../n8n-docs # 3. 安装依赖并构建 npm install npm run build # 4. 初始化节点数据库 npm run rebuild # 5. 启动服务 npm start # stdio 模式，面向 Claude Desktop 等本地 MCP 客户端 npm run start:http # HTTP 模式，用于远程访问

第 4 步的npm run rebuild对应 package.json 中的node dist/scripts/rebuild.js，它会将 n8n 节点元数据解析并写入 SQLite 数据库（仓库中的data/nodes.db），这是 MCP 服务器提供节点搜索、文档查询能力的数据基础。仓库还提供了更轻量的变体npm run rebuild:optimized（对应dist/scripts/rebuild-optimized.js），以及 Docker 环境下专用的提取脚本 scripts/extract-from-docker.js 和 scripts/extract-nodes-docker.sh。

开发命令详解

package.json 中的 scripts 字段是开发期的"命令字典"，核心命令如下：

# 构建与校验 npm run build # 用 tsc 编译 TypeScript（tsc -p tsconfig.build.json） npm run rebuild # 重建节点数据库（依赖 dist/ 存在，需先 build） npm run validate # 校验节点数据，包含 critical-node 关键节点检查 npm test # 运行全部测试（vitest） # 依赖更新 npm run update:n8n:check # 检查 n8n 相关依赖是否有新版本（dry-run） npm run update:n8n # 更新 n8n 系列依赖 # 启动服务 npm run dev # 开发模式：build + rebuild + validate 一次到位 npm run dev:http # HTTP 开发模式，nodemon 监听 src 自动重载

依赖更新背后的同步机制

update:n8n值得单独说明，它对应 scripts/update-n8n-deps.js。该脚本以n8n@latest的依赖清单为唯一事实来源（npm view n8n@latest dependencies --json），跟踪n8n-nodes-base、n8n-core、n8n-workflow、@n8n/n8n-nodes-langchain四个子包：

• 采用精确锁定版本（不带^），确保数据库重建时依赖可复现，避免未来 minor 版本悄悄改变节点集合；
• 内置防降级保护：若当前版本高于 n8n 官方锁定值则跳过，因为 n8n 的子包latestdist-tag 并不同步，直接按 tag 查询曾导致误降级；
• 更新 package.json 后还会同步 Dockerfile 中的构建依赖 pin（syncDockerfilePins方法），防止 Docker 构建阶段因版本漂移而出现类型编译失败或 zod peer 冲突。

测试体系

测试命令矩阵

npm test # 运行所有测试 npm run test:coverage # 带覆盖率报告的测试 npm run test:watch # 监听模式 npm run test:unit # 仅单元测试（tests/unit） npm run test:integration # 仅集成测试（--config vitest.config.integration.ts）

测试架构

从 vitest.config.ts 可以读出几个关键的工程决策：

• 测试环境强制N8N_MCP_TELEMETRY_DISABLED: 'true'，确保 CI 生成的遥测数据不会污染生产项目；
• 覆盖率高门槛（lines/functions/statements 均要求 75%，branches 要求 70%），不达标会失败；
• retry: 0—— 不掩盖 flaky 测试，而是要求修复；
• 线程池默认最多 4 个 worker，可用TEST_MAX_WORKERS环境变量调节。

CI 流水线的分层策略

.github/workflows/test.yml 展示了 CI 的完整设计：

1. 单元测试：npm run test:unit，带覆盖率报告；
2. 构建 dist：先npm run build，因为部分集成测试会以子进程方式启动真实入口（如tests/integration/mcp/stdio-*.test.ts），没有 dist 时它们会自动跳过；
3. Docker 测试镜像预构建：单独一步npm run docker:test:build，continue-on-error: true降级为跳过而非阻塞 PR；
4. 离线集成测试：排除 n8n-api 与 ai-validation 套件，任何 PR（含 Dependabot 与 fork PR）都必须通过；
5. 在线集成测试：只有配置了N8N_API_URL和N8N_API_KEY两个 secret（HAS_N8N_INSTANCE判定）才运行，且 secret 只作用于此步骤；
6. CJS 运行时回归：独立的cjs-runtimejob 用 Node 严格 CJS 加载器验证编译产物（对应 scripts/smoke-cjs-runtime.js），防止 ESM-only 依赖混入 CommonJS 发布包。

测试结果通过dorny/test-reporter以 JUnit 格式回写到 PR checks，并生成 test-summary 评论与 coverage 制品（上传 Codecov 与 Actions Artifacts）。本地开发时可以参照 tests/setup/TEST_ENV_DOCUMENTATION.md 配置.env.test与可选的.env.test.local（后者不应提交）。

自动化发布流程（维护者专用）

n8n-mcp 的发布是"版本号即触发器"：当package.json或package.runtime.json的版本变化被推送到main分支时，.github/workflows/release.yml 自动接管，完成 GitHub Release、npm 发布、多平台 Docker 镜像构建和文档更新。完整设计见 docs/AUTOMATED_RELEASES.md。

推荐：引导式发布

# 引导式发布准备（交互式脚本） npm run prepare:release # 验证发布自动化本身（不触发真实发布） npm run test:release-automation

scripts/prepare-release.js 是一个交互式 CLI，完整流程为：输入新版本（严格 semver 校验，且必须大于当前版本）→ 更新package.json与package.runtime.json（通过npm run sync:runtime-version）→ 将docs/CHANGELOG.md的 Unreleased 内容迁移到新版本节 → 依次运行npm test、npm run build、npm run rebuild、npm run typecheck→ 创建 git 提交 → 询问是否推送。推送前会显示"破坏性操作"警告并要求输入RELEASE确认，避免误触公开发布。

手动发布流程

# 1. 更新版本号 # 编辑 package.json 的 version 字段 # 然后同步运行包版本 npm run sync:runtime-version # 2. 更新变更日志 # 编辑 docs/CHANGELOG.md，遵守 Keep a Changelog 格式： # ## [2.10.0] - 2025-08-02 # ### Added / Changed / Fixed 三段式 # 3. 测试并提交 npm test npm run build npm run rebuild git add package.json package.runtime.json docs/CHANGELOG.md git commit -m "chore: release vX.Y.Z" git push

发布流水线的七个环节

release.yml 中的 job 依赖关系清晰地描述了发布编排：

1. 版本检测（detect-version-change）：对比HEAD~1与当前package.json的版本，识别 alpha/beta/rc/dev 预发布版本，并与 npm registry 校验版本必须递增且未发布过；
2. 生成发布说明（generate-release-notes）：基于上一个 git tag 调用 scripts/generate-release-notes.js（首次发布则用 scripts/generate-initial-release-notes.js）；
3. 创建 GitHub Release（create-release）：创建带注释的vX.Y.Ztag，预发布版本自动加--prerelease标志，发布正文包含安装指引；
4. 打包 MCPB 包（package-mcpb）：npm run generate:mcpb-manifest生成清单后，用@anthropic-ai/mcpb校验并打包，作为 release 资产上传；
5. 构建验证（build-and-verify）：npm run build:all（同步 skills + 构建 UI + 编译 TS），并强制检查data/nodes.db已提交（CI 上重建会因内存压力段错误）；
6. npm 发布（publish-npm）：使用 npmTrusted Publishers（OIDC）认证，permissions: id-token: write+environment: npm-publish，无需长期 NPM_TOKEN；以package.runtime.json为基础组装精简发布包（仅运行时依赖，约 50MB，对比含 devDependencies 的 1GB+），并用npm publish --access public --provenance附上来源证明，带 3 次重试；
7. Docker 镜像（build-docker）：通过 QEMU + Buildx 构建linux/amd64与linux/arm64双平台镜像，标准版ghcr.io/.../n8n-mcp与 Railway 专用版ghcr.io/.../n8n-mcp-railway，打vX.Y.Z、vX.Y、vX、latest语义化标签，并在推完后带指数退避重试校验 multi-arch manifest；最后update-documentation自动更新 README 版本徽章并回推。

需要配置的 Secret

发布需要以下 GitHub 仓库 Secrets（Settings → Secrets and variables → Actions）：

npm 侧无需 NPM_TOKEN：只需在 npmjs.com 包管理页配置 Trusted Publisher，指向release.yml工作流与npm-publish环境（GitHub 仓库 Settings → Environments 中需存在同名环境）。npm 版本需 ≥ 11.5.1 才支持 OIDC，CI 中有Upgrade npm步骤处理。

常见发布故障速查

• npm 发布 401 / ENEEDAUTH：核对 Trusted Publisher 配置（工作流文件名只写release.yml不带路径）与npm-publish环境是否存在；确认 job 仍声明id-token: write。
• Docker 构建失败could not read from registry：检查 GHCR 权限与GITHUB_TOKEN的packages: write。
• changelog 解析失败：确保版本节格式为## [X.Y.Z] - YYYY-MM-DD。
• 版本未递增：新版本必须大于 npm 上已发布版本，遵循语义化版本规范（MAJOR 破坏性变更、MINOR 新功能、PATCH 修复）。
• 发布不完整需回滚：本地git tag -d vX.Y.Z并git push --delete origin vX.Y.Z删除 tag 后修复重推。

给贡献者与维护者的最佳实践

• 提交 PR 前：本地跑通npm test && npm run build，有版本变更的 PR 更新 changelog 并说明破坏性影响；
• 版本提升规则：破坏性变更必须 MAJOR、新功能 MINOR、修复 PATCH；
• 发布前自检清单：运行npm run test:release-automation、用有意义的描述更新 changelog、审查破坏性变更、评估对下游用户的影响；
• 安全基线：发布包只含运行时依赖，无构建工具与测试框架，攻击面最小化；npm 来源证明（provenance）将包与具体 commit 和工作流运行绑定。

通过本文的本地开发 → 测试 → 发布完整链路，你既可以作为贡献者快速进入 n8n-mcp 的代码世界，也可以作为维护者安全、可回溯地发布新版本。深入细节可继续阅读仓库中的 docs/AUTOMATED_RELEASES.md 与 tests/setup/TEST_ENV_DOCUMENTATION.md。

【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp