Skip to content

Commit 0573518

Browse files
gui-wfgui-wf
committed
Merge remote-tracking branch 'origin/tools-1_to_1'
2 parents 0f4952c + 137c008 commit 0573518

File tree

13 files changed

+1175
-172
lines changed

13 files changed

+1175
-172
lines changed

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

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
name: Publish to npm
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v*'
7+
- '[0-9]+.[0-9]+.[0-9]+*'
8+
9+
jobs:
10+
publish:
11+
runs-on: ubuntu-latest
12+
permissions:
13+
contents: write
14+
pull-requests: write
15+
16+
steps:
17+
- name: Checkout repository
18+
uses: actions/checkout@v4
19+
with:
20+
fetch-depth: 0
21+
22+
- name: Install Nix
23+
uses: cachix/install-nix-action@v24
24+
with:
25+
nix_path: nixpkgs=channel:nixos-unstable
26+
27+
- name: Extract version from tag
28+
id: version
29+
run: |
30+
# Remove 'v' prefix if present
31+
VERSION="${GITHUB_REF#refs/tags/}"
32+
VERSION="${VERSION#v}"
33+
echo "version=$VERSION" >> $GITHUB_OUTPUT
34+
echo "📌 Target version: $VERSION"
35+
36+
- name: Update version in files
37+
id: update
38+
run: |
39+
echo "🔄 Running version update script..."
40+
nix run .#update-version -- -y "${{ steps.version.outputs.version }}" > version-output.txt 2>&1
41+
42+
# Check if changes were made
43+
if grep -q "No changes needed" version-output.txt; then
44+
echo "changes_needed=false" >> $GITHUB_OUTPUT
45+
echo "ℹ️ No version updates needed"
46+
else
47+
echo "changes_needed=true" >> $GITHUB_OUTPUT
48+
echo "✅ Version files updated"
49+
fi
50+
51+
# Save output for PR body
52+
cat version-output.txt
53+
54+
- name: Create Pull Request
55+
if: steps.update.outputs.changes_needed == 'true'
56+
uses: peter-evans/create-pull-request@v5
57+
with:
58+
token: ${{ secrets.GITHUB_TOKEN }}
59+
commit-message: |
60+
chore: Update version to ${{ steps.version.outputs.version }}
61+
62+
Automated version sync for tag ${{ github.ref_name }}
63+
title: 'chore: Sync version to ${{ steps.version.outputs.version }}'
64+
body: |
65+
## Version Sync Required
66+
67+
Latest version was changed to `${{ steps.version.outputs.version }}`, and the following files need updating to sync with the tagged version:
68+
69+
**Changed files:**
70+
- `package.json`
71+
- `flake.nix`
72+
73+
### Diff
74+
75+
```diff
76+
$(cat version-output.txt)
77+
```
78+
79+
---
80+
81+
🤖 This PR was created automatically by the **Publish to npm** workflow.
82+
83+
**Next steps:**
84+
1. Review the changes
85+
2. Merge this PR
86+
3. The npm publish will proceed after merge
87+
branch: automated/version-sync-${{ steps.version.outputs.version }}
88+
delete-branch: true
89+
draft: false
90+
labels: |
91+
automated
92+
version-sync
93+
94+
- name: Setup Node.js
95+
uses: actions/setup-node@v4
96+
with:
97+
node-version: '20'
98+
registry-url: 'https://registry.npmjs.org'
99+
100+
- name: Install dependencies
101+
run: npm ci
102+
103+
- name: Build package
104+
run: npm run build
105+
106+
- name: Run tests
107+
run: npm run test:mock
108+
109+
- name: Publish to npm
110+
if: steps.update.outputs.changes_needed == 'false'
111+
run: npm publish
112+
env:
113+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
114+
115+
- name: Publish summary
116+
if: steps.update.outputs.changes_needed == 'false'
117+
run: |
118+
echo "## ✅ Published to npm" >> $GITHUB_STEP_SUMMARY
119+
echo "" >> $GITHUB_STEP_SUMMARY
120+
echo "- **Version**: ${{ steps.version.outputs.version }}" >> $GITHUB_STEP_SUMMARY
121+
echo "- **Package**: [purelymail-mcp-server](https://www.npmjs.com/package/purelymail-mcp-server)" >> $GITHUB_STEP_SUMMARY
122+
echo "- **Tag**: ${{ github.ref_name }}" >> $GITHUB_STEP_SUMMARY
123+
124+
- name: Waiting for version sync
125+
if: steps.update.outputs.changes_needed == 'true'
126+
run: |
127+
echo "## ⏳ Waiting for Version Sync" >> $GITHUB_STEP_SUMMARY
128+
echo "" >> $GITHUB_STEP_SUMMARY
129+
echo "A pull request has been created to sync version files." >> $GITHUB_STEP_SUMMARY
130+
echo "npm publish will proceed after the PR is merged and the tag is re-pushed." >> $GITHUB_STEP_SUMMARY
131+
echo "" >> $GITHUB_STEP_SUMMARY
132+
echo "**Action required:**" >> $GITHUB_STEP_SUMMARY
133+
echo "1. Review and merge the version sync PR" >> $GITHUB_STEP_SUMMARY
134+
echo "2. Re-tag: \`git tag -f ${{ github.ref_name }} && git push -f origin ${{ github.ref_name }}\`" >> $GITHUB_STEP_SUMMARY

‎CLAUDE.md‎

Lines changed: 43 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,33 @@ See `docs/KNOWN_ISSUES.md` for detailed documentation of current limitations and
2828

2929
See `docs/versioning-guidelines.md` for semantic versioning practices and release procedures.
3030

31+
### Version Update Script
32+
33+
Use `scripts/update-version.sh` to update versions across `package.json` and `flake.nix`:
34+
35+
**Interactive Mode** (with gum UI):
36+
```bash
37+
./scripts/update-version.sh 2.0.0
38+
nix run .#update-version -- 2.0.0
39+
```
40+
- Shows beautiful colored UI
41+
- Previews diff before applying
42+
- Offers to create git tag
43+
- Safe with automatic rollback on errors
44+
45+
**Non-Interactive Mode** (for automation):
46+
```bash
47+
./scripts/update-version.sh -y 2.0.0
48+
```
49+
- Outputs "No changes needed" or diff
50+
- Never creates git tags (used by GitHub Actions)
51+
- Suitable for CI/CD pipelines
52+
53+
**Automated Release Process**:
54+
1. Update version: `./scripts/update-version.sh 2.0.0`
55+
2. Push tag: `git push origin v2.0.0`
56+
3. GitHub Actions automatically publishes to npm
57+
3158
## Commands
3259
```bash
3360
# Development
@@ -40,6 +67,12 @@ npm run dev # Run server in development mode
4067
npm run test:mock # Test with mock data
4168
npm run inspector # Launch MCP Inspector
4269

70+
# Version Management
71+
npm run version:update 2.0.0 # Update version (npm script)
72+
nix run .#update-version -- 2.0.0 # Update version (via nix)
73+
./scripts/update-version.sh 2.0.0 # Update version (direct script)
74+
./scripts/update-version.sh -y 2.0.0 # Update version (non-interactive)
75+
4376
# Building
4477
nix build # Build production package
4578
npm run build # Compile TypeScript only
@@ -68,7 +101,7 @@ generated-client/ # DO NOT MODIFY - codegen output
68101

69102
### Error Handling
70103
- Never throw raw strings - use Error objects
71-
- Include operation context in errors: `new Error(\`Failed to ${action}: ${details}\`)`
104+
- Include operation context in errors: `new Error(\`Failed to execute ${operationId}: ${details}\`)`
72105
- Log errors to stderr, not stdout (stdout is for MCP protocol)
73106

74107
## Development Workflow
@@ -105,11 +138,15 @@ generated-client/ # DO NOT MODIFY - codegen output
105138
- Never commit API keys
106139
- Support both mock and real modes
107140

108-
### Tool Design
109-
- Group related endpoints into single tools
110-
- Use swagger operationId as action names
111-
- Extract descriptions from swagger summary/description
112-
- Validate inputs with Zod schemas generated from swagger
141+
### Tool Design (v2.0+ Architecture)
142+
- **One tool per operation**: Each OpenAPI operation maps to a dedicated MCP tool
143+
- **Tool naming**: Convert operationId to snake_case (e.g., "Create User" → "create_user")
144+
- **No action parameter**: Tool name directly indicates the action
145+
- **Operation-specific schemas**: Each tool has only the parameters it needs
146+
- **Extract descriptions**: Use swagger operation summary and description
147+
- **Schema validation**: Direct mapping from requestBody schema to tool input schema
148+
149+
This architecture eliminates parameter conflicts and provides clear, unambiguous tools for AI assistants.
113150

114151
### Mock Mode
115152
- Enabled with `MOCK_MODE=true`

‎README.md‎

Lines changed: 43 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -136,27 +136,36 @@ The server uses stdio transport and follows the MCP specification, making it com
136136

137137
## Available Tools
138138

139-
The server provides 4 main tools grouped by resource:
140-
141-
### `manage_user`
142-
- **Actions**: Create User, Delete User, List Users, Modify User, Get User, Create App Password, Delete App Password
143-
- **Use for**: Managing email users and their settings
144-
145-
### `manage_domains`
146-
- **Actions**: Add Domain, List Domains, Update Domain Settings, Delete Domain, Get Ownership Code
147-
- **Use for**: Managing email domains and DNS settings
148-
149-
### `manage_routing`
150-
- **Actions**: Create Routing Rule, Delete Routing Rule, List Routing Rules
151-
- **Use for**: Setting up email forwarding and routing
152-
153-
### `manage_billing`
154-
- **Actions**: Check Account Credit
155-
- **Use for**: Monitoring account balance and usage
156-
157-
### `manage_user_password_reset`
158-
- **Actions**: Create/Update Password Reset Method, Delete Password Reset Method, List Password Reset Methods
159-
- **Use for**: Managing user password recovery options
139+
The server provides 19 individual tools, each corresponding to a specific PurelyMail API operation:
140+
141+
### User Management
142+
- `create_user` - Create a new email user
143+
- `delete_user` - Delete an email user
144+
- `list_users` - List all users under your account
145+
- `modify_user` - Modify user settings
146+
- `get_user` - Retrieve user details
147+
- `create_app_password` - Create an app-specific password
148+
- `delete_app_password` - Delete an app password
149+
150+
### Password Reset Management
151+
- `create_or_update_password_reset_method` - Create or update password reset method
152+
- `delete_password_reset_method` - Delete a password reset method
153+
- `list_password_reset_methods` - List all password reset methods for a user
154+
155+
### Domain Management
156+
- `add_domain` - Add a new domain
157+
- `list_domains` - List all domains
158+
- `update_domain_settings` - Update domain settings
159+
- `delete_domain` - Delete a domain
160+
- `get_ownership_code` - Get DNS ownership verification code
161+
162+
### Routing Management
163+
- `create_routing_rule` - Create a new routing rule
164+
- `delete_routing_rule` - Delete a routing rule
165+
- `list_routing_rules` - List all routing rules
166+
167+
### Billing
168+
- `check_account_credit` - Check current account credit balance
160169

161170
## Features
162171

@@ -202,9 +211,8 @@ npm run build
202211

203212
```json
204213
{
205-
"tool": "manage_user",
214+
"tool": "create_user",
206215
"arguments": {
207-
"action": "Create User",
208216
"userName": "john",
209217
"domainName": "example.com",
210218
"password": "secure-password",
@@ -218,14 +226,24 @@ npm run build
218226

219227
```json
220228
{
221-
"tool": "manage_domains",
229+
"tool": "list_domains",
222230
"arguments": {
223-
"action": "List Domains",
224231
"includeShared": false
225232
}
226233
}
227234
```
228235

236+
### Example: Getting User Details
237+
238+
```json
239+
{
240+
"tool": "get_user",
241+
"arguments": {
242+
"userName": "[email protected]"
243+
}
244+
}
245+
```
246+
229247
## Architecture Notes
230248

231249
### Type Safety

‎docs/DEVELOPMENT.md‎

Lines changed: 41 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,12 @@ npm run fetch:swagger # Download latest API spec from PurelyMail
3333
npm run generate:types # Regenerate TypeScript types from spec
3434
npm run generate:docs # Update endpoint documentation
3535
npm run update:api # Complete API update workflow (fetch + generate + docs)
36+
37+
# Version Management
38+
npm run version:update 2.0.0 # Update version (npm script)
39+
./scripts/update-version.sh 2.0.0 # Update version (direct script)
40+
./scripts/update-version.sh -y 2.0.0 # Update version (non-interactive)
41+
nix run .#update-version -- 2.0.0 # Update version via Nix
3642
```
3743

3844
**Key points:**
@@ -43,13 +49,14 @@ npm run update:api # Complete API update workflow (fetch + generate + docs
4349

4450
## Tool Usage Patterns
4551

52+
As of v2.0+, the server uses a flat tool structure with one tool per operation.
53+
4654
### Example: Creating a User
4755

4856
```json
4957
{
50-
"tool": "manage_user",
58+
"tool": "create_user",
5159
"arguments": {
52-
"action": "Create User",
5360
"userName": "john",
5461
"domainName": "example.com",
5562
"password": "secure-password",
@@ -63,14 +70,24 @@ npm run update:api # Complete API update workflow (fetch + generate + docs
6370

6471
```json
6572
{
66-
"tool": "manage_domains",
73+
"tool": "list_domains",
6774
"arguments": {
68-
"action": "List Domains",
6975
"includeShared": false
7076
}
7177
}
7278
```
7379

80+
### Example: Getting User Details
81+
82+
```json
83+
{
84+
"tool": "get_user",
85+
"arguments": {
86+
"userName": "[email protected]"
87+
}
88+
}
89+
```
90+
7491
## Architecture Notes
7592

7693
### Type Safety
@@ -119,7 +136,25 @@ npm install
119136

120137
1. **Check API spec**: Ensure the PurelyMail API supports the feature
121138
2. **Update types**: Run `npm run generate:types` if API spec changed
122-
3. **Implement feature**: Add to appropriate tool or create new tool
139+
3. **Implement feature**: Tools are auto-generated from OpenAPI spec
123140
4. **Add mock responses**: Update `mock-client.ts` with example responses
124141
5. **Test thoroughly**: Use both mock and real API modes
125-
6. **Update documentation**: Update relevant docs and README if needed
142+
6. **Update documentation**: Update relevant docs and README if needed
143+
144+
### Releasing New Versions
145+
146+
See `docs/versioning-guidelines.md` for complete release process. Quick summary:
147+
148+
1. **Update version**:
149+
```bash
150+
npm run version:update 2.0.0
151+
# or: ./scripts/update-version.sh 2.0.0
152+
# or: nix run .#update-version -- 2.0.0
153+
```
154+
2. **Push tag** (triggers automated release):
155+
```bash
156+
git push origin v2.0.0
157+
```
158+
3. **GitHub Actions** automatically publishes to npm
159+
160+
The version script updates both `package.json` and `flake.nix`, shows a diff preview, and offers to create a git tag.

0 commit comments

Comments
 (0)