[Enhancement] Package for NPM distribution with global CLI installation support

[jdutton]

📦 MCP Framework Extraction & NPM Distribution

Overview

Extract the MCP server infrastructure (OAuth, transport, session management) into a reusable framework that enables developers to build multiple MCP servers with custom tool sets, while also packaging the current server for easy npm installation.

Strategic Vision

This proposal combines two complementary goals:

1. Framework Extraction: Create @mcp-framework/core for building custom MCP servers
2. Reference Implementation: Package current server as mcp-server-advanced using the framework

Problem Statement

Current Architecture: Monolithic server with infrastructure (OAuth, transport, session) tightly coupled to business logic (tools).

Challenges:

• Can't reuse OAuth/transport infrastructure for different tool sets
• Building new MCP servers requires copying entire codebase
• Tools are hardcoded in src/server/mcp-setup.ts
• Infrastructure changes require updating all tool implementations

Opportunity: The infrastructure is production-ready but not reusable. Extract it into a framework.

Proposed Architecture

Phase 1: Framework Extraction (@mcp-framework/core)

Create a reusable framework package that provides:

Core Infrastructure:

• ✅ Multi-provider OAuth (Google, GitHub, Microsoft, Generic)
• ✅ Dynamic Client Registration (RFC 7591/7592)
• ✅ Transport abstraction (STDIO, Streamable HTTP)
• ✅ Session management with resumability
• ✅ Security middleware (CORS, Helmet, DCR auth)
• ✅ Observability (OpenTelemetry integration)
• ✅ Environment configuration

Framework API:

import { MCPFramework, ToolHandler } from '@mcp-framework/core';

// Define custom tools
const myTools: ToolHandler[] = [
  {
    name: 'my-tool',
    description: 'Does something specific',
    inputSchema: { /* JSON Schema */ },
    handler: async (args) => {
      // Tool implementation
      return { content: [{ type: 'text', text: 'Result' }] };
    }
  }
];

// Create and start server
const framework = new MCPFramework({
  name: 'my-mcp-server',
  version: '1.0.0',
  tools: myTools,
  
  // Optional LLM integration
  llm: {
    providers: ['claude', 'openai'],
    defaultProvider: 'claude'
  }
});

await framework.start();

Package Structure:

@mcp-framework/core/
├── src/
│   ├── auth/                    # OAuth system
│   │   ├── factory.ts          # Multi-provider factory
│   │   ├── providers/          # Provider implementations
│   │   ├── stores/             # Storage abstractions
│   │   └── discovery-metadata.ts
│   ├── transport/              # Transport layer
│   │   ├── factory.ts          # STDIO + HTTP
│   │   └── types.ts
│   ├── server/                 # HTTP server
│   │   ├── streamable-http-server.ts
│   │   ├── routes/             # Health, OAuth, DCR
│   │   └── instance-manager.ts
│   ├── session/                # Session management
│   ├── config/                 # Environment config
│   ├── observability/          # OpenTelemetry
│   └── framework.ts            # Main API
└── package.json

Phase 2: Optional LLM Plugin (@mcp-framework/llm)

Separate package for LLM integration:

import { MCPFramework } from '@mcp-framework/core';
import { LLMPlugin } from '@mcp-framework/llm';

const framework = new MCPFramework({
  name: 'my-server',
  tools: myTools,
  plugins: [
    new LLMPlugin({
      providers: ['claude', 'openai', 'gemini'],
      defaultProvider: 'claude'
    })
  ]
});

Phase 3: Reference Implementation (mcp-server-advanced)

Convert current server to use framework:

// This repository becomes a reference implementation
import { MCPFramework } from '@mcp-framework/core';
import { LLMPlugin } from '@mcp-framework/llm';
import { basicTools } from './tools/basic.js';

const framework = new MCPFramework({
  name: 'mcp-typescript-simple',
  version: '1.0.0',
  tools: basicTools,
  plugins: [
    new LLMPlugin({
      providers: ['claude', 'openai', 'gemini']
    })
  ]
});

await framework.start();

Add CLI wrapper (Issue #3 original proposal):

# Global installation
npm install -g mcp-server-advanced

# Interactive setup
mcp-server-advanced --init

# Quick start
mcp-server-advanced --oauth google --mode streamable_http

# Development mode
mcp-server-advanced --dev

Phase 4: Template Repository

Create mcp-server-template for quick starts:

npx create-mcp-server my-database-mcp
cd my-database-mcp
npm install
npm start

Generated project structure:

my-database-mcp/
├── src/
│   ├── index.ts              # Server entry point
│   └── tools/                # Custom tool implementations
│       └── database.ts
├── package.json              # Depends on @mcp-framework/core
├── .env.example
└── README.md

Implementation Plan

Stage 1: Core Framework Extraction (1 week)

• Create @mcp-framework/core package structure
• Extract auth, transport, server, session modules
• Design and implement MCPFramework class API
• Create ToolHandler interface for plugin system
• Port tests to framework package
• Document framework API

Stage 2: LLM Plugin Extraction (3 days)

• Create @mcp-framework/llm package
• Extract LLM manager and providers
• Implement plugin interface
• Add LLM-specific tool helpers
• Document LLM plugin usage

Stage 3: Convert Current Server (2 days)

• Update mcp-typescript-simple to use framework
• Refactor tools to use ToolHandler interface
• Verify all existing functionality works
• Update existing tests
• Ensure backward compatibility

Stage 4: CLI & NPM Packaging (3 days)

• Create bin/mcp-server.js CLI entry point
• Add command-line argument parsing (commander.js)
• Implement interactive setup wizard (inquirer.js)
• Add configuration validation and helpers
• Update package.json for npm publishing
• Create .npmignore for clean packaging

Stage 5: Documentation & Examples (2 days)

• Framework API documentation
• Tool development guide
• OAuth setup guide (framework context)
• Example implementations (database, analytics, etc.)
• Migration guide for existing users
• Publishing guide

Stage 6: Template Generator (2 days)

• Create create-mcp-server CLI tool
• Add project templates (basic, database, API)
• Interactive project wizard
• Documentation and examples

Use Cases Enabled

Use Case 1: Custom Database MCP Server

import { MCPFramework } from '@mcp-framework/core';

const dbTools = [
  {
    name: 'query',
    description: 'Execute SQL query',
    inputSchema: { /* ... */ },
    handler: async ({ sql }) => {
      const results = await db.query(sql);
      return { content: [{ type: 'text', text: JSON.stringify(results) }] };
    }
  }
];

const server = new MCPFramework({
  name: 'database-mcp-server',
  version: '1.0.0',
  tools: dbTools
});

Use Case 2: Analytics MCP Server

import { MCPFramework } from '@mcp-framework/core';

const analyticsTools = [
  { name: 'get-metrics', /* ... */ },
  { name: 'create-report', /* ... */ },
  { name: 'export-data', /* ... */ }
];

const server = new MCPFramework({
  name: 'analytics-mcp-server',
  version: '1.0.0',
  tools: analyticsTools
});

Use Case 3: Global CLI Installation (Original Issue #3)

npm install -g mcp-server-advanced
mcp-server-advanced --help
mcp-server-advanced --oauth google --mode streamable_http

Benefits

For Framework Users (Developers)

• ✨ Reusable Infrastructure: Don't rebuild OAuth/transport for each server
• 🚀 Rapid Development: Focus on tools, not plumbing
• 📦 Production Ready: Battle-tested infrastructure
• 🔐 Security Built-in: OAuth, DCR, session management
• 📊 Observability: OpenTelemetry integration included
• 🎯 Type Safety: Full TypeScript support

For End Users (Original Issue #3)

• 🎉 Easy Installation: Single npm install -g command
• 🔧 Interactive Setup: Guided configuration wizard
• 📚 Discoverability: Listed in npm registry
• 🌟 Professional Package: Industry-standard distribution

For Ecosystem

• 🌍 Standardization: Common infrastructure for MCP servers
• 🤝 Community: Shared improvements benefit everyone
• 📈 Adoption: Lower barrier to building MCP servers
• 🏗️ Architecture: Clean separation of concerns

Technical Requirements

Framework Package

• ✅ Zero breaking changes to consumers after v1.0
• ✅ Full backward compatibility with MCP SDK
• ✅ Comprehensive TypeScript types
• ✅ Extensive test coverage (>90%)
• ✅ Semantic versioning
• ✅ Clear deprecation policy

Reference Implementation

• ✅ 100% feature parity with current server
• ✅ All existing tests pass
• ✅ Performance equivalent or better
• ✅ Documentation updated

CLI/NPM Package

• ✅ Cross-platform (Windows, macOS, Linux)
• ✅ Interactive setup wizard
• ✅ Clear error messages
• ✅ Health check commands
• ✅ Configuration validation

Repository Structure (Post-Implementation)

Option A: Monorepo

mcp-typescript-simple/          # Monorepo root
├── packages/
│   ├── core/                   # @mcp-framework/core
│   ├── llm/                    # @mcp-framework/llm
│   ├── server/                 # mcp-server-advanced (reference impl)
│   └── create-mcp-server/      # Project generator
├── examples/
│   ├── database-server/
│   ├── analytics-server/
│   └── minimal-server/
└── docs/

Option B: Separate Repos

• mcp-framework-core → @mcp-framework/core
• mcp-framework-llm → @mcp-framework/llm
• mcp-typescript-simple → Reference implementation + CLI
• mcp-server-template → Template repository

Migration Path

For Existing Users

No breaking changes - server continues to work with optional migration:

// Before (still works)
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
// Current implementation

// After (optional migration)
import { MCPFramework } from '@mcp-framework/core';
// Simplified implementation

For New Users

Choose your path:

1. Use framework directly: Build custom server
2. Use reference implementation: Install mcp-server-advanced
3. Use template: Generate new project with create-mcp-server

Success Metrics

Framework Adoption

• 10+ custom servers built on framework (6 months)
• 100+ npm downloads/week
• 5+ community contributions

CLI/Package Usage

• 1000+ npm downloads (3 months)
• Positive user feedback (>4.5 stars)
• <5 min average setup time

Community Impact

• Featured in MCP ecosystem documentation
• Conference/blog mentions
• Active community discussions

Estimated Effort

Total: 3-4 weeks

• Framework extraction: 1 week
• LLM plugin: 3 days
• Server conversion: 2 days
• CLI/NPM packaging: 3 days
• Documentation: 2 days
• Template generator: 2 days
• Testing & polish: 3 days

Priority

High - Enables ecosystem growth and addresses multiple user needs simultaneously.

Related Issues

• Replaces original Issue [Enhancement] Package for NPM distribution with global CLI installation support #3 proposal with broader framework approach
• Incorporates OAuth multi-provider enhancement
• Addresses session management scalability
• Enables horizontal scaling of MCP servers

Questions for Discussion

1. Repository Strategy: Monorepo or separate repos?
2. Package Naming: @mcp-framework/* or different namespace?
3. Versioning: How to version framework vs implementations?
4. LLM Plugin: Core or separate package?
5. Breaking Changes: Deprecation policy for framework?

Acceptance Criteria

Framework Package

• Published to npm as @mcp-framework/core
• Full API documentation
• >90% test coverage
• Examples in README

Reference Implementation

• All existing functionality preserved
• CLI working on all platforms
• Interactive setup wizard functional
• Published as mcp-server-advanced

Template Generator

• npx create-mcp-server works
• Generates working project
• Multiple templates available

Documentation

• Framework API reference
• Tool development guide
• Migration guide
• Example implementations

---

Status: Proposal - Awaiting feedback and approval
Updated: 2025-10-16 (Expanded from original Issue #3)