mirror of
https://github.com/steipete/agent-rules.git
synced 2025-12-16 12:00:09 +01:00
e3d9dbf805
- Created docs/ folder for reference documentation (Swift, MCP guides) - Created project-rules/ folder for actionable AI assistant rules - Separated content by purpose: - docs/: Knowledge bases and API documentation - project-rules/: Rules for AI behavior and automation - Updated README with clearer structure and usage instructions This organization makes it easier to distinguish between reference materials and actionable rules for AI assistants. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
103 lines
5.1 KiB
Plaintext
103 lines
5.1 KiB
Plaintext
---
|
|
description: Steps and procedures for releasing MCP (Model Context Protocol) servers as NPM packages
|
|
globs: "package.json, **/package.json"
|
|
alwaysApply: false
|
|
---
|
|
|
|
# Releasing MCP Servers
|
|
|
|
This document outlines the steps to release a new version of an MCP (Model Context Protocol) server as an NPM package.
|
|
|
|
## Automated Release Preparation
|
|
|
|
Many MCP projects include an automated release preparation script that performs comprehensive checks before release. Run it with:
|
|
|
|
```bash
|
|
npm run prepare-release
|
|
```
|
|
|
|
This script typically performs the following checks:
|
|
- **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** (if applicable): Runs format, lint, and tests for Swift/other languages
|
|
- **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
|
|
|
|
If all checks pass, follow the manual steps below.
|
|
|
|
## Manual Pre-Release Steps
|
|
|
|
1. **Update Version Number:**
|
|
- Decide on the new semantic version number (e.g., `1.0.0-beta.3`, `1.0.0`, `1.1.0`).
|
|
- Update the `version` field in `package.json`.
|
|
|
|
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.
|
|
- Any other relevant documentation.
|
|
|
|
3. **Update `CHANGELOG.md`:**
|
|
- Add a new section for the upcoming release version (e.g., `## [1.0.0-beta.3] - YYYY-MM-DD`).
|
|
- List all notable changes (Added, Changed, Fixed, Removed, Deprecated, Security) under this version.
|
|
- Replace `YYYY-MM-DD` with the current date.
|
|
|
|
4. **Run Release Preparation:**
|
|
- Run `npm run prepare-release` to ensure everything is ready.
|
|
- Fix any issues identified by the script.
|
|
|
|
5. **Test Local Compilation:**
|
|
- **MANDATORY**: Compile and run local tests to ensure they build correctly.
|
|
- **CI Limitations**: Many tests may require system permissions (Apple Events, file system access, etc.) which CI cannot grant. Therefore, comprehensive local testing is essential.
|
|
- Run all test suites locally to verify they pass with proper permissions.
|
|
- **Important**: First-time runs may prompt for system permissions. Grant necessary access for tests to work.
|
|
- This step is critical as permission-dependent tests cannot be fully validated in CI environments.
|
|
|
|
6. **Commit Changes:**
|
|
- Commit all changes related to the version bump, documentation, and changelog.
|
|
- `git add .`
|
|
- `git commit -m "Prepare release vX.Y.Z"`
|
|
|
|
## Publishing to NPM
|
|
|
|
1. **NPM Publish Dry Run:**
|
|
- This step is crucial to verify what files will be included in the package without actually publishing.
|
|
- `npm publish --access public --tag <your_tag> --dry-run`
|
|
- Replace `<your_tag>` with the appropriate tag (e.g., `beta`, `latest`). For pre-releases, always use a specific tag like `beta` or `rc`.
|
|
- `--access public` is needed for scoped packages if they are intended to be public.
|
|
- Carefully review the list of files. Ensure it includes necessary files (`dist/`, binaries if applicable, `package.json`, `README.md`, `CHANGELOG.md`, and `LICENSE`). Ensure no unnecessary files are included.
|
|
|
|
2. **Actual NPM Publish:**
|
|
- If the dry run is satisfactory, proceed with the actual publish command.
|
|
- Use tag "beta" if the version is a beta, else omit tag to do a release version.
|
|
- `npm publish --access public --tag <your_tag>`
|
|
|
|
## Post-Publish Steps
|
|
|
|
1. **Create a Git Tag:**
|
|
- Create a Git tag for the new version.
|
|
- `git tag vX.Y.Z` (e.g., `git tag v1.0.0-beta.3`)
|
|
|
|
2. **Push the Git Tag:**
|
|
- Push the tag to the remote repository.
|
|
- `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.
|
|
- You can also attach any build artifacts (like compiled binaries or the `.tgz` NPM package) to the GitHub release for direct download if desired.
|
|
|
|
4. **Announce the Release (Optional):**
|
|
- Announce the new release on relevant channels (e.g., team chat, Twitter, project website, MCP community).
|
|
|
|
---
|
|
|
|
**Note on `prepublishOnly`:** Most MCP projects should have a `prepublishOnly` script in their `package.json` that runs the build process. This ensures that the project is always built before publishing. |