Skip to content

Commit f4654c9

Browse files
avrabeavrabe
committed
feat: initial template MCP server with enhanced npm publishing
- Complete MCP server implementation using PulseEngine framework macros - Comprehensive npm distribution with platform-specific packages - Robust CI/CD workflow for cross-platform binary publishing - Template structure with example tools and documentation - Dual installation strategy: platform packages + GitHub releases fallback - Full project templates including GitHub issue/PR templates - Complete development and publishing documentation
0 parents  commit f4654c9

34 files changed

+2298
-0
lines changed

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
name: Bug report
3+
about: Create a report to help us improve
4+
title: '[BUG] '
5+
labels: bug
6+
assignees: ''
7+
---
8+
9+
## Bug Description
10+
A clear and concise description of what the bug is.
11+
12+
## To Reproduce
13+
Steps to reproduce the behavior:
14+
1. Build the server with '...'
15+
2. Run command '...'
16+
3. Send request '...'
17+
4. See error
18+
19+
## Expected Behavior
20+
A clear and concise description of what you expected to happen.
21+
22+
## Actual Behavior
23+
What actually happened.
24+
25+
## Error Output
26+
```
27+
Paste any error messages or logs here
28+
```
29+
30+
## Environment
31+
- OS: [e.g. macOS, Ubuntu, Windows]
32+
- Rust version: [e.g. 1.75.0]
33+
- Framework version: [e.g. 0.8.2]
34+
- MCP Client: [e.g. Claude Desktop, MCP Inspector]
35+
36+
## Request/Response Examples
37+
```json
38+
// Request that caused the issue
39+
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{...}}
40+
41+
// Response received
42+
{"jsonrpc":"2.0","id":1,"error":{...}}
43+
```
44+
45+
## Additional Context
46+
Add any other context about the problem here.

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
name: Feature request
3+
about: Suggest an idea for this project
4+
title: '[FEATURE] '
5+
labels: enhancement
6+
assignees: ''
7+
---
8+
9+
## Feature Description
10+
A clear and concise description of what you want to add.
11+
12+
## Problem Statement
13+
What problem does this feature solve? Is your feature request related to a problem?
14+
15+
## Proposed Solution
16+
Describe the solution you'd like to see implemented.
17+
18+
## Tool Specification
19+
If this is a new MCP tool, provide the specification:
20+
21+
### Tool Name
22+
`your_tool_name`
23+
24+
### Description
25+
What the tool does and when to use it.
26+
27+
### Parameters
28+
```json
29+
{
30+
"param1": {
31+
"type": "string",
32+
"description": "Description of parameter",
33+
"required": true
34+
},
35+
"param2": {
36+
"type": "number",
37+
"description": "Optional parameter",
38+
"required": false
39+
}
40+
}
41+
```
42+
43+
### Expected Response
44+
```json
45+
{
46+
"result": "example response format"
47+
}
48+
```
49+
50+
## Alternative Solutions
51+
Describe any alternative solutions or features you've considered.
52+
53+
## Additional Context
54+
Add any other context, mockups, or examples about the feature request here.

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Pull Request
2+
3+
## Description
4+
Brief description of changes made in this PR.
5+
6+
## Type of Change
7+
- [ ] Bug fix (non-breaking change which fixes an issue)
8+
- [ ] New feature (non-breaking change which adds functionality)
9+
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
10+
- [ ] Documentation update
11+
- [ ] Refactoring (no functional changes)
12+
- [ ] Performance improvement
13+
14+
## Changes Made
15+
- Change 1
16+
- Change 2
17+
- Change 3
18+
19+
## Testing
20+
- [ ] I have tested these changes locally
21+
- [ ] I have tested with MCP Inspector
22+
- [ ] I have tested the tools/list endpoint
23+
- [ ] I have tested tool execution
24+
25+
## Test Commands
26+
```bash
27+
# List tools
28+
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | ./target/debug/your-server
29+
30+
# Test specific tool
31+
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"tool_name","arguments":{}}}' | ./target/debug/your-server
32+
```
33+
34+
## Documentation
35+
- [ ] I have updated the README if needed
36+
- [ ] I have added/updated code comments
37+
- [ ] I have updated tool descriptions
38+
39+
## Checklist
40+
- [ ] My code follows the project's style guidelines
41+
- [ ] I have performed a self-review of my own code
42+
- [ ] My changes generate no new warnings
43+
- [ ] Any dependent changes have been merged and published

‎.github/dependabot.yml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
version: 2
2+
updates:
3+
# Enable version updates for Cargo
4+
- package-ecosystem: "cargo"
5+
directory: "/"
6+
schedule:
7+
interval: "weekly"
8+
open-pull-requests-limit: 10
9+
labels:
10+
- "dependencies"
11+
- "rust"
12+
commit-message:
13+
prefix: "chore"
14+
include: "scope"

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

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
name: Release NPM Package
2+
3+
on:
4+
release:
5+
types: [published]
6+
workflow_dispatch:
7+
inputs:
8+
version:
9+
description: 'Version to release'
10+
required: true
11+
default: 'v0.1.0'
12+
13+
permissions:
14+
contents: write
15+
packages: write
16+
17+
env:
18+
CARGO_TERM_COLOR: always
19+
20+
jobs:
21+
build-binaries:
22+
name: Build ${{ matrix.target }}
23+
runs-on: ${{ matrix.os }}
24+
strategy:
25+
fail-fast: false
26+
matrix:
27+
include:
28+
- target: x86_64-unknown-linux-gnu
29+
os: ubuntu-latest
30+
archive: tar.gz
31+
- target: x86_64-apple-darwin
32+
os: macos-latest
33+
archive: tar.gz
34+
- target: aarch64-apple-darwin
35+
os: macos-14
36+
archive: tar.gz
37+
- target: x86_64-pc-windows-msvc
38+
os: windows-latest
39+
archive: zip
40+
41+
steps:
42+
- name: Checkout repository
43+
uses: actions/checkout@v4
44+
45+
- name: Install Rust
46+
uses: dtolnay/rust-toolchain@stable
47+
with:
48+
targets: ${{ matrix.target }}
49+
50+
- name: Build binary
51+
run: cargo build --release --target ${{ matrix.target }} --package template-mcp-server
52+
53+
- name: Prepare binary (Unix)
54+
if: matrix.archive == 'tar.gz'
55+
run: |
56+
mkdir -p dist
57+
cp target/${{ matrix.target }}/release/template-mcp-server dist/
58+
cd dist
59+
tar -czf template-mcp-server-${{ github.event.release.tag_name || github.event.inputs.version }}-${{ matrix.target }}.tar.gz template-mcp-server
60+
61+
- name: Prepare binary (Windows)
62+
if: matrix.archive == 'zip'
63+
run: |
64+
mkdir dist
65+
cp target/${{ matrix.target }}/release/template-mcp-server.exe dist/
66+
cd dist
67+
Compress-Archive -Path template-mcp-server.exe -DestinationPath template-mcp-server-${{ github.event.release.tag_name || github.event.inputs.version }}-${{ matrix.target }}.zip
68+
69+
- name: Upload binary to release
70+
shell: bash
71+
env:
72+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
73+
run: |
74+
VERSION=${{ github.event.release.tag_name || github.event.inputs.version }}
75+
FILE="dist/template-mcp-server-${VERSION}-${{ matrix.target }}.${{ matrix.archive }}"
76+
77+
# Check if release exists, create if not
78+
if ! gh release view "${VERSION}" >/dev/null 2>&1; then
79+
gh release create "${VERSION}" --title "Release ${VERSION}" --notes "Auto-generated release for ${VERSION}"
80+
fi
81+
82+
# Upload or update asset
83+
if gh release view "${VERSION}" --json assets --jq '.assets[].name' | grep -q "template-mcp-server-${VERSION}-${{ matrix.target }}.${{ matrix.archive }}"; then
84+
gh release delete-asset "${VERSION}" "template-mcp-server-${VERSION}-${{ matrix.target }}.${{ matrix.archive }}" --yes
85+
fi
86+
87+
gh release upload "${VERSION}" "${FILE}"
88+
89+
publish-npm:
90+
name: Publish to NPM
91+
needs: build-binaries
92+
runs-on: ubuntu-latest
93+
steps:
94+
- name: Checkout repository
95+
uses: actions/checkout@v4
96+
97+
- name: Setup Node.js
98+
uses: actions/setup-node@v4
99+
with:
100+
node-version: '18'
101+
registry-url: 'https://registry.npmjs.org'
102+
103+
- name: Update package version and dependencies
104+
working-directory: npm
105+
run: |
106+
VERSION=${{ github.event.release.tag_name || github.event.inputs.version }}
107+
# Remove 'v' prefix if present
108+
VERSION=${VERSION#v}
109+
110+
# Update main package version and optionalDependencies
111+
jq --arg version "$VERSION" '
112+
.version = $version |
113+
.optionalDependencies = {
114+
"@yourusername/template-mcp-server-darwin-arm64": $version,
115+
"@yourusername/template-mcp-server-darwin-x64": $version,
116+
"@yourusername/template-mcp-server-linux-x64": $version,
117+
"@yourusername/template-mcp-server-win32-x64": $version
118+
}
119+
' package.json > package.json.tmp && mv package.json.tmp package.json
120+
121+
- name: Install dependencies
122+
working-directory: npm
123+
run: npm install
124+
125+
- name: Publish to NPM
126+
working-directory: npm
127+
run: npm publish --access public
128+
env:
129+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
130+
131+
- name: Create NPM release summary
132+
run: |
133+
echo "## 📦 NPM Package Published" >> $GITHUB_STEP_SUMMARY
134+
echo "" >> $GITHUB_STEP_SUMMARY
135+
echo "Package: \`@yourusername/template-mcp-server\`" >> $GITHUB_STEP_SUMMARY
136+
echo "Version: \`${{ github.event.release.tag_name || github.event.inputs.version }}\`" >> $GITHUB_STEP_SUMMARY
137+
echo "" >> $GITHUB_STEP_SUMMARY
138+
echo "### 🚀 Usage:" >> $GITHUB_STEP_SUMMARY
139+
echo "\`\`\`bash" >> $GITHUB_STEP_SUMMARY
140+
echo "# Run with npx (no installation)" >> $GITHUB_STEP_SUMMARY
141+
echo "npx @yourusername/template-mcp-server --help" >> $GITHUB_STEP_SUMMARY
142+
echo "" >> $GITHUB_STEP_SUMMARY
143+
echo "# Or install globally" >> $GITHUB_STEP_SUMMARY
144+
echo "npm install -g @yourusername/template-mcp-server" >> $GITHUB_STEP_SUMMARY
145+
echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
146+
147+
build-platform-packages:
148+
name: Build Platform Packages
149+
needs: build-binaries
150+
runs-on: ubuntu-latest
151+
strategy:
152+
matrix:
153+
include:
154+
- target: aarch64-apple-darwin
155+
platform: darwin-arm64
156+
binary: template-mcp-server
157+
- target: x86_64-apple-darwin
158+
platform: darwin-x64
159+
binary: template-mcp-server
160+
- target: x86_64-unknown-linux-gnu
161+
platform: linux-x64
162+
binary: template-mcp-server
163+
- target: x86_64-pc-windows-msvc
164+
platform: win32-x64
165+
binary: template-mcp-server.exe
166+
167+
steps:
168+
- name: Checkout repository
169+
uses: actions/checkout@v4
170+
171+
- name: Setup Node.js
172+
uses: actions/setup-node@v4
173+
with:
174+
node-version: '18'
175+
registry-url: 'https://registry.npmjs.org'
176+
177+
- name: Download release asset
178+
env:
179+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
180+
run: |
181+
VERSION=${{ github.event.release.tag_name || github.event.inputs.version }}
182+
ARCHIVE_EXT=${{ matrix.target == 'x86_64-pc-windows-msvc' && 'zip' || 'tar.gz' }}
183+
ASSET_NAME="template-mcp-server-${VERSION}-${{ matrix.target }}.${ARCHIVE_EXT}"
184+
185+
# Download the release asset
186+
gh release download "${VERSION}" --pattern "${ASSET_NAME}" --dir ./temp
187+
188+
# Extract the binary
189+
cd temp
190+
if [[ "${ARCHIVE_EXT}" == "zip" ]]; then
191+
unzip "${ASSET_NAME}"
192+
else
193+
tar -xzf "${ASSET_NAME}"
194+
fi
195+
196+
# Move binary to platform package directory
197+
mv "${{ matrix.binary }}" "../platform-packages/${{ matrix.platform }}/"
198+
199+
- name: Update platform package version
200+
working-directory: platform-packages/${{ matrix.platform }}
201+
run: |
202+
VERSION=${{ github.event.release.tag_name || github.event.inputs.version }}
203+
# Remove 'v' prefix if present
204+
VERSION=${VERSION#v}
205+
206+
# Update platform package version
207+
jq --arg version "$VERSION" '.version = $version' package.json > package.json.tmp && mv package.json.tmp package.json
208+
209+
- name: Publish platform package
210+
working-directory: platform-packages/${{ matrix.platform }}
211+
run: npm publish --access public
212+
env:
213+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
214+
215+
- name: Clean up
216+
run: rm -rf temp

0 commit comments

Comments
 (0)