MCP 发布流程

发布概述

将 MCP 工具发布到 NPM 需要经过严格的检查流程，确保代码质量和用户体验。

Automated Release Preparation

大多数 MCP 项目都包含自动化发布准备脚本：

npm run prepare-release

这个脚本会执行以下检查：

检查项	说明
Git Status	Ensures you're on the main branch with no uncommitted changes
Required Fields	Validates all required fields in package.json
Dependencies	Checks for missing or outdated dependencies
Security Audit	Runs npm audit to check for vulnerabilities
Version Availability	Confirms the version isn't already published
Version Consistency	Ensures package.json and package-lock.json versions match
Changelog Entry	Verifies CHANGELOG.md has an entry for the current version
TypeScript	Compiles and runs tests
TypeScript Declarations	Verifies .d.ts files are generated
Native Code	Runs format, lint, and tests for Swift/other languages (if applicable)
Build Verification	Builds everything and verifies the package
Package Size	Warns if package exceeds reasonable size limits
MCP Server Smoke Test	Tests the server with a simple JSON-RPC request

Manual Pre-Release Steps

在脚本检查通过后，执行以下手动步骤：

1. Update Version Number

根据语义化版本规范决定新版本号：

{
	"version": "1.0.0-beta.3" // or "1.0.0", "1.1.0"
}

2. Update Documentation

README.md: Ensure it accurately reflects the latest features, installation instructions, and any breaking changes.
API Documentation: If there are changes to tool schemas or server behavior, update the detailed specification.

3. Update CHANGELOG.md

添加新版本的变更记录：

## [1.0.0-beta.3] - 2025-01-15

### Added

-   New feature X

### Changed

-   Updated behavior of Y

### Fixed

-   Bug fix for Z

4. Run Release Preparation

npm run prepare-release

修复脚本发现的任何问题。

5. Test Local Compilation

MANDATORY: Compile and run local tests to ensure they build correctly.

Important Notes:

Many tests may require system permissions (Apple Events, file system access, etc.) which CI cannot grant
Comprehensive local testing is essential
First-time runs may prompt for system permissions

6. Commit Changes

git add .
git commit -m "Prepare release vX.Y.Z"

Publishing to NPM

1. NPM Publish Dry Run

这一步非常重要，用于验证发布内容：

npm publish --access public --tag <your_tag> --dry-run

仔细检查文件列表：

✅ 应该包含：

dist/ (编译后的代码)
binaries (如果有原生二进制文件)
package.json
README.md
CHANGELOG.md
LICENSE

❌ 不应该包含：

source files (源代码)
test files (测试文件)
config files (配置文件)

2. Actual NPM Publish

如果 dry run 结果满意，执行实际发布：

# Beta 版本
npm publish --access public --tag beta

# 正式版本
npm publish --access public

Post-Publish Steps

发布后的收尾工作：

1. Create a Git Tag

git tag vX.Y.Z

2. Push the Git Tag

git push origin vX.Y.Z

3. Create a GitHub Release (Recommended)

Go to the GitHub repository's "Releases" section
Draft a new release, selecting the tag you just pushed
Copy the relevant section from CHANGELOG.md into the release description
Attach any build artifacts if desired

4. Announce the Release (Optional)

在相关渠道宣布新版本发布：

Team chat
Twitter/X
Project website
MCP community

Best Practices

prepublishOnly Script

确保 package.json 中有 prepublishOnly 脚本：

{
	"scripts": {
		"prepublishOnly": "npm run build"
	}
}

这确保每次发布前都会自动构建。

Beta 测试流程

首先发布 beta 版本：npm publish --tag beta
通过 npx [packageName]@beta install 测试
确认无误后发布正式版本

发布检查清单

下一步

学习 AI 规则持续改进了解如何系统性地优化 AI 开发规则。

MCP 发布指南

注册解锁完整内容