Skip to content

Commit 2d842a3

Browse files
ochafikclaudegithub-advanced-security[bot]
authored
Add npm publish workflow (#89)
* Add npm publish workflow - Add .github/workflows/npm-publish.yml triggered on GitHub releases - Runs build and test jobs before publishing - Uses NPM_TOKEN secret with OIDC provenance - Smart npm tagging: latest, beta, or release-X.Y - Add prepack hook to package.json for automatic builds - Move bun from dependencies to devDependencies - Add npm test step to CI workflow 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]> * Add CONTRIBUTING.md with maintainer publishing guide - Getting started and development process for contributors - Pull request guidelines - Maintainer section with: - Repository setup (NPM_TOKEN, release environment) - Step-by-step release publishing instructions - npm tag documentation (latest, beta, release-X.Y) - Maintenance release workflow - Pre-release testing via pkg-pr-new 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]> * ... * Potential fix for code scanning alert no. 9: Workflow does not contain permissions Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com> --------- Co-authored-by: Claude <[email protected]> Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>
1 parent 42265d8 commit 2d842a3

File tree

5 files changed

+242
-2
lines changed

5 files changed

+242
-2
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,4 +27,6 @@ jobs:
2727

2828
- run: npm run build:all
2929

30+
- run: npm test
31+
3032
- run: npm run prettier

‎.github/workflows/npm-publish.yml‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
name: Publish to npm
2+
3+
on:
4+
release:
5+
types: [published]
6+
7+
concurrency:
8+
group: ${{ github.workflow }}-${{ github.ref }}
9+
cancel-in-progress: true
10+
11+
jobs:
12+
build:
13+
runs-on: ubuntu-latest
14+
permissions:
15+
contents: read
16+
steps:
17+
- uses: actions/checkout@v4
18+
- uses: oven-sh/setup-bun@v2
19+
with:
20+
bun-version: latest
21+
- uses: actions/setup-node@v4
22+
with:
23+
node-version: "22"
24+
cache: npm
25+
- run: npm ci
26+
- run: npm run build
27+
- run: npm run prettier
28+
29+
test:
30+
runs-on: ubuntu-latest
31+
permissions:
32+
contents: read
33+
steps:
34+
- uses: actions/checkout@v4
35+
- uses: oven-sh/setup-bun@v2
36+
with:
37+
bun-version: latest
38+
- uses: actions/setup-node@v4
39+
with:
40+
node-version: "22"
41+
cache: npm
42+
- run: npm ci
43+
- run: npm test
44+
45+
publish:
46+
runs-on: ubuntu-latest
47+
if: github.event_name == 'release'
48+
environment: release
49+
needs: [build, test]
50+
51+
permissions:
52+
contents: read
53+
id-token: write
54+
55+
steps:
56+
- uses: actions/checkout@v4
57+
- uses: oven-sh/setup-bun@v2
58+
with:
59+
bun-version: latest
60+
- uses: actions/setup-node@v4
61+
with:
62+
node-version: "22"
63+
cache: npm
64+
registry-url: "https://registry.npmjs.org"
65+
- run: npm ci
66+
67+
- name: Determine npm tag
68+
id: npm-tag
69+
run: |
70+
VERSION=$(node -p "require('./package.json').version")
71+
# Check if this is a beta release
72+
if [[ "$VERSION" == *"-beta"* ]]; then
73+
echo "tag=--tag beta" >> $GITHUB_OUTPUT
74+
# Check if this release is from a non-main branch (patch/maintenance release)
75+
elif [[ "${{ github.event.release.target_commitish }}" != "main" ]]; then
76+
# Use "release-X.Y" as tag for old branch releases
77+
MAJOR_MINOR=$(echo "$VERSION" | cut -d. -f1,2)
78+
echo "tag=--tag release-${MAJOR_MINOR}" >> $GITHUB_OUTPUT
79+
else
80+
echo "tag=" >> $GITHUB_OUTPUT
81+
fi
82+
83+
- run: npm publish --provenance --access public ${{ steps.npm-tag.outputs.tag }}
84+
env:
85+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

‎CONTRIBUTING.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
# Contributing to MCP Apps SDK
2+
3+
We welcome contributions to the MCP Apps SDK! This document outlines the process for contributing to the project.
4+
5+
## Getting Started
6+
7+
1. Fork the repository
8+
2. Clone your fork: `git clone https://github.com/YOUR-USERNAME/ext-apps.git`
9+
3. Install dependencies: `npm install`
10+
4. Build the project: `npm run build`
11+
5. Run tests: `npm test`
12+
13+
## Development Process
14+
15+
1. Create a new branch for your changes
16+
2. Make your changes
17+
3. Run `npm run prettier` to ensure code style compliance
18+
4. Run `npm test` to verify all tests pass
19+
5. Submit a pull request
20+
21+
## Pull Request Guidelines
22+
23+
- Follow the existing code style
24+
- Include tests for new functionality
25+
- Update documentation as needed
26+
- Keep changes focused and atomic
27+
- Provide a clear description of changes
28+
29+
## Running Examples
30+
31+
Start the development environment with hot reloading:
32+
33+
```bash
34+
npm run examples:dev
35+
```
36+
37+
Or build and run examples:
38+
39+
```bash
40+
npm run examples:start
41+
```
42+
43+
## Code of Conduct
44+
45+
This project follows our [Code of Conduct](CODE_OF_CONDUCT.md). Please review it before contributing.
46+
47+
## Reporting Issues
48+
49+
- Use the [GitHub issue tracker](https://github.com/modelcontextprotocol/ext-apps/issues)
50+
- Search existing issues before creating a new one
51+
- Provide clear reproduction steps
52+
53+
## Security Issues
54+
55+
Please review our [Security Policy](SECURITY.md) for reporting security vulnerabilities.
56+
57+
---
58+
59+
## For Maintainers
60+
61+
### Repository Setup
62+
63+
Before publishing releases, ensure the following are configured:
64+
65+
1. **NPM_TOKEN secret**: Add an npm automation token to the repository secrets
66+
- Go to Settings � Secrets and variables � Actions
67+
- Create a new secret named `NPM_TOKEN`
68+
- Value: an npm automation token with publish permissions for `@modelcontextprotocol/ext-apps`
69+
70+
2. **`release` environment** (optional): Create a protected environment for additional safeguards
71+
- Go to Settings � Environments � New environment
72+
- Name it `release`
73+
- Add required reviewers or other protection rules as needed
74+
75+
### Publishing a Release
76+
77+
Releases are published automatically via GitHub Actions when a GitHub Release is created.
78+
79+
#### Steps to publish:
80+
81+
1. **Update the version** in `package.json`:
82+
83+
```bash
84+
# For a regular release
85+
npm version patch # or minor, or major
86+
87+
# For a beta release
88+
npm version prerelease --preid=beta
89+
```
90+
91+
2. **Commit the version bump** (if not done by `npm version`):
92+
93+
```bash
94+
git add package.json
95+
git commit -m "Bump version to X.Y.Z"
96+
git push origin main
97+
```
98+
99+
3. **Create a GitHub Release**:
100+
- Go to [Releases](https://github.com/modelcontextprotocol/ext-apps/releases)
101+
- Click "Draft a new release"
102+
- Create a new tag matching the version (e.g., `v0.1.0`)
103+
- Set the target branch (usually `main`)
104+
- Write release notes describing the changes
105+
- Click "Publish release"
106+
107+
4. **Monitor the workflow**:
108+
- The [npm-publish workflow](https://github.com/modelcontextprotocol/ext-apps/actions/workflows/npm-publish.yml) will trigger automatically
109+
- It runs build and test jobs before publishing
110+
- On success, the package is published to npm with provenance
111+
112+
#### npm Tags
113+
114+
The workflow automatically determines the npm dist-tag:
115+
116+
| Version Pattern | npm Tag | Install Command |
117+
| ----------------------------- | ------------- | -------------------------------------------------------- |
118+
| `X.Y.Z` (from main) | `latest` | `npm install @modelcontextprotocol/ext-apps` |
119+
| `X.Y.Z-beta.N` | `beta` | `npm install @modelcontextprotocol/ext-apps@beta` |
120+
| `X.Y.Z` (from release branch) | `release-X.Y` | `npm install @modelcontextprotocol/[email protected]` |
121+
122+
#### Maintenance Releases
123+
124+
To release a patch for an older version:
125+
126+
1. Create a release branch from the tag: `git checkout -b release-0.1 v0.1.0`
127+
2. Cherry-pick or apply fixes
128+
3. Bump the patch version
129+
4. Create a GitHub Release targeting the release branch
130+
5. The package will be published with tag `release-0.1`
131+
132+
### Testing Pre-releases
133+
134+
Every commit and PR automatically publishes a preview package via [pkg-pr-new](https://github.com/pkg-pr-new/pkg-pr-new). Check the PR comments or workflow logs for the install command.
135+
136+
---
137+
138+
## License
139+
140+
By contributing, you agree that your contributions will be licensed under the MIT License.

‎package-lock.json‎

Lines changed: 13 additions & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@
2828
],
2929
"scripts": {
3030
"build": "bun build.bun.ts",
31+
"prepack": "npm run build",
3132
"build:all": "npm run build && npm run examples:build",
3233
"test": "bun test",
3334
"examples:build": "find examples -maxdepth 1 -mindepth 1 -type d -exec printf '%s\\0' 'npm run --workspace={} build' ';' | xargs -0 concurrently --kill-others-on-fail",
@@ -55,6 +56,7 @@
5556
"author": "Olivier Chafik",
5657
"devDependencies": {
5758
"@types/bun": "^1.3.2",
59+
"bun": "^1.3.2",
5860
"@types/react": "^19.2.2",
5961
"@types/react-dom": "^19.2.2",
6062
"concurrently": "^9.2.1",
@@ -69,7 +71,6 @@
6971
},
7072
"dependencies": {
7173
"@modelcontextprotocol/sdk": "^1.23.0",
72-
"bun": "^1.3.2",
7374
"react": "^19.2.0",
7475
"react-dom": "^19.2.0",
7576
"zod": "^3.25"

0 commit comments

Comments
 (0)