TailscaleMCP

# 📦 MCPB Packaging Documentation **Complete guide to packaging and distributing MCP servers with MCPB** --- ## 📚 **Documentation Index** ### **1. MCPB Building Guide** ⭐ **PRIMARY REFERENCE** 📄 [MCPB_BUILDING_GUIDE.md](MCPB_BUILDING_GUIDE.md) **Complete 1,900+ line comprehensive guide** **What it covers**: - ✅ MCPB vs DXT migration (complete transition guide) - ✅ Manifest configuration (detailed examples) - ✅ Build process (step-by-step) - ✅ GitHub Actions CI/CD (automated workflows) - ✅ Troubleshooting (common issues and solutions) - ✅ User configuration (3 types of user prompts) - ✅ Package signing (security) - ✅ Registry publishing (distribution) - ✅ Production patterns (real-world examples) **Read Time**: 2-3 hours **Difficulty**: Intermediate to Advanced **Priority**: **CRITICAL** for distribution --- ### **2. MCPB Implementation Summary** 📄 [MCPB_IMPLEMENTATION_SUMMARY.md](MCPB_IMPLEMENTATION_SUMMARY.md) **Our implementation status and results** **What it covers**: - ✅ Implementation overview - ✅ Package details (0.19 MB) - ✅ Configuration files (mcpb.json, manifest.json) - ✅ Build process - ✅ GitHub Actions workflow - ✅ Tool inventory (26 tools) - ✅ Next steps **Read Time**: 15 minutes **Status**: ✅ **COMPLETED** implementation **Package**: dist/notepadpp-mcp.mcpb (ready!) --- ## 🎯 **What is MCPB?** **MCPB** (MCP Bundle) - Anthropic's official packaging format for MCP servers **Key Benefits**: - 🎯 **One-click installation** - Drag & drop to Claude Desktop - 🔒 **Security** - Cryptographically signed packages - ⚙️ **User configuration** - Interactive setup prompts - 📦 **Bundled dependencies** - Everything included - 🚀 **Automated distribution** - GitHub Actions integration --- ## 📦 **Our MCPB Package** ### **Package Details** | Property | Value | |----------|-------| | **Name** | notepadpp-mcp.mcpb | | **Version** | 1.2.0 | | **Size** | 0.19 MB | | **Tools** | 26 | | **Status** | ✅ Production Ready | | **Location** | `dist/notepadpp-mcp.mcpb` | ### **User Configuration** When users install our MCPB package, they're prompted for: 1. **Notepad++ Executable Path** (file picker) - Default: `C:\Program Files\Notepad++\notepad++.exe` - Auto-detection if left empty 2. **Auto-start Notepad++** (boolean) - Default: `true` - Automatically starts Notepad++ if not running 3. **Operation Timeout** (string) - Default: `30` seconds - Timeout for Notepad++ operations --- ## 🏗️ **Build Process** ### **Quick Build** ```powershell # Build MCPB package (development) .\scripts\build-mcpb-package.ps1 -NoSign # Output: dist/notepadpp-mcp.mcpb (0.19 MB) ``` ### **Build Script Features** ✅ Prerequisites check (MCPB CLI, Python) ✅ Manifest validation ✅ Output management ✅ Package verification ✅ Signing support (optional) ✅ Color-coded progress --- ## 🚀 **Distribution Methods** ### **Method 1: Direct Distribution** 1. Build MCPB package 2. Share `.mcpb` file 3. User drags to Claude Desktop 4. User configures settings 5. Done! **Use Case**: Direct sharing, beta testing --- ### **Method 2: GitHub Releases** 1. Tag version: `git tag v1.2.0` 2. Push tag: `git push origin v1.2.0` 3. GitHub Actions builds automatically 4. Release created with `.mcpb` file 5. Users download from releases **Use Case**: Public distribution, version management **Status**: ✅ Configured and ready! --- ### **Method 3: MCPB Registry** (Future) 1. Build package 2. Sign with key 3. Publish to registry 4. Available in Claude Desktop marketplace **Use Case**: Official distribution channel **Status**: 📅 Planned (registry not yet available) --- ## 📋 **Configuration Files** ### **mcpb.json** (Build Configuration) **Purpose**: Controls how MCPB CLI builds your package **Location**: Project root **Format**: JSON **Key Sections**: ```json { "name": "notepadpp-mcp", "version": "1.2.0", "mcp": { "version": "2.12.0", "capabilities": { "tools": true } }, "dependencies": { "python": ">=3.10.0", "fastmcp": ">=2.12.0" } } ``` --- ### **manifest.json** (Runtime Configuration) **Purpose**: Tells Claude Desktop how to run your server **Location**: Project root **Format**: JSON **Key Sections**: ```json { "manifest_version": "0.2", "name": "notepadpp-mcp", "version": "1.2.0", "server": { "type": "python", "entry_point": "src/notepadpp_mcp/tools/server.py", "mcp_config": { "command": "python", "args": ["-m", "notepadpp_mcp.tools.server"], "env": { "PYTHONPATH": "${PWD}", "NOTEPADPP_PATH": "${user_config.notepadpp_path}" } } }, "user_config": { "notepadpp_path": { "type": "file", "title": "..." } }, "tools": [ /* 26 tools listed */ ] } ``` --- ## 🔍 **Troubleshooting** ### **Build Failures** **Common Issues**: - MCPB CLI not installed → `npm install -g @anthropic-ai/mcpb` - Manifest validation fails → Check JSON syntax - Python path issues → Verify `PYTHONPATH` in manifest **Solution**: See [MCPB Building Guide](MCPB_BUILDING_GUIDE.md) - Troubleshooting section --- ### **Installation Failures** **Common Issues**: - Package won't install in Claude Desktop - Configuration prompts don't appear - Server fails to start **Solution**: See [MCPB Building Guide](MCPB_BUILDING_GUIDE.md) - Path bugs section --- ### **FastMCP Issues** **Common Issues**: - Version < 2.12.0 (incompatible) - Tool registration errors - stdio protocol violations **Solution**: See [FastMCP Troubleshooting](TROUBLESHOOTING_FASTMCP_2.12.md) --- ## 🛠️ **Build Scripts** ### **PowerShell Build Script** **Location**: `scripts/build-mcpb-package.ps1` **Features**: - Automated validation - Package building - Integrity verification - Optional signing - Detailed output **Usage**: ```powershell # Standard build .\scripts\build-mcpb-package.ps1 -NoSign # With signing (when configured) .\scripts\build-mcpb-package.ps1 # Custom output .\scripts\build-mcpb-package.ps1 -OutputDir "E:\builds" ``` --- ### **GitHub Actions Workflow** **Location**: `.github/workflows/build-mcpb.yml` **Triggers**: - Tag push (`v*`) - Manual dispatch **Steps**: 1. Setup Python & Node.js 2. Install MCPB CLI 3. Validate manifest 4. Build MCPB package 5. Upload artifact 6. Create GitHub release 7. Publish to PyPI **Status**: ✅ Configured and tested --- ## 📊 **Package Contents** ### **What's Inside the MCPB Package** ``` notepadpp-mcp.mcpb (0.19 MB) ├── manifest.json # Runtime configuration ├── requirements.txt # Python dependencies ├── src/ # Source code │ └── notepadpp_mcp/ │ ├── __init__.py │ ├── tools/ │ │ └── server.py # Main server (2,424 lines) │ ├── docs/ # Documentation │ └── tests/ # Test suite └── lib/ # Bundled dependencies ├── fastmcp/ # FastMCP framework ├── pywin32/ # Windows API ├── psutil/ # System utilities └── requests/ # HTTP library ``` --- ## 🎯 **Best Practices** ### **Before Building** - [ ] Validate manifest: `mcpb validate manifest.json` - [ ] Test locally - [ ] Update version numbers - [ ] Update CHANGELOG - [ ] All tests passing ### **During Build** - [ ] Use build script (consistency) - [ ] Verify package size (<1 MB ideal) - [ ] Check for errors - [ ] Validate output ### **After Building** - [ ] Test installation in Claude Desktop - [ ] Verify user configuration prompts - [ ] Test all 26 tools - [ ] Check logs for errors --- ## 🔗 **Related Documentation** ### **In This Repository** - [Development Docs](../development/README.md) - Development practices - [MCP Technical](../mcp-technical/README.md) - MCP specifics - [Repository Protection](../repository-protection/README.md) - Safety - [Documentation Index](../DOCUMENTATION_INDEX.md) - All docs ### **External Resources** - [MCPB Official Docs](https://anthropic.com) - Official MCPB documentation - [FastMCP](https://github.com/jlowin/fastmcp) - Framework docs - [MCP Specification](https://modelcontextprotocol.io) - Protocol spec --- ## 🏆 **Success Metrics** **Our MCPB implementation**: - ✅ Package builds successfully (0.19 MB) - ✅ Manifest validates without errors - ✅ All 26 tools registered - ✅ User configuration working - ✅ GitHub Actions automated - ✅ PyPI publishing ready - ✅ Production-ready distribution **Achievement**: Professional packaging matching industry standards! --- ## 📞 **Getting Help** ### **MCPB Issues** - **MCPB Guide**: [MCPB_BUILDING_GUIDE.md](MCPB_BUILDING_GUIDE.md) - **GitHub**: Create issue with `packaging` label - **Community**: Ask in MCP forums ### **FastMCP Issues** - **Troubleshooting**: [TROUBLESHOOTING_FASTMCP_2.12.md](TROUBLESHOOTING_FASTMCP_2.12.md) - **GitHub**: FastMCP repository issues - **Documentation**: FastMCP official docs --- *MCPB Packaging Documentation* *Location: `docs/mcpb-packaging/`* *Files: 3 (2,500+ lines total!)* *Focus: Professional distribution* *Status: Production ready* **Package your MCP server professionally!** 📦✨