Skip to content

Commit 28311c0

Browse files
ketemaketema
committed
[strategos] chore: Add local build protection against NPM/NPX cache overrides
WHY: - NPM and NPX can cache packages and override local builds - User needs to ensure local fix remains active until PR is merged - Multiple layers of protection needed for reliability EXPECTED: - Local build always used (never overridden by NPM/NPX cache) - Easy verification that fix is active - Convenient rebuild workflow - Clear documentation of setup CHANGES: - Added .npmrc: Prevents automatic NPM updates (save-exact, prefer-offline) - Added verify-local-build.sh: Verification script to confirm fix is active - Updated package.json: Added verify, rebuild, postinstall scripts - Added LOCAL_BUILD_SETUP.md: Complete documentation of local build setup PROTECTION LAYERS: 1. Direct node execution (no NPX) - Primary defense 2. NPM config (.npmrc) - Prevents auto-updates 3. Verification script - Confirms fix is active 4. Package.json scripts - Easy maintenance USAGE: - npm run verify: Check local build is active - npm run rebuild: Rebuild and verify - npm run watch: Watch for changes Refs: User request to guard against NPM/NPX cache updates
1 parent ca00790 commit 28311c0

File tree

5 files changed

+422
-1
lines changed

5 files changed

+422
-1
lines changed

‎src/sequentialthinking/.npmrc‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Prevent NPM from auto-updating dependencies
2+
# This ensures the local build remains stable until PR is merged
3+
4+
# Disable automatic package updates
5+
save-exact=true
6+
7+
# Prevent npm from modifying package-lock.json
8+
package-lock=false
9+
10+
# Use local cache only (don't fetch from registry)
11+
prefer-offline=true
12+
13+
# Prevent automatic dependency updates
14+
save-prefix=""
15+

‎src/sequentialthinking/LOCAL_BUILD_SETUP.md‎

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
# Local Build Setup - Sequential Thinking MCP Server
2+
3+
This document explains how to ensure your local build with the schema fix is always used until the PR is merged.
4+
5+
## Quick Start
6+
7+
```bash
8+
# Verify local build is active
9+
npm run verify
10+
11+
# Rebuild after making changes
12+
npm run rebuild
13+
```
14+
15+
## Problem
16+
17+
NPM and NPX can cache packages, potentially overriding your local build with the upstream version that doesn't have the fix.
18+
19+
## Solution: Multi-Layer Protection
20+
21+
### Layer 1: Direct Node Execution (Primary)
22+
23+
Both Augment and VS Code configs use **direct node execution** with absolute paths, bypassing NPX entirely:
24+
25+
```json
26+
{
27+
"sequentialthinking": {
28+
"command": "node",
29+
"args": [
30+
"/Users/ketema/projects/ametek_chess/submodules/mcp-servers/src/sequentialthinking/dist/index.js"
31+
]
32+
}
33+
}
34+
```
35+
36+
**Why this works:**
37+
- ✅ No NPX involved - can't be overridden by cache
38+
- ✅ Absolute path - always points to your local build
39+
- ✅ Direct execution - fastest startup
40+
41+
### Layer 2: NPM Configuration (.npmrc)
42+
43+
The `.npmrc` file prevents automatic updates:
44+
45+
```ini
46+
# Prevent NPM from auto-updating dependencies
47+
save-exact=true
48+
package-lock=false
49+
prefer-offline=true
50+
save-prefix=""
51+
```
52+
53+
**Why this works:**
54+
- ✅ `save-exact=true` - No automatic version updates
55+
- ✅ `prefer-offline=true` - Uses local cache, doesn't fetch from registry
56+
- ✅ `package-lock=false` - Prevents lock file modifications
57+
58+
### Layer 3: Verification Script
59+
60+
Run `npm run verify` to confirm your local build is active:
61+
62+
```bash
63+
npm run verify
64+
```
65+
66+
**Checks performed:**
67+
- ✅ dist/index.js exists
68+
- ✅ Schema fix (oneOf) present in built file
69+
- ✅ Input sanitization (sanitizeNumericParam) present
70+
- ✅ Augment config using local build
71+
- ✅ VS Code config using local build
72+
- ✅ No global package installed
73+
74+
### Layer 4: Package.json Scripts
75+
76+
Convenient scripts for common tasks:
77+
78+
```bash
79+
# Build TypeScript to JavaScript
80+
npm run build
81+
82+
# Build and verify
83+
npm run rebuild
84+
85+
# Watch for changes and rebuild
86+
npm run watch
87+
88+
# Verify local build is active
89+
npm run verify
90+
```
91+
92+
## How to Maintain Local Build
93+
94+
### After Making Code Changes
95+
96+
```bash
97+
cd submodules/mcp-servers/src/sequentialthinking
98+
npm run rebuild
99+
```
100+
101+
This will:
102+
1. Compile TypeScript to JavaScript
103+
2. Make dist/index.js executable
104+
3. Verify the fix is present in the built file
105+
106+
### After Pulling from Git
107+
108+
```bash
109+
cd submodules/mcp-servers/src/sequentialthinking
110+
npm run rebuild
111+
```
112+
113+
### After Restarting VS Code or Augment
114+
115+
No action needed! The configs use absolute paths, so they'll always use your local build.
116+
117+
### Verifying the Server is Running
118+
119+
```bash
120+
ps aux | grep sequential | grep -v grep
121+
```
122+
123+
**Expected output:**
124+
```
125+
ketema 65806 ... node /Users/ketema/projects/ametek_chess/submodules/mcp-servers/src/sequentialthinking/dist/index.js
126+
```
127+
128+
**Key indicator:** Should show `node` followed by the absolute path to your local `dist/index.js`.
129+
130+
**Bad output (if you see this, something is wrong):**
131+
```
132+
ketema 65806 ... npx @modelcontextprotocol/server-sequential-thinking
133+
```
134+
135+
## Troubleshooting
136+
137+
### Problem: "Invalid thoughtNumber: must be a number" error returns
138+
139+
**Diagnosis:**
140+
```bash
141+
npm run verify
142+
```
143+
144+
**If verification fails:**
145+
```bash
146+
npm run rebuild
147+
```
148+
149+
**If still failing:**
150+
1. Check Augment config (Settings Panel) - should use absolute path
151+
2. Check VS Code config (.vscode/settings.json) - should use absolute path
152+
3. Restart VS Code extension host
153+
4. Check running process: `ps aux | grep sequential`
154+
155+
### Problem: NPX cache interfering
156+
157+
**Solution:** Don't use NPX! The configs use `node` directly.
158+
159+
**If you accidentally installed globally:**
160+
```bash
161+
npm uninstall -g @modelcontextprotocol/server-sequential-thinking
162+
```
163+
164+
### Problem: Changes not taking effect
165+
166+
**Checklist:**
167+
1. ✅ Run `npm run rebuild`
168+
2. ✅ Restart MCP server (restart VS Code extension host or Augment)
169+
3. ✅ Verify with `npm run verify`
170+
4. ✅ Check running process: `ps aux | grep sequential`
171+
172+
## File Structure
173+
174+
```
175+
submodules/mcp-servers/src/sequentialthinking/
176+
├── .npmrc # NPM configuration (prevents auto-updates)
177+
├── package.json # Package definition with scripts
178+
├── verify-local-build.sh # Verification script
179+
├── LOCAL_BUILD_SETUP.md # This file
180+
├── SCHEMA_FIX_EXPLANATION.md # Technical explanation of the fix
181+
├── index.ts # Source code (TypeScript)
182+
└── dist/
183+
└── index.js # Built code (JavaScript) - THIS IS WHAT RUNS
184+
```
185+
186+
## Key Principles
187+
188+
1. **Never use NPX** - Always use `node` with absolute path
189+
2. **Verify after changes** - Run `npm run verify` to confirm
190+
3. **Rebuild when needed** - Run `npm run rebuild` after code changes
191+
4. **Check running process** - Use `ps aux | grep sequential` to verify
192+
193+
## When Can You Stop Using Local Build?
194+
195+
Once PR #2812 is merged and released:
196+
197+
1. Check NPM for new version: `npm view @modelcontextprotocol/server-sequential-thinking version`
198+
2. If version > 0.6.2, the fix is released
199+
3. Update configs to use NPX: `npx @modelcontextprotocol/server-sequential-thinking`
200+
4. Remove local build from configs
201+
202+
Until then, **always use the local build!**
203+
204+
## Summary
205+
206+
Your local build is protected by:
207+
- ✅ Direct node execution (no NPX)
208+
- ✅ Absolute paths (no ambiguity)
209+
- ✅ NPM config (no auto-updates)
210+
- ✅ Verification script (confirm it's working)
211+
- ✅ Convenient scripts (easy maintenance)
212+
213+
**You're safe from NPM/NPX cache issues!** 🎉
214+

‎src/sequentialthinking/QUICK_REFERENCE.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Quick Reference - Sequential Thinking Local Build
2+
3+
## Daily Commands
4+
5+
```bash
6+
# Verify local build is active
7+
npm run verify
8+
9+
# Rebuild after code changes
10+
npm run rebuild
11+
12+
# Watch for changes (auto-rebuild)
13+
npm run watch
14+
```
15+
16+
## Verification Checklist
17+
18+
✅ **Local build exists**: dist/index.js present
19+
✅ **Schema fix present**: oneOf in built file
20+
✅ **Sanitization present**: sanitizeNumericParam in built file
21+
✅ **Config correct**: Using absolute path to dist/index.js
22+
✅ **No global package**: Not installed globally
23+
✅ **Server running**: `node .../dist/index.js` (not npx)
24+
25+
## Quick Checks
26+
27+
```bash
28+
# Check running server
29+
ps aux | grep sequential | grep -v grep
30+
# Should show: node /Users/ketema/.../dist/index.js
31+
32+
# Check build date
33+
stat -f "%Sm" -t "%Y-%m-%d %H:%M:%S" dist/index.js
34+
35+
# Check for fix in built file
36+
grep -c "oneOf" dist/index.js # Should be > 0
37+
grep -c "sanitizeNumericParam" dist/index.js # Should be > 0
38+
```
39+
40+
## Troubleshooting
41+
42+
| Problem | Solution |
43+
|---------|----------|
44+
| Error returns | `npm run rebuild` |
45+
| Changes not working | `npm run rebuild` + restart extension |
46+
| NPX interfering | Don't use NPX! Config uses `node` directly |
47+
| Global package installed | `npm uninstall -g @modelcontextprotocol/server-sequential-thinking` |
48+
49+
## Protection Status
50+
51+
🛡️ **Layer 1**: Direct node execution (no NPX)
52+
🛡️ **Layer 2**: NPM config (.npmrc) prevents auto-updates
53+
🛡️ **Layer 3**: Verification script confirms fix
54+
🛡️ **Layer 4**: Package scripts for easy maintenance
55+
56+
## When to Rebuild
57+
58+
- ✅ After editing index.ts
59+
- ✅ After pulling from git
60+
- ✅ After npm install
61+
- ❌ NOT needed after restarting VS Code/Augment
62+
63+
## Config Locations
64+
65+
- **Augment**: Settings Panel → MCP Servers
66+
- **VS Code**: `.vscode/settings.json`
67+
- **Both should use**: `node` + absolute path to `dist/index.js`
68+
69+
## Success Indicators
70+
71+
✅ `npm run verify` passes all checks
72+
✅ `ps aux | grep sequential` shows local path
73+
✅ No "Invalid thoughtNumber" errors
74+
✅ Tool accepts both `thoughtNumber: 1` and `thoughtNumber: "1"`
75+
76+
## Emergency Reset
77+
78+
```bash
79+
cd submodules/mcp-servers/src/sequentialthinking
80+
npm run rebuild
81+
# Restart VS Code extension host or Augment
82+
npm run verify
83+
```
84+
85+
---
86+
87+
**Remember**: Your local build is protected! NPM/NPX cache can't override it. 🎉
88+

‎src/sequentialthinking/package.json‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,10 @@
1616
"scripts": {
1717
"build": "tsc && shx chmod +x dist/*.js",
1818
"prepare": "npm run build",
19-
"watch": "tsc --watch"
19+
"watch": "tsc --watch",
20+
"verify": "bash verify-local-build.sh",
21+
"rebuild": "npm run build && npm run verify",
22+
"postinstall": "echo '⚠️ Local build detected. Run npm run rebuild to ensure your fixes are active.'"
2023
},
2124
"dependencies": {
2225
"@modelcontextprotocol/sdk": "0.5.0",

0 commit comments

Comments
 (0)