Skip to content

docs: Document npm+npx deployment pattern for Node.js MCP servers#183

Closed
bryankthompson wants to merge 1 commit intomodelcontextprotocol:mainfrom
bryankthompson:docs/npx-deployment-pattern
Closed

docs: Document npm+npx deployment pattern for Node.js MCP servers#183
bryankthompson wants to merge 1 commit intomodelcontextprotocol:mainfrom
bryankthompson:docs/npx-deployment-pattern

Conversation

@bryankthompson
Copy link

Summary

Add minimal documentation for an alternative Node.js deployment pattern using npm and npx instead of bundling node_modules.

Motivation

This pattern is already in production use by multiple MCP servers but was undocumented. It complements PR #161 which documents the equivalent uvx pattern for Python.

Changes

MANIFEST.md

  • Add npx configuration example alongside traditional Node.js example

README.md

  • Add concise section on npm-based deployment
  • Include trade-offs comparison table
  • Link to example implementation

examples/npx-node/

  • Complete minimal working example
  • Demonstrates manifest and package.json configuration
  • Shows required bin entry setup

Pattern Overview

Manifest configuration:

{
  "mcp_config": {
    "command": "npx",
    "args": ["-y", "--package=your-package", "your-bin-command"]
  }
}

Benefits:

  • Smaller bundle sizes (< 50 KB vs 50-300 MB)
  • Automatic updates from npm
  • Zero bundle maintenance

Trade-offs:

  • Requires internet on first launch
  • 30-60 second initial download

Testing

  • ✅ Verified working with multiple production implementations
  • ✅ Confirmed npx invocation from Claude Desktop
  • ✅ Validated manifest schema compliance with mcpb validate

🤖 Generated with Claude Code

Add documentation for an alternative Node.js deployment pattern using
npm and npx instead of bundling node_modules. This complements the
existing uvx pattern for Python.

Changes:
- MANIFEST.md: Add npx configuration example
- README.md: Add npm-based deployment section with trade-offs table
- examples/npx-node/: Complete minimal working example

Benefits of this pattern:
- Smaller bundle sizes (< 50 KB vs 50-300 MB)
- Automatic updates from npm
- Zero bundle maintenance

Trade-offs:
- Requires internet on first launch
- 30-60 second initial download

🤖 Generated with [Claude Code](https://claude.com/claude-code)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant