feat: Publish MCP server to npm as gsd-mcp-server v0.2.1

[vscarpenter]

Summary

Published the GSD Task Manager MCP Server to npm for easy installation and usage. Users can now install and run the MCP server via npx gsd-mcp-server without any build steps.

Published Package

• Package Name: gsd-mcp-server
• Version: 0.2.1
• npm URL: https://www.npmjs.com/package/gsd-mcp-server
• Installation: npx gsd-mcp-server
• Package Size: 16.5 kB (compressed), 57.8 kB (unpacked)

Changes

Package Publishing

• ✅ Published to npm as gsd-mcp-server (unscoped package for simplicity)
• ✅ Deprecated @vscarpenter/gsd-mcp-server in favor of unscoped version
• ✅ Version bumped from 0.2.0 → 0.2.1 with updated README

New Files

• .npmignore - Excludes test scripts, dev files, and sensitive configs from published package
• LICENSE - MIT license file required for npm publishing

Package Configuration (package.json)

• Added npm metadata: repository, homepage, bugs URLs
• Added files field to whitelist publishable content (dist/, README.md, LICENSE)
• Added types field for TypeScript declaration files
• Added prepublishOnly script for automatic builds before publish
• Enhanced keywords for better npm discoverability

Documentation (README.md)

• ✨ Added Quick Start section with npx gsd-mcp-server example
• 📦 Added npm version and license badges at top
• 🔧 Updated installation to prioritize published package over local build
• 📝 Included both npx and local build Claude Desktop configurations
• 🌐 Updated all API URLs to production (https://gsd.vinny.dev)
• 🛠️ Added publishing instructions to Development section
• 🐛 Enhanced troubleshooting for npx-specific issues

Security Improvements

• .gitignore - Added patterns to exclude sensitive config files:
  • **/claude-config.json (except examples)
  • packages/mcp-server/test-*.sh (contain hardcoded credentials)
  • packages/mcp-server/debug-*.sh (may contain tokens)
  • worker/cf-dev-config.json (sensitive Worker config)
• .npmignore - Prevents test scripts with hardcoded user IDs/tokens from being published
• Removed worker/cf-dev-config.json from repository (contained sensitive data)

Installation for Users

Before (v0.2.0)

# Had to clone repo, install deps, build
git clone https://github.com/vscarpenter/gsd-task-manager.git
cd gsd-task-manager/packages/mcp-server
npm install
npm run build

After (v0.2.1)

# Just use npx - no installation needed!
npx gsd-mcp-server

Claude Desktop Configuration

Users can now add to their config with:

{
  "mcpServers": {
    "gsd-tasks": {
      "command": "npx",
      "args": ["-y", "gsd-mcp-server"],
      "env": {
        "GSD_API_URL": "https://gsd.vinny.dev",
        "GSD_AUTH_TOKEN": "your-jwt-token",
        "GSD_ENCRYPTION_PASSPHRASE": "your-passphrase"
      }
    }
  }
}

Testing

• ✅ Published successfully to npm
• ✅ Scoped package (@vscarpenter/gsd-mcp-server) deprecated with redirect message
• ✅ Package installable via npx gsd-mcp-server
• ✅ No sensitive data included in published package
• ✅ README displays correctly on npm package page

Breaking Changes

None - this is purely additive. Users can still build from source if desired.

---

🤖 Generated with Claude Code

[claude]

PR Review: Publishing MCP Server to npm (v0.2.1)

✅ Overall Assessment

This is a well-executed npm publishing PR that significantly improves the user experience. The changes are clean, security-conscious, and follow best practices for package publishing.

---

🎯 Strengths

1. Security Improvements ⭐⭐⭐⭐⭐

• Excellent .npmignore configuration preventing test scripts with hardcoded credentials from being published
• Removed sensitive worker/cf-dev-config.json from repository (contained CloudFront distribution config)
• Added comprehensive .gitignore patterns to prevent future credential leaks
• Security comment in .npmignore line 15 clearly documents the risk

2. Package Configuration

• Proper use of files field (whitelist approach) - more secure than .npmignore alone
• prepublishOnly script ensures package is always built before publishing
• Added types field for TypeScript declaration files - good developer experience
• Comprehensive metadata (repository, homepage, bugs) - follows npm best practices
• Enhanced keywords for better discoverability

3. Documentation Quality

• Clear distinction between npx (recommended) and local build paths
• Added badges (npm version, MIT license) for quick reference
• Troubleshooting section updated for npx-specific issues
• Publishing instructions added for maintainers

4. Migration Path

• Unscoped package name (gsd-mcp-server) is simpler than scoped @vscarpenter/gsd-mcp-server
• Old scoped package deprecated with redirect message (good user experience)

---

🔍 Issues & Recommendations

🟡 MEDIUM: Missing Shebang Check in bin

Issue: The bin field in package.json points to dist/index.js, but we should verify the compiled file has the shebang line.

Check: Does dist/index.js contain #!/usr/bin/env node after compilation?

• ✅ Source file (src/index.ts:1) has shebang
• ⚠️ TypeScript doesn't preserve shebangs by default in output

Recommendation:

1. Verify the compiled dist/index.js starts with #!/usr/bin/env node
2. If missing, add a post-build script to prepend it, or update tsconfig with preserveShebang: true (TS 5.0+)

# Test locally
npm pack
tar -xzf gsd-mcp-server-0.2.1.tgz
head -n1 package/dist/index.js  # Should show #!/usr/bin/env node

🟡 MEDIUM: .npmignore Overlap with files Field

Issue: Using both .npmignore (55 lines) and files field (package.json:11-15) creates dual exclusion logic.

Best Practice: When using files whitelist, .npmignore is redundant (npm ignores files not in files array by default).

Recommendation:

• Remove .npmignore entirely, OR
• Remove files field and rely only on .npmignore blacklist

The files whitelist approach is more secure (can't accidentally publish sensitive files), so I'd recommend removing .npmignore.

// Current package.json (keep this)
"files": [
  "dist/**/*",
  "README.md",
  "LICENSE"
]

🟢 MINOR: .env.example Should Be Published

Issue: Line 27 in .npmignore excludes .env.example, but example env files are helpful for users.

Recommendation: Change line 27-28 to:

 # Environment files
 .env
-.env.*
+.env.local
+.env.*.local
+!.env.example

This allows .env.example while still excluding actual environment files.

Note: If using files whitelist (see previous issue), this is moot since .env.example won't be published anyway unless explicitly added.

🟢 MINOR: Package Size Could Be Optimized

Observation: Package is 16.5 kB compressed, 57.8 kB unpacked (per PR description).

Potential savings:

• dist/**/*.map files (source maps) add ~40% to package size
• dist/**/*.d.ts.map (declaration maps) are only needed for library development

Recommendation (optional, not blocking):

// package.json
"files": [
  "dist/**/*.js",
  "dist/**/*.d.ts",
  "README.md",
  "LICENSE"
]

Or keep maps for better debugging experience (current approach is fine).

🟢 MINOR: TypeScript Configuration - Declaration Maps

Observation: tsconfig.json:15 enables declarationMap: true, which generates .d.ts.map files.

Question: Are declaration maps needed for an MCP server (executable, not a library)?

Recommendation (low priority):

• For an executable package, you could disable declarationMap to reduce package size
• For a library, keep them enabled for better IDE navigation

---

🧪 Testing Recommendations

Before merging, please verify:

# 1. Test local installation
npm pack
npm install -g ./gsd-mcp-server-0.2.1.tgz
gsd-mcp-server  # Should start without errors

# 2. Test npx execution
npx gsd-mcp-server@0.2.1  # Should work after publishing

# 3. Verify shebang in built file
head -n1 dist/index.js

# 4. Check published contents
npm pack
tar -tzf gsd-mcp-server-0.2.1.tgz | head -20

---

📋 Code Quality Checklist

• ✅ Clear, semantic commit message and PR description
• ✅ No hard-coded secrets or credentials
• ✅ Proper version bump (0.2.0 → 0.2.1)
• ✅ MIT license included
• ✅ README updated with installation instructions
• ✅ Follows repository coding standards (CLAUDE.md)
• ✅ Security-conscious .gitignore patterns
• ⚠️ Tests: No test coverage changes (N/A for publishing PR)
• ⚠️ Shebang preservation needs verification

---

🎬 Verdict

APPROVE with minor suggestions ✅

This PR is ready to merge after verifying the shebang issue. The security improvements alone make this valuable. The .npmignore vs files redundancy is a code quality issue, not a blocker.

Post-merge actions:

1. Verify npx gsd-mcp-server works after npm publish
2. Update CLAUDE.md to reflect new installation method (if not already done)
3. Consider deprecating old @vscarpenter/gsd-mcp-server with clear migration message

---

📊 Impact Summary

User Experience: ⭐⭐⭐⭐⭐ (5/5) - Transforms installation from 5 steps to 1 command
Security: ⭐⭐⭐⭐⭐ (5/5) - Excellent credential leak prevention
Code Quality: ⭐⭐⭐⭐☆ (4/5) - Minor redundancy, otherwise excellent
Documentation: ⭐⭐⭐⭐⭐ (5/5) - Clear, comprehensive, well-structured

Overall: ⭐⭐⭐⭐⭐ (4.75/5)

Great work on this release! 🎉

---

Review generated by Claude Code following coding-standards.md and CLAUDE.md guidelines.