MCP_SAMPLING.md

MCP Sampling Provider Re-implementation Plan

This document outlines the detailed plan for refactoring the MCP Sampling provider to follow the custom AI SDK pattern, as exemplified by the claude-code provider.

1. Directory and File Structure

We will start by creating the following directory and file structure:

src/
└── ai-providers/
    ├── custom-sdk/
    │   └── mcp-sampling/
    │       ├── index.js
    │       ├── language-model.js
    │       ├── message-converter.js
    │       ├── errors.js
    │       └── types.js
    └── mcp-sampling.js

2. Implementation Details

2.1. src/ai-providers/custom-sdk/mcp-sampling/types.js

This file will define the JSDoc types for the MCP Sampling provider. This will include types for:

• McpSamplingSettings: Configuration options for the provider.
• McpSamplingModelId: The model IDs supported by the provider.
• McpSamplingErrorMetadata: Metadata for custom errors.
• McpSamplingProvider: The provider interface.
• McpSamplingProviderSettings: Settings for the provider factory.

2.2. src/ai-providers/custom-sdk/mcp-sampling/errors.js

This file will create custom error classes for the provider, including:

• createApiCallError: For general API errors.
• createAuthenticationError: For authentication-related errors.
• createTimeoutError: For timeout errors.

2.3. src/ai-providers/custom-sdk/mcp-sampling/message-converter.js

This file will contain the logic to convert the AI SDK prompt format to the format expected by the MCP Sampling service. It will export a convertToMcpSamplingMessages function.

2.4. src/ai-providers/custom-sdk/mcp-sampling/language-model.js

This file will contain the core logic of the provider in the McpSamplingLanguageModel class. This class will:

• Implement the doGenerate method for text and object generation.
• Implement the doStream method for streaming responses.
• Handle authentication and session management.
• Manage the connection to the MCP Sampling service.
• Properly handle errors and warnings.

2.5. src/ai-providers/custom-sdk/mcp-sampling/index.js

This file will be the entry point for the custom SDK. It will:

• Export a createMcpSampling factory function that creates an instance of the McpSamplingLanguageModel.
• Export the McpSamplingLanguageModel class.
• Export the error handling functions from errors.js.

2.6. src/ai-providers/mcp-sampling.js

This file will be the main provider file that integrates with the rest of the application. It will:

• Import createMcpSampling from the custom SDK.
• Export a McpSamplingProvider class that extends BaseAIProvider.
• Implement the getClient method to return a new McpSamplingLanguageModel instance.

3. Testing

We will create a comprehensive suite of tests for the new provider:

• Unit Tests: In tests/unit/ai-providers/, we will create mcp-sampling.test.js to test the individual components of the provider, including the language model, message converter, and error handling.
• Integration Tests: In tests/integration/, we will create tests to verify the provider's interaction with a mock MCP Sampling service. This will ensure that the provider can correctly handle requests and responses.

4. Migration

Once the new provider is implemented and tested, we will perform the following steps to migrate to the new implementation:

1. Update src/ai-providers/index.js to export the new McpSamplingProvider.
2. Remove the old MCP Sampling provider implementation from the codebase.
3. Update any code that uses the old provider to use the new provider.
4. Run all tests to ensure that the migration was successful.