Skip to content

Instantly share code, notes, and snippets.

@ben-vargas

ben-vargas/MCP_SAMPLING_PRD.md

Created June 26, 2025 07:32
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save ben-vargas/d5786fb1a3f8d35ade1058a3b5d50d86 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save ben-vargas/d5786fb1a3f8d35ade1058a3b5d50d86 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
MCP_SAMPLING_PRD.md

PRD: MCP Sampling as a Custom AI SDK Provider

1. Background

The initial implementation of the MCP (Model Context Protocol) Sampling provider was done as a custom, one-off solution. While functional, it did not align with the established architectural pattern for AI providers in this project, exemplified by the claude-code provider. The current standard is to encapsulate provider-specific logic within a custom AI SDK structure, which promotes modularity, maintainability, and consistency across the codebase.

The feedback on PR #863 highlighted the need to refactor the MCP Sampling provider to follow this established pattern. This document outlines the requirements for that re-implementation.

2. Objective

To refactor the MCP Sampling provider into a custom AI SDK provider, mirroring the structure and implementation of the existing claude-code provider. This will improve the long-term health of the codebase by ensuring all AI providers adhere to a single, consistent architectural pattern.

3. Requirements

Functional Requirements

  • FR1: Provider Registration: The MCP Sampling provider must be registered and available to the application just like any other AI provider.
  • FR2: Authentication: The provider must use the existing MCP session for authentication and not require a separate API key.
  • FR3: generateText Support: The provider must implement the generateText method to generate text completions.
  • FR4: generateObject Support: The provider must implement the generateObject method to generate structured JSON objects.
  • FR5: Streaming Support: The provider must implement the streamText method to support streaming responses.
  • FR6: Error Handling: The provider must implement robust error handling for common issues such as authentication failures, timeouts, and API errors.
  • FR7: Configuration: The provider should be configurable with settings relevant to the MCP Sampling service.

Non-Functional Requirements

  • NFR1: Architectural Consistency: The provider's implementation must follow the custom AI SDK pattern established by the claude-code provider.
  • NFR2: Testability: The provider must be fully unit-tested and integration-tested.
  • NFR3: Maintainability: The code should be well-documented, modular, and easy to understand and maintain.
  • NFR4: Performance: The provider should not introduce any significant performance regressions.

4. Scope

In Scope

  • Creating a new mcp-sampling custom AI SDK directory.
  • Implementing the MCP Sampling provider logic within this new structure.
  • Creating a new McpSamplingProvider class.
  • Updating the provider index to include the new provider.
  • Writing comprehensive unit and integration tests for the new provider.
  • Removing the old MCP Sampling provider implementation.

Out of Scope

  • Adding new features or capabilities to the MCP Sampling service itself.
  • Refactoring any other AI providers.
  • Making any changes to the MCP protocol.

5. Success Metrics

  • The new McpSamplingProvider is successfully integrated into the application.
  • The old MCP Sampling provider implementation is completely removed from the codebase.
  • All unit and integration tests for the new provider pass.
  • The code for the new provider is successfully reviewed and merged.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment