🚀 MCP Proxy Wrapper

npm install mcp-proxy-wrapper

A proxy wrapper that adds hooks, plugins, and custom logic to existing MCP servers without modifying the original code.

🎯 Overview

Add functionality to your existing MCP server:

import { wrapWithProxy, LLMSummarizationPlugin } from 'mcp-proxy-wrapper';
 
// Your existing server - no changes needed
const server = new McpServer({ name: 'My Server', version: '1.0.0' });
server.tool('getData', schema, getData);
 
// Add plugins and hooks
const plugin = new LLMSummarizationPlugin();
plugin.updateConfig({
  options: {
    provider: 'openai',
    openaiApiKey: process.env.OPENAI_API_KEY
  }
});
 
const enhanced = await wrapWithProxy(server, {
  plugins: [plugin],
  hooks: {
    beforeToolCall: async (context) => {
      console.log(`🔧 ${context.toolName}`);
      // Add auth, rate limiting, etc.
    }
  }
});

Result: Your server now has AI summarization, logging, and custom hooks without any code changes.

✨ Key Features

• 🔧 Zero Code Changes - Wrap existing servers instantly
• 🤖 AI Integration - OpenAI-powered response summarization
• 🪝 Hook System - beforeToolCall/afterToolCall with full control
• 🔌 Plugin Architecture - Reusable, composable functionality
• 🌐 Remote Servers - Proxy external MCP servers over HTTP/WebSocket
• 🛡️ Authentication & Security - Auth, rate limiting, access control patterns
• 📊 Comprehensive Tests - 273 tests covering MCP protocol compatibility

🚀 Common Use Cases

const secure = await wrapWithProxy(server, {
  hooks: {
    beforeToolCall: async (context) => {
      if (!await validateApiKey(context.args.apiKey)) {
        return { 
          result: { 
            content: [{ type: 'text', text: 'Unauthorized' }], 
            isError: true 
          }
        };
      }
    }
  }
});

🧪 Technical Details

• 273 passing tests with real MCP client-server communication
• Comprehensive error handling with fallbacks and proper error propagation
• TypeScript native with full type safety and IntelliSense
• MCP SDK v1.6.0+ compatible with any existing server

🚀 Quick Navigation

⭐ Key Features

🔧 How the Proxy Wrapper Works with Tools

1. Tools registered BEFORE wrapping: Remain fully available and functional, but don't get enhanced with hooks/plugins
2. Tools registered AFTER wrapping: Get full plugin functionality (summarization, memory, analytics, etc.)
3. All underlying server functionality: Completely preserved (resources, prompts, metadata, transport)

The proxy wrapper intercepts the server.tool() method registration process, not the tools themselves. So when you call wrapWithProxy(server), it overrides how new tools are registered to add the hook functionality, but existing tools continue to work exactly as before.

📖 This behavior is documented in detail in the Getting Started guide and How It Works section with examples showing the difference between enhanced and non-enhanced tools.

💻 Quick Example

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { wrapWithProxy, LLMSummarizationPlugin } from 'mcp-proxy-wrapper';
import { z } from 'zod';
 
// Create your MCP server
const server = new McpServer({ name: 'My AI Tools', version: '1.0.0' });
 
// Add AI enhancement plugin
const summarizationPlugin = new LLMSummarizationPlugin();
 
// Wrap with proxy functionality
const proxiedServer = await wrapWithProxy(server, {
  plugins: [summarizationPlugin]
});
 
// Register tools as usual - enhancement happens automatically
proxiedServer.tool('ai-analysis', {
  text: z.string()
}, async (args) => {
  return {
    content: [{ type: 'text', text: `Analysis result: ${args.text}` }]
  };
});