# MCP Package Implementation Plan for Hello 3D MCP Server
## Executive Summary
This plan outlines the adoption of the **MCP Package (`.mcpb`)** approach from IGV-Web MCP to Hello 3D MCP Server. This will enable easy distribution and installation of the server as a self-contained package that can be installed directly in Claude Desktop and other MCP clients.
## Applicability Assessment
### ✅ **Yes, this approach is highly applicable** for the following reasons:
1. **Distribution Benefits:**
- Users can install the server without needing Node.js/npm installed
- Single-file bundle eliminates dependency management issues
- Easy installation in Claude Desktop via `.mcpb` file
- No need to clone repository or run `npm install`
2. **Current State Compatibility:**
- Hello 3D MCP server already works well as a standalone server
- Both STDIO and HTTP/SSE transport modes are supported
- WebSocket server is self-contained
- All dependencies are standard npm packages that can be bundled
3. **Key Differences from IGV-Web MCP:**
- **No YAML tool definitions**: Hello 3D defines tools inline (simpler, no YAML conversion step needed)
- **More dependencies**: express, cors, ws, zod, three (all bundleable)
- **Dual transport modes**: Both STDIO and HTTP/SSE (both should work after bundling)
- **WebSocket server**: Built-in WebSocket server (needs to be bundled correctly)
## Bundler Choice: esbuild vs Vite
### Recommendation: **esbuild** ⚡
For bundling a Node.js MCP server, **esbuild is the better choice**:
| Feature | esbuild | Vite |
|---------|---------|------|
| **Speed** | ⚡⚡⚡ Extremely fast (Go-based) | ⚡ Fast (uses esbuild internally) |
| **Node.js Support** | ✅ Excellent, designed for it | ⚠️ Good, but optimized for frontend |
| **Configuration** | 🎯 Simple, minimal config | 📝 More config needed for Node.js |
| **Bundle Size** | 📦 Smaller | 📦 Similar |
| **Dependencies** | 📥 Just `esbuild` | 📥 `vite` + plugins |
| **Best For** | Node.js servers, libraries | Frontend apps, full-stack with frontend |
**Why esbuild for this project:**
- ✅ Faster builds (10-100x faster than Rollup/Vite)
- ✅ Simpler configuration for pure Node.js code
- ✅ Better suited for server-side bundling
- ✅ Smaller dependency footprint
- ✅ What Vite uses internally anyway
**When to use Vite instead:**
- If you already have Vite in your project and want consistency
- If you're building a full-stack app with shared frontend/backend code
- If you prefer the Vite ecosystem and tooling
**Bottom line**: Both work, but esbuild is faster and simpler for Node.js server bundling. However, if you prefer Vite for consistency with other tooling, it's absolutely viable.
## Implementation Plan
### Phase 1: Build Infrastructure Setup
#### 1.1 Install Build Dependencies
**Recommended: esbuild**
Add to `package.json` devDependencies:
- `esbuild` - Fast bundler (written in Go, 10-100x faster than Rollup)
- `archiver` - Create ZIP archives
**Alternative: Vite**
Add to `package.json` devDependencies:
- `vite` - Build tool (uses Rollup internally for production)
- `archiver` - Create ZIP archives
**Why esbuild over Vite for Node.js servers:**
- Vite is optimized for frontend development (HMR, dev server, etc.)
- esbuild is simpler and faster for pure Node.js bundling
- Vite uses esbuild internally anyway for fast transforms
- Less configuration needed for server-side code
#### 1.2 Create Build Configuration
**Recommended: esbuild** (faster, simpler for Node.js)
- Create `esbuild.config.js` or use esbuild CLI
- Input: `server.js` (main entry point)
- Output: `dist/hello3dmcp-server.js` (bundled ESM file)
- Platform: `node`
- Target: `node18`
- Bundle all dependencies (express, cors, ws, zod, three, @modelcontextprotocol/sdk)
**Alternative: Vite** (if preferred for consistency with frontend tooling)
- Create `vite.config.js`
- Configure for Node.js library mode
- Uses Rollup internally for production builds
#### 1.3 Create Build Script
Create `build-mcpb.js`:
- Create ZIP archive named `hello3dmcp-server.mcpb`
- Include `manifest.json` and `dist/` directory
- Use maximum compression (level 9)
#### 1.4 Create Manifest File
Create `manifest.json`:
- Package metadata (name, version, description, author)
- Server configuration:
- Entry point: `dist/hello3dmcp-server.js`
- Command: `node`
- Args: `["${__dirname}/dist/hello3dmcp-server.js"]`
- Support for environment variables (BROWSER_URL, MCP_PORT, WS_PORT)
### Phase 2: Code Adjustments
#### 2.1 Ensure ESM Compatibility
- Verify all imports use ESM syntax (`import` not `require`)
- Ensure `package.json` has `"type": "module"`
- Test that Node.js built-ins work correctly after bundling
#### 2.2 Handle Dynamic Imports
- Check for any dynamic imports that might need special handling
- Ensure WebSocket server initialization works in bundled code
- Verify Express server setup works after bundling
#### 2.3 Environment Variable Handling
- Ensure `.env` file reading still works (may need to adjust paths)
- Test command-line argument parsing
- Verify environment variable priority (CLI > env > .env > default)
### Phase 3: Testing & Validation
#### 3.1 Development Mode Testing
- Ensure `npm start` still works (runs from source)
- Verify all tools are registered correctly
- Test WebSocket server functionality
- Test both STDIO and HTTP/SSE transport modes
#### 3.2 Production Bundle Testing
- Run `npm run build` to create bundle
- Test bundled server in STDIO mode (Claude Desktop)
- Test bundled server in HTTP/SSE mode (MCP Inspector)
- Verify WebSocket server works with bundled code
- Test all tool handlers function correctly
#### 3.3 Package Testing
- Create `.mcpb` package
- Install in Claude Desktop
- Verify installation and connection
- Test tool calls through Claude Desktop
- Verify browser connection URL generation
### Phase 4: Documentation & Distribution
#### 4.1 Update Documentation
- Update README.md with build instructions
- Add installation instructions for `.mcpb` package
- Document development vs production workflows
- Add troubleshooting section for bundled server
#### 4.2 Create Build Scripts
Update `package.json` scripts:
- `build`: Full build process (bundle + package)
- `build:bundle`: Just create bundle (for testing)
- `build:package`: Just create package (if bundle exists)
- `start`: Run from source (development)
- `start:prod`: Run from bundle (production testing)
## Detailed Implementation Steps
### Step 1: Update package.json
**Option A: Using esbuild (Recommended)**
```json
{
"scripts": {
"start": "node server.js",
"build": "node esbuild.config.js && node build-mcpb.js",
"build:bundle": "node esbuild.config.js",
"build:package": "node build-mcpb.js",
"start:prod": "node dist/hello3dmcp-server.js"
},
"devDependencies": {
"esbuild": "^0.19.0",
"archiver": "^7.0.1"
}
}
```
**Option B: Using Vite**
```json
{
"scripts": {
"start": "node server.js",
"build": "vite build && node build-mcpb.js",
"build:bundle": "vite build",
"build:package": "node build-mcpb.js",
"start:prod": "node dist/hello3dmcp-server.js"
},
"devDependencies": {
"vite": "^5.0.0",
"archiver": "^7.0.1"
}
}
```
**Recommendation**: Use esbuild for:
- ⚡ Much faster builds (10-100x faster)
- 🎯 Simpler configuration for Node.js
- 📦 Smaller dependency footprint
- ✅ Better suited for server-side bundling
### Step 2: Create Build Configuration
**Option A: esbuild (Recommended for Node.js)**
Create `esbuild.config.js`:
```javascript
import { build } from 'esbuild';
build({
entryPoints: ['server.js'],
bundle: true,
platform: 'node',
target: 'node18',
format: 'esm',
outfile: 'dist/hello3dmcp-server.js',
external: [], // Bundle everything
minify: false, // Keep readable for debugging
sourcemap: false,
}).catch(() => process.exit(1));
```
**Option B: Vite (If preferred)**
Create `vite.config.js`:
```javascript
import { defineConfig } from 'vite';
export default defineConfig({
build: {
lib: {
entry: 'server.js',
formats: ['es'],
fileName: 'hello3dmcp-server',
},
rollupOptions: {
output: {
dir: 'dist',
format: 'es',
},
},
target: 'node18',
minify: false,
},
});
```
**Note**: esbuild is recommended because:
- Faster builds (10-100x faster than Rollup)
- Simpler configuration for Node.js
- What Vite uses internally anyway
- Better suited for server-side bundling
**Note**: May need to mark some Node.js built-ins as external if they cause issues, but ideally bundle everything.
### Step 3: Create build-mcpb.js
```javascript
import fs from 'fs';
import archiver from 'archiver';
const output = fs.createWriteStream('hello3dmcp-server.mcpb');
const archive = archiver('zip', { zlib: { level: 9 } });
output.on('close', () => {
console.log(`✅ Package created: hello3dmcp-server.mcpb (${archive.pointer()} bytes)`);
});
archive.on('error', err => { throw err; });
archive.pipe(output);
archive.file('manifest.json', { name: 'manifest.json' });
archive.directory('dist/', 'dist');
archive.finalize();
```
### Step 4: Create manifest.json
```json
{
"manifest_version": "0.1",
"name": "hello3dmcp-server",
"version": "1.0.0",
"description": "MCP server for controlling 3D model visualization",
"author": {
"name": "Douglass Turner"
},
"server": {
"type": "node",
"entry_point": "dist/hello3dmcp-server.js",
"mcp_config": {
"command": "node",
"args": [
"${__dirname}/dist/hello3dmcp-server.js"
],
"env": {
"BROWSER_URL": "http://localhost:5173",
"MCP_PORT": "3000",
"WS_PORT": "3001"
}
}
}
}
```
### Step 5: Handle Path Issues
The bundled code may need adjustments for:
- `__dirname` and `__filename` (use `import.meta.url` instead)
- `.env` file path resolution
- Static file serving (if needed)
### Step 6: Test Build Process
1. **Install dependencies:**
```bash
npm install
```
2. **Create bundle:**
```bash
# With esbuild
npm run build:bundle
# Or with Vite
npm run build:bundle
```
3. **Test bundled server:**
```bash
npm run start:prod
```
4. **Create package:**
```bash
npm run build:package
```
5. **Install in Claude Desktop:**
- Settings → Extensions → Advanced Settings → Install Extension
- Select `hello3dmcp-server.mcpb`
## Potential Challenges & Solutions
### Challenge 1: Node.js Built-ins in Bundle
**Issue**: Bundlers may have issues bundling Node.js built-ins (fs, path, crypto, etc.)
**Solution (esbuild)**:
- esbuild handles Node.js built-ins well with `platform: 'node'`
- Usually works out of the box
- May need to mark some as external if bundling fails
**Solution (Vite)**:
- Configure `build.target: 'node18'`
- May need additional Rollup plugins for Node.js compatibility
- Test thoroughly to ensure all Node.js APIs work
### Challenge 2: Dynamic Requires/Imports
**Issue**: Some dependencies may use dynamic requires that don't bundle well
**Solution (esbuild)**:
- esbuild handles CommonJS conversion automatically
- Check for any dynamic imports and handle them explicitly
- Test WebSocket and Express initialization
**Solution (Vite)**:
- Vite uses Rollup internally, which handles CommonJS well
- May need additional configuration for complex cases
- Test WebSocket and Express initialization
### Challenge 3: File Path Resolution
**Issue**: `__dirname` and `__filename` don't work in ESM bundles
**Solution**:
- Use `import.meta.url` and `fileURLToPath` (already used in server.js)
- Ensure `.env` file path resolution works correctly
- Test path resolution in bundled code
### Challenge 4: Environment Variables
**Issue**: Environment variables need to work in both development and production
**Solution**:
- Manifest.json supports `env` section for default values
- Command-line arguments should still work
- `.env` file reading should work if file is in expected location
### Challenge 5: WebSocket Server
**Issue**: WebSocket server needs to work correctly in bundled code
**Solution**:
- Test WebSocket server initialization
- Verify WebSocket connections work
- Ensure port binding works correctly
## Success Criteria
✅ **Build Process:**
- `npm run build` creates working bundle and package
- Bundle size is reasonable (< 5MB ideally)
- No runtime errors when running bundled server
✅ **Functionality:**
- All tools register correctly
- WebSocket server works
- Both STDIO and HTTP/SSE modes work
- Environment variables and CLI args work
✅ **Distribution:**
- `.mcpb` package installs in Claude Desktop
- Server starts correctly from package
- Tools are available and functional
- Browser connection URL generation works
✅ **Documentation:**
- README updated with build instructions
- Installation guide for `.mcpb` package
- Development vs production workflow documented
## Timeline Estimate
- **Phase 1 (Build Infrastructure)**: 2-3 hours
- **Phase 2 (Code Adjustments)**: 1-2 hours
- **Phase 3 (Testing)**: 2-3 hours
- **Phase 4 (Documentation)**: 1 hour
**Total**: ~6-9 hours
## Next Steps
1. Review and approve this plan
2. Install build dependencies
3. Create build configuration files
4. Test build process incrementally
5. Validate functionality
6. Update documentation
7. Create first `.mcpb` package release
## Benefits Summary
After implementation, users will be able to:
1. **Easy Installation**: Install server in Claude Desktop with a single `.mcpb` file
2. **No Dependencies**: No need for Node.js, npm, or `node_modules`
3. **Self-Contained**: Everything bundled into one package
4. **Version Control**: Easy to distribute specific versions
5. **Professional Distribution**: Standard MCP package format
This approach aligns Hello 3D MCP Server with industry best practices and makes it much easier for users to get started.
