Publish MCP server packages to npm registry

[jdutton]

Goal

Publish the MCP server packages to npm registry so users can easily install and run the server using:

# STDIO mode (Claude Desktop, MCP Inspector, etc.)
npx -y @mcp-typescript-simple/example-mcp

# Or install globally
npm install -g @mcp-typescript-simple/example-mcp
example-mcp  # Run from anywhere

Current State

• ✅ Package already configured: @mcp-typescript-simple/example-mcp
• ✅ Binary entry point set: bin/example-mcp → dist/index.js
• ✅ Shebang present: #!/usr/bin/env node
• ✅ Default mode: STDIO (no MCP_MODE env var needed)
• ❌ Not yet published to npm registry
• ⚠️ Documentation references this command before it's available

How STDIO Mode Works

The server automatically defaults to STDIO mode when no MCP_MODE environment variable is set:

// packages/config/src/environment.ts
static getTransportMode(): TransportMode {
  const mode = this.get().MCP_MODE;
  switch (mode) {
    case 'streamable_http':
      return TransportMode.STREAMABLE_HTTP;
    default:
      return TransportMode.STDIO;  // Default mode
  }
}

This means npx -y @mcp-typescript-simple/example-mcp will:

1. Download and execute the package
2. Run dist/index.js (the binary entry point)
3. Automatically use STDIO transport (default)
4. Work seamlessly with Claude Desktop, MCP Inspector, etc.

Required Tasks

1. Package Configuration

• ✅ Package name: @mcp-typescript-simple/example-mcp (already correct)
• ✅ Binary configured in package.json (already correct)
• Verify files array includes all necessary built assets
• Set publishConfig.access to "public" for scoped package
• Add repository, homepage, and bugs URLs
• Verify all dependencies are correctly listed (not using workspace:*)

2. Build and Bundle Verification

• Run npm run build in packages/example-mcp
• Verify dist/ directory contains all necessary files
• Test built package locally: node dist/index.js (should run in STDIO mode)
• Verify all internal dependencies are bundled or properly referenced

3. NPM Authentication Setup

• Create npm account for @mcp-typescript-simple organization (or individual account)
• Generate NPM_TOKEN with publish permissions
• Add NPM_TOKEN to GitHub repository secrets
• Test token authentication locally

4. Versioning Strategy

• Decide initial version (recommend 1.0.0 since it's production-ready)
• Create .changeset configuration for automated versioning (optional)
• OR use manual versioning with npm version commands

5. CI/CD Publishing Workflow

• Create .github/workflows/publish-npm.yml
• Trigger on version tags (e.g., v1.0.0)
• Build all packages
• Run validation tests
• Publish to npm registry
• Create GitHub release with changelog

6. Testing Installation

After publishing, test:

• npx -y @mcp-typescript-simple/example-mcp works
• Claude Desktop integration works with npx command
• MCP Inspector can connect with npx command
• Global installation works: npm i -g @mcp-typescript-simple/example-mcp && example-mcp

7. Documentation Updates

• Update docs/homepage.md (already has correct command)
• Update README.md with npm installation instructions
• Update CLAUDE.md developer docs
• Add badge to README: npm version shield

Example Claude Desktop Configuration

After publishing, users will be able to use:

{
  "mcpServers": {
    "typescript-simple": {
      "command": "npx",
      "args": ["-y", "@mcp-typescript-simple/example-mcp"]
    }
  }
}

This is already documented in docs/homepage.md lines 28-37.

Priority

Medium - Currently blocks simplified user onboarding, but project is functional through hosted deployment

Related Files

• packages/example-mcp/package.json (main package to publish)
• packages/example-mcp/src/index.ts (entry point with shebang)
• packages/config/src/environment.ts (transport mode logic)
• docs/homepage.md (already has correct instructions)
• README.md (needs npm installation docs)
• .github/workflows/ (for automated publishing)