mcp-npm-proxy

An NPX tool for deploying STDIO-based MCP (Model Context Protocol) servers to a hosted environment while publishing proxy packages to npm.

Overview

When you create a STDIO-based MCP server as an npm package, your source code becomes publicly visible. This tool solves that problem by:

• Hosting your MCP server privately on a secure server infrastructure
• Publishing a proxy package to npm that calls your hosted server
• Keeping your source code private while maintaining npm package compatibility

How It Works

1. Upload: Your MCP server source code is uploaded to a private hosting service
2. Build & Deploy: The server builds and deploys your MCP server in a secure environment
3. Proxy Generation: A proxy npm package is automatically generated and published
4. Client Connection: Users install your npm package, which proxies requests to your hosted server

Features

• 🔒 Private Source Code: Keep your MCP server implementation private
• 📦 NPM Compatibility: Publish as a standard npm package
• 🚀 Automatic Deployment: Seamless build and deployment process
• ✅ NPM Validation: Validates package permissions and version compatibility
• 📋 Smart File Detection: Automatically detects necessary files for deployment
• 🧹 Clean Process: Handles temporary files and cleanup automatically

Installation

npm install -g mcp-npm-tool

Setup

1. Create Environment Configuration

Create a .tool-env file in your project root with the required tokens:

AUTH_TOKEN=your_deployment_auth_token
NPM_TOKEN=your_npm_auth_token

2. Configure NPM Authentication

Create a .npmrc file in your project root:

//registry.npmjs.org/:_authToken=YOUR_NPM_TOKEN_HERE

3. Project Requirements

Your project must have:

• A valid package.json with a bin field (required for MCP servers)
• A tsconfig.json or tsconfig.build.json file
• Source code in directories specified by your TypeScript configuration

Usage

Navigate to your MCP server project directory and run:

npx mcp-npm-tool

Process Flow

1. 🔍 Environment Validation: Reads authentication tokens from .tool-env
2. 📦 Package Analysis: Parses package.json and TypeScript configuration
3. ✅ NPM Validation:
   • Checks if package exists on npm registry
   • Validates version is higher than existing versions
   • Verifies publish permissions
4. 📋 File Collection: Automatically detects files needed for deployment
5. 📦 Compression: Creates a zip archive of necessary files
6. 📤 Upload: Securely uploads to the hosting service
7. 🧹 Cleanup: Removes temporary files

File Inclusion

The tool automatically includes:

Always Included

• package.json
• tsconfig.json or tsconfig.build.json

Source Code (from TypeScript config)

• Files matching include patterns (default: src/**/*)
• Excludes files matching exclude patterns

Additional Files (if present)

• README.md, LICENSE, CHANGELOG.md
• .npmignore, .gitignore
• Build configuration files:
  • jest.config.js/ts, webpack.config.js, rollup.config.js
  • vite.config.js/ts, babel.config.js/json, .babelrc
  • eslint.config.js, .eslintrc.js/json
  • prettier.config.js, .prettierrc

Excluded Files

• dist/**/* (build artifacts)
• node_modules/**/* (dependencies)
• .git/**/* (git history)
• Other temporary files and build outputs

API Endpoint

The tool uploads to: https://package.wildcoder.me/api/upload

Example MCP Server Package Structure

my-mcp-server/
├── package.json          # Must include "bin" field
├── tsconfig.json
├── .tool-env             # AUTH_TOKEN and NPM_TOKEN
├── .npmrc                # NPM authentication
├── src/
│   ├── index.ts          # Your MCP server entry point
│   └── lib/
│       └── handlers.ts   # Your MCP server logic
└── README.md

package.json Requirements

Your package.json must include a bin field for MCP servers:

{
  "name": "my-mcp-server",
  "version": "1.0.0",
  "bin": {
    "my-mcp-server": "./dist/index.js"
  },
  "main": "./dist/index.js",
  "files": ["dist/**/*"],
  "scripts": {
    "build": "tsc",
    "prepublishOnly": "npm run build"
  }
}

Development

# Install dependencies
pnpm install

# Build the tool
pnpm run build

# Test locally
node dist/index.js

Error Handling

The tool provides comprehensive error messages for common issues:

• Missing authentication tokens
• Invalid package.json or TypeScript configuration
• NPM permission issues
• Version conflicts
• Network connectivity problems

Security

• Authentication tokens are never logged or exposed
• Source code is transmitted securely to the hosting service
• NPM tokens are validated before any operations

License

ISC