What is Mcp Sampling Service

mcp-sampling-service is a registry for flexible sampling strategies designed to work with the Model Context Protocol (MCP). It serves as a proof of concept for managing sampling strategies effectively.

Use cases

Use cases include integrating with AI models for adaptive sampling, customizing sampling strategies for specific applications, and enhancing model selection processes in various AI-driven projects.

How to use

To use mcp-sampling-service, install it via npm with ‘npm install mcp-sampling-service’. Initialize the service using the ‘initializeSamplingService’ function, either with default strategies or custom ones.

Key features

Key features include a plugin-based sampling strategy system, example integration with OpenRouter for intelligent model selection, and an extensible architecture that allows for custom strategy definitions.

Where to use

mcp-sampling-service can be used in applications that require dynamic sampling strategies, particularly in machine learning, AI model selection, and data processing environments.

mcp-sampling-service

🚧 UNDER CONSTRUCTION: This package is currently being developed and its API may change. Not recommended to be used directly in any production apps! 🚧

A proof of concept for a flexible sampling strategy registry to use with the Model Context Protocol (a.k.a. MCP).

Installation

npm install mcp-sampling-service

Features

• Plugin-based sampling strategy system
• Includes example OpenRouter and Anthropic integrations with intelligent model selection
• Extensible architecture

Initialization

The library uses a registry-based approach for managing sampling strategies. The recommended way to initialize the service is through the initializeSamplingService function:

import { initializeSamplingService } from 'mcp-sampling-service';

// Initialize with default strategies (stub, openrouter, and anthropic)
const registry = initializeSamplingService({
  useDefaultStrategies: true
});

// Or initialize with custom strategies
const registry = initializeSamplingService({
  useDefaultStrategies: false,
  additionalStrategies: {
    myStrategy: {
      factory: myStrategyFactory,
      definition: myStrategyDefinition
    }
  }
});

Configuration

OpenRouter Strategy Configuration

The OpenRouter strategy requires configuration for API access and model selection:

const strategy = registry.create('openrouter', {
  apiKey: "your-api-key-here",
  defaultModel: "anthropic/claude-3.5-sonnet",
  allowedModels: [
    {
      id: "openai/gpt-4",
      speedScore: 0.7,
      intelligenceScore: 0.9,
      costScore: 0.3
    },
    {
      id: "anthropic/claude-3.5-sonnet",
      speedScore: 0.9,
      intelligenceScore: 0.7,
      costScore: 0.8
    }
  ]
});

Model Selection Process

The OpenRouter strategy selects models based on:

1. Model hints (processed in order)
2. Priority scoring:
   • Speed priority (response time)
   • Intelligence priority (model capabilities)
   • Cost priority (token pricing)
3. Fallback to default model if no suitable match

Usage

Basic Usage

import { 
  initializeSamplingService,
  SamplingStrategy 
} from 'mcp-sampling-service';

// Initialize registry
const registry = initializeSamplingService();

// Create strategy instance
const strategy = registry.create('openrouter', {
  apiKey: "your-api-key-here",
  defaultModel: "anthropic/claude-3.5-sonnet"
});

// Use strategy
const result = await strategy.handleSamplingRequest({
  method: "sampling/createMessage",
  params: {
    messages: [
      {
        role: 'user',
        content: {
          type: 'text',
          text: 'Hello!'
        }
      }
    ],
    maxTokens: 1000,
    temperature: 0.2, // Optional, defaults to 0.2
    systemPrompt: "You are a helpful assistant", // Optional
    stopSequences: ["END"], // Optional
    modelPreferences: {
      speedPriority: 0.8,
      intelligencePriority: 0.6,
      costPriority: 0.4,
      hints: [
        { name: "gpt" }
      ]
    }
  }
});

Custom Strategy Implementation

import { 
  SamplingStrategy,
  SamplingStrategyDefinition,
  CreateMessageRequest,
  CreateMessageResult
} from 'mcp-sampling-service';

// Define your strategy's configuration requirements
const myStrategyDefinition: SamplingStrategyDefinition = {
  id: 'custom',
  name: 'Custom Strategy',
  requiresConfig: true,
  configFields: [
    {
      name: 'apiKey',
      type: 'string',
      label: 'API Key',
      required: true
    }
  ]
};

// Create your strategy factory
const myStrategyFactory = (config: Record<string, unknown>): SamplingStrategy => ({
  handleSamplingRequest: async (request: CreateMessageRequest): Promise<CreateMessageResult> => {
    // Your implementation here
    return {
      model: "custom-model",
      stopReason: "stop",
      role: "assistant",
      content: {
        type: "text",
        text: "Custom response"
      }
    };
  }
});

// Register your strategy
const registry = initializeSamplingService({
  useDefaultStrategies: true,
  additionalStrategies: {
    custom: {
      factory: myStrategyFactory,
      definition: myStrategyDefinition
    }
  }
});

API Reference

SamplingStrategyRegistry

Static class that manages sampling strategies:

• getInstance(): Get singleton instance
• register(name: string, factory: SamplingStrategyFactory, definition: SamplingStrategyDefinition): Register a strategy
• create(name: string, config: Record<string, unknown>): Create strategy instance
• getAvailableStrategies(): Get list of registered strategies

Request Parameters

interface SamplingParams {
  messages: SamplingMessage[];
  systemPrompt?: string;
  includeContext?: 'none' | 'thisServer' | 'allServers';
  temperature?: number;
  maxTokens: number;
  stopSequences?: string[];
  modelPreferences?: ModelPreferences;
}

interface ModelPreferences {
  hints?: Array<{ name?: string }>;
  costPriority?: number;
  speedPriority?: number;
  intelligencePriority?: number;
}

Built-in Strategies

Stub Strategy

Simple strategy that returns a fixed response. Useful for testing.

OpenRouter Strategy

Strategy that connects to OpenRouter’s API with intelligent model selection.

Configuration:

interface OpenRouterStrategyConfig {
  apiKey: string;
  defaultModel: string;
  allowedModels?: ModelConfig[];
}

interface ModelConfig {
  id: string;
  speedScore: number;    // 0-1 score for model speed
  intelligenceScore: number;  // 0-1 score for model capability
  costScore: number;     // 0-1 score for cost efficiency
}

Anthropic Strategy

Strategy that connects to Anthropic’s API with intelligent model selection.

Configuration:

interface AnthropicStrategyConfig {
  apiKey: string;
  model: string;  // e.g. "claude-3-5-sonnet-latest"
}

Example usage:

const strategy = registry.create('anthropic', {
  apiKey: "your-api-key-here",
  model: "claude-3-5-sonnet-latest"
});

Available default models with their characteristics:

• claude-3-7-sonnet-latest: Highest intelligence score, supports extended thinking
• claude-3-5-haiku-latest: Fastest response time, most cost-effective
• claude-3-5-sonnet-latest: Balanced performance and capabilities

The model selection process considers:

1. Context window requirements
2. Extended thinking capabilities (if required)
3. Priority scoring:
   • Speed priority (response time)
   • Intelligence priority (model capabilities)
   • Cost priority (token pricing)
4. Model hints for specific model preferences

Error Handling

The service provides structured error handling:

interface SamplingResponse {
  jsonrpc: '2.0';
  id: number;
  result?: {
    model: string;
    stopReason: string;
    role: 'assistant';
    content: {
      type: 'text';
      text: string;
    };
  };
  error?: {
    code: number;  // -32008 for SamplingError, -32009 for SamplingExecutionError
    message: string;
  };
}