feat: add support for MCP Sampling as AI provider (#863)
* feat: support MCP sampling * support provider registry * use standard config options for MCP provider * update fastmcp to support passing params to requestSampling * move key name definition to base provider * moved check for required api key to provider class * remove unused code * more cleanup * more cleanup * refactor provider * remove not needed files * more cleanup * more cleanup * more cleanup * update docs * fix tests * add tests * format fix * clean files * merge fixes * format fix * feat: add support for MCP Sampling as AI provider * initial mcp ai sdk * fix references to old provider * update models * lint * fix gemini-cli conflicts * ran format * Update src/provider-registry/index.js Co-authored-by: Ralph Khreish <35776126+Crunchyman-ralph@users.noreply.github.com> * fix circular dependency Circular Dependency Issue ✅ FIXED Root Cause: BaseAIProvider was importing from index.js, which includes commands.js and other modules that eventually import back to AI providers Solution: Changed imports to use direct paths to avoid circular dependencies: Updated base-provider.js to import log directly from utils.js Updated gemini-cli.js to import log directly from utils.js Result: Fixed 11 failing tests in mcp-provider.test.js * fix gemini test * fix(claude-code): recover from CLI JSON truncation bug (#913) (#920) Gracefully handle SyntaxError thrown by @anthropic-ai/claude-code when the CLI truncates large JSON outputs (4–16 kB cut-offs).\n\nKey points:\n• Detect JSON parse error + existing buffered text in both doGenerate() and doStream() code paths.\n• Convert the failure into a recoverable 'truncated' finish state and push a provider-warning.\n• Allows Task Master to continue parsing long PRDs / expand-task operations instead of crashing.\n\nA patch changeset (.changeset/claude-code-json-truncation.md) is included for the next release.\n\nRef: eyaltoledano/claude-task-master#913 * docs: fix gemini-cli authentication documentation (#923) Remove erroneous 'gemini auth login' command references and replace with correct 'gemini' command authentication flow. Update documentation to reflect proper OAuth setup process via the gemini CLI interactive interface. * fix tests * fix: update ai-sdk-provider-gemini-cli to 0.0.4 for improved authentication (#932) - Fixed authentication compatibility issues with Google auth - Added support for 'api-key' auth type alongside 'gemini-api-key' - Resolved "Unsupported authType: undefined" runtime errors - Updated @google/gemini-cli-core dependency to 0.1.9 - Improved documentation and removed invalid auth references - Maintained backward compatibility while enhancing type validation * call logging directly Need to patch upstream fastmcp to allow easier access and bootstrap the TM mcp logger to use the fastmcp logger which today is only exposed in the tools handler * fix tests * removing logs until we figure out how to pass mcp logger * format * fix tests * format * clean up * cleanup * readme fix --------- Co-authored-by: Oren Melamed <oren.m@gloat.com> Co-authored-by: Ralph Khreish <35776126+Crunchyman-ralph@users.noreply.github.com> Co-authored-by: Ben Vargas <ben@vargas.com>
This commit is contained in:
Oren Me
@@ -11,10 +11,11 @@ Welcome to the Task Master documentation. Use the links below to navigate to the
|
||||
|
||||
- [Command Reference](command-reference.md) - Complete list of all available commands (including research and multi-task viewing)
|
||||
- [Task Structure](task-structure.md) - Understanding the task format and features
|
||||
- [Available Models](models.md) - Complete list of supported AI models and providers
|
||||
|
||||
## Examples & Licensing
|
||||
|
||||
- [Example Interactions](examples.md) - Common Cursor AI interaction examples
|
||||
- [Example Interactions](examples.md) - Common Cursor AI interaction examples
|
||||
- [Licensing Information](licensing.md) - Detailed information about the license
|
||||
|
||||
## Need More Help?
|
||||
|
||||
@@ -4,7 +4,30 @@ Taskmaster uses two primary methods for configuration:
|
||||
|
||||
1. **`.taskmaster/config.json` File (Recommended - New Structure)**
|
||||
|
||||
- This JSON file stores most configuration settings, including AI model selections, parameters, logging levels, and project defaults.
|
||||
- This JSON file stores most configuration settings, including A5. **Usage Requirements**:
|
||||
8. **Troubleshooting**:
|
||||
- "MCP provider requires session context" → Ensure running in MCP environment
|
||||
- See the [MCP Provider Guide](./mcp-provider-guide.md) for detailed troubleshootingust be running in an MCP context (session must be available)
|
||||
- Session must provide `clientCapabilities.sampling` capability
|
||||
|
||||
6. **Best Practices**:
|
||||
- Always configure a non-MCP fallback provider
|
||||
- Use `mcp` for main/research roles when in MCP environments
|
||||
- Test sampling capability before production use
|
||||
|
||||
7. **Setup Commands**:
|
||||
```bash
|
||||
# Set MCP provider for main role
|
||||
task-master models set-main --provider mcp --model claude-3-5-sonnet-20241022
|
||||
|
||||
# Set MCP provider for research role
|
||||
task-master models set-research --provider mcp --model claude-3-opus-20240229
|
||||
|
||||
# Verify configuration
|
||||
task-master models list
|
||||
```
|
||||
|
||||
8. **Troubleshooting**:lections, parameters, logging levels, and project defaults.
|
||||
- **Location:** This file is created in the `.taskmaster/` directory when you run the `task-master models --setup` interactive setup or initialize a new project with `task-master init`.
|
||||
- **Migration:** Existing projects with `.taskmasterconfig` in the root will continue to work, but should be migrated to the new structure using `task-master migrate`.
|
||||
- **Management:** Use the `task-master models --setup` command (or `models` MCP tool) to interactively create and manage this file. You can also set specific models directly using `task-master models --set-<role>=<model_id>`, adding `--ollama` or `--openrouter` flags for custom models. Manual editing is possible but not recommended unless you understand the structure.
|
||||
@@ -173,6 +196,57 @@ node scripts/init.js
|
||||
|
||||
## Provider-Specific Configuration
|
||||
|
||||
### MCP (Model Context Protocol) Provider
|
||||
|
||||
The MCP provider enables Task Master to use MCP servers as AI providers. This is particularly useful when running Task Master within MCP-compatible development environments like Claude Desktop or Cursor.
|
||||
|
||||
1. **Prerequisites**:
|
||||
- An active MCP session with sampling capability
|
||||
- MCP client with sampling support (e.g. VS Code)
|
||||
- No API keys required (uses session-based authentication)
|
||||
|
||||
2. **Configuration**:
|
||||
```json
|
||||
{
|
||||
"models": {
|
||||
"main": {
|
||||
"provider": "mcp",
|
||||
"modelId": "mcp-sampling"
|
||||
},
|
||||
"research": {
|
||||
"provider": "mcp",
|
||||
"modelId": "mcp-sampling"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. **Available Model IDs**:
|
||||
- `mcp-sampling` - General text generation using MCP client sampling (supports all roles)
|
||||
- `claude-3-5-sonnet-20241022` - High-performance model for general tasks (supports all roles)
|
||||
- `claude-3-opus-20240229` - Enhanced reasoning model for complex tasks (supports all roles)
|
||||
|
||||
4. **Features**:
|
||||
- ✅ **Text Generation**: Standard AI text generation via MCP sampling
|
||||
- ✅ **Object Generation**: Full schema-driven structured output generation
|
||||
- ✅ **PRD Parsing**: Parse Product Requirements Documents into structured tasks
|
||||
- ✅ **Task Creation**: AI-powered task creation with validation
|
||||
- ✅ **Session Management**: Automatic session detection and context handling
|
||||
- ✅ **Error Recovery**: Robust error handling and fallback mechanisms
|
||||
|
||||
5. **Usage Requirements**:
|
||||
- Must be running in an MCP context (session must be available)
|
||||
- Session must provide `clientCapabilities.sampling` capability
|
||||
|
||||
5. **Best Practices**:
|
||||
- Always configure a non-MCP fallback provider
|
||||
- Use `mcp` for main/research roles when in MCP environments
|
||||
- Test sampling capability before production use
|
||||
|
||||
6. **Troubleshooting**:
|
||||
- "MCP provider requires session context" → Ensure running in MCP environment
|
||||
- See the [MCP Provider Guide](./mcp-provider-guide.md) for detailed troubleshooting
|
||||
|
||||
### Google Vertex AI Configuration
|
||||
|
||||
Google Vertex AI is Google Cloud's enterprise AI platform and requires specific configuration:
|
||||
|
||||
564
docs/mcp-provider-guide.md
Normal file
564
docs/mcp-provider-guide.md
Normal file
@@ -0,0 +1,564 @@
|
||||
# MCP Provider Integration Guide
|
||||
|
||||
## Overview
|
||||
|
||||
Task Master provides a **unified MCP provider** for AI operations:
|
||||
|
||||
**MCP Provider** (`mcp`) - Modern AI SDK-compatible provider with full structured object generation support
|
||||
|
||||
The MCP provider enables Task Master to act as an MCP client, using MCP servers as AI providers alongside traditional API-based providers. This integration follows the existing provider pattern and supports all standard AI operations including structured object generation for PRD parsing and task creation.
|
||||
|
||||
## MCP Provider Features
|
||||
|
||||
The **MCP Provider** (`mcp`) provides:
|
||||
|
||||
✅ **Full AI SDK Compatibility** - Complete LanguageModelV1 interface implementation
|
||||
✅ **Structured Object Generation** - Schema-driven outputs for PRD parsing and task creation
|
||||
✅ **Enhanced Error Handling** - Robust JSON extraction and validation
|
||||
✅ **Session Management** - Automatic session detection and context handling
|
||||
✅ **Schema Validation** - Type-safe object generation with Zod validation
|
||||
|
||||
### Quick Setup
|
||||
|
||||
```bash
|
||||
# Set MCP provider for main role
|
||||
task-master models set-main --provider mcp --model claude-3-5-sonnet-20241022
|
||||
```
|
||||
|
||||
For detailed information, see [MCP Provider Documentation](mcp-provider.md).
|
||||
|
||||
## What is MCP Provider?
|
||||
|
||||
The MCP provider allows Task Master to:
|
||||
- Connect to MCP servers/tools as AI providers
|
||||
- Use session-based authentication instead of API keys
|
||||
- Map AI operations to MCP tool calls
|
||||
- Integrate with existing role-based provider assignment
|
||||
- Maintain compatibility with fallback chains
|
||||
- Support structured object generation for schema-driven features
|
||||
|
||||
## Configuration
|
||||
|
||||
### MCP Provider Setup
|
||||
|
||||
Add MCP provider to your `.taskmaster/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"models": {
|
||||
"main": {
|
||||
"provider": "mcp",
|
||||
"modelId": "claude-3-5-sonnet-20241022",
|
||||
"maxTokens": 50000,
|
||||
"temperature": 0.2
|
||||
},
|
||||
"research": {
|
||||
"provider": "mcp",
|
||||
"modelId": "claude-3-5-sonnet-20241022",
|
||||
"maxTokens": 8700,
|
||||
"temperature": 0.1
|
||||
},
|
||||
"fallback": {
|
||||
"provider": "anthropic",
|
||||
"modelId": "claude-3-5-sonnet-20241022"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Available Models
|
||||
|
||||
**MCP Provider Models:**
|
||||
|
||||
- **`claude-3-5-sonnet-20241022`** - High-performance model for general tasks
|
||||
- **SWE Score**: 0.49
|
||||
- **Features**: Text + Object generation
|
||||
|
||||
- **`claude-3-opus-20240229`** - Enhanced reasoning model for complex tasks
|
||||
- **SWE Score**: 0.725
|
||||
- **Features**: Text + Object generation
|
||||
|
||||
- **`mcp-sampling`** - General text generation using MCP client sampling
|
||||
- **SWE Score**: null
|
||||
- **Roles**: Supports main, research, and fallback roles
|
||||
- **SWE Score**: 0.49
|
||||
- **Cost**: $0 (session-based)
|
||||
- **Max Tokens**: 200,000
|
||||
- **Supported Roles**: main, research, fallback
|
||||
- **Features**: Text + Object generation
|
||||
|
||||
- **`claude-3-opus-20240229`** - Enhanced reasoning model for complex tasks
|
||||
- **SWE Score**: 0.725
|
||||
- **Cost**: $0 (session-based)
|
||||
- **Max Tokens**: 200,000
|
||||
- **Supported Roles**: main, research, fallback
|
||||
- **Features**: Text + Object generation
|
||||
|
||||
**Basic MCP Provider Models:**
|
||||
|
||||
- **`mcp-sampling`** - General text generation using MCP client sampling
|
||||
- **`mcp-sampling`** - General text generation using MCP client sampling
|
||||
- **SWE Score**: null
|
||||
- **Roles**: Supports main, research, and fallback roles
|
||||
|
||||
### Model ID Format
|
||||
|
||||
MCP model IDs use a simple format:
|
||||
|
||||
- **`claude-3-5-sonnet-20241022`** - Uses Claude 3.5 Sonnet via MCP sampling
|
||||
- **`claude-3-opus-20240229`** - Uses Claude 3 Opus via MCP sampling
|
||||
- **`mcp-sampling`** - Uses MCP client's sampling capability for text generation
|
||||
|
||||
## Session Requirements
|
||||
|
||||
The MCP provider requires an active MCP session with sampling capabilities:
|
||||
|
||||
```javascript
|
||||
session: {
|
||||
clientCapabilities: {
|
||||
sampling: {} // Client supports sampling requests
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Text Generation
|
||||
|
||||
```javascript
|
||||
import { generateTextService } from './scripts/modules/ai-services-unified.js';
|
||||
|
||||
const result = await generateTextService({
|
||||
role: 'main',
|
||||
session: mcpSession, // Required for MCP provider
|
||||
prompt: 'Explain MCP integration',
|
||||
systemPrompt: 'You are a helpful AI assistant'
|
||||
});
|
||||
|
||||
console.log(result.text);
|
||||
```
|
||||
|
||||
### Structured Object Generation
|
||||
|
||||
```javascript
|
||||
import { generateObjectService } from './scripts/modules/ai-services-unified.js';
|
||||
|
||||
const result = await generateObjectService({
|
||||
role: 'main',
|
||||
session: mcpSession,
|
||||
prompt: 'Create a task breakdown',
|
||||
schema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
tasks: {
|
||||
type: 'array',
|
||||
items: { type: 'string' }
|
||||
}
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
console.log(result.object);
|
||||
```
|
||||
|
||||
### Research Operations
|
||||
|
||||
```javascript
|
||||
const research = await generateTextService({
|
||||
role: 'research',
|
||||
session: mcpSession,
|
||||
prompt: 'Research the latest developments in AI',
|
||||
systemPrompt: 'You are a research assistant'
|
||||
});
|
||||
```
|
||||
|
||||
## CLI Integration
|
||||
|
||||
The MCP provider works seamlessly with Task Master CLI commands when running in an MCP context:
|
||||
|
||||
```bash
|
||||
# Generate tasks using MCP provider (if configured as main)
|
||||
task-master add-task "Implement user authentication"
|
||||
|
||||
# Research using MCP provider (if configured as research)
|
||||
task-master research "OAuth 2.0 best practices"
|
||||
|
||||
# Parse PRD using MCP provider
|
||||
task-master parse-prd requirements.txt
|
||||
```
|
||||
|
||||
## Architecture Details
|
||||
|
||||
### Provider Architecture
|
||||
**MCPProvider** (`mcp-server/src/providers/mcp-provider.js`)
|
||||
- Modern AI SDK-compliant provider for Task Master's MCP server
|
||||
- Auto-registers when MCP sessions connect to Task Master
|
||||
- Enables Task Master to use MCP sessions for AI operations
|
||||
- Supports both text generation and structured object generation
|
||||
|
||||
### Auto-Registration Process
|
||||
|
||||
When running as an MCP server, Task Master automatically:
|
||||
|
||||
```javascript
|
||||
// On MCP session connect
|
||||
server.on("connect", (event) => {
|
||||
// Check session capabilities
|
||||
if (session.clientCapabilities?.sampling) {
|
||||
// Create and register MCP provider
|
||||
const mcpProvider = new MCPProvider();
|
||||
mcpProvider.setSession(session);
|
||||
|
||||
// Auto-register with provider registry
|
||||
providerRegistry.registerProvider('mcp', mcpProvider);
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
This enables seamless self-referential AI operations within MCP contexts.
|
||||
|
||||
### Provider Pattern Integration
|
||||
|
||||
The MCP provider follows the same pattern as other providers:
|
||||
|
||||
```javascript
|
||||
class MCPProvider extends BaseAIProvider {
|
||||
// Implements generateText, generateObject
|
||||
// Uses session context instead of API keys
|
||||
// Maps operations to MCP sampling requests
|
||||
}
|
||||
```
|
||||
|
||||
### Session Detection
|
||||
|
||||
The provider automatically detects MCP sampling capability when sessions connect:
|
||||
|
||||
```javascript
|
||||
// On MCP session connect
|
||||
if (session.clientCapabilities?.sampling) {
|
||||
// Auto-register MCP provider for use
|
||||
const mcpProvider = new MCPProvider();
|
||||
mcpProvider.setSession(session);
|
||||
}
|
||||
```
|
||||
|
||||
### Sampling Integration
|
||||
|
||||
AI operations use MCP sampling with different levels of support:
|
||||
|
||||
- `generateText()` → MCP `requestSampling()` with messages (2-minute timeout) ✅ **Full Support**
|
||||
- `streamText()` → **Limited/No Support** ⚠️ See streaming limitations below
|
||||
- `generateObject()` → MCP `requestSampling()` with JSON schema instructions (2-minute timeout) ✅ **Full Support**
|
||||
|
||||
**Timeout Configuration**: All MCP sampling requests use a 2-minute (120,000ms) timeout to accommodate complex AI operations.
|
||||
|
||||
#### Streaming Text Limitations ⚠️
|
||||
|
||||
**Important**: The MCP provider has **no support** for text streaming:
|
||||
|
||||
**MCPProvider**:
|
||||
- **❌ No Streaming Support**: Throws error "MCP Provider does not support streaming text, use generateText instead"
|
||||
- **Solution**: Always use `generateText()` instead of `streamText()` with this provider
|
||||
|
||||
**Recommendation**: For streaming functionality, configure a non-MCP fallback provider (like Anthropic or OpenAI) in your fallback role.
|
||||
|
||||
### Error Handling
|
||||
|
||||
The MCP provider includes comprehensive error handling:
|
||||
|
||||
- Session validation errors (checks for `clientCapabilities.sampling`)
|
||||
- MCP sampling request failures
|
||||
- JSON parsing errors (for structured output)
|
||||
- Automatic fallback to other providers
|
||||
|
||||
### Best Practices
|
||||
|
||||
### 1. Configure Fallbacks
|
||||
|
||||
Always configure a non-MCP fallback provider, especially for streaming operations:
|
||||
|
||||
```json
|
||||
{
|
||||
"models": {
|
||||
"main": {
|
||||
"provider": "mcp",
|
||||
"modelId": "mcp-sampling"
|
||||
},
|
||||
"fallback": {
|
||||
"provider": "anthropic",
|
||||
"modelId": "claude-3-5-sonnet-20241022"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Avoid Streaming with MCP
|
||||
|
||||
**Do not use `streamTextService()` with MCP provider**. Use `generateTextService()` instead:
|
||||
|
||||
```javascript
|
||||
// ❌ Don't do this with MCP provider
|
||||
const result = await streamTextService({
|
||||
role: 'main', // MCP provider
|
||||
session: mcpSession,
|
||||
prompt: 'Generate content'
|
||||
});
|
||||
|
||||
// ✅ Do this instead
|
||||
const result = await generateTextService({
|
||||
role: 'main', // MCP provider
|
||||
session: mcpSession,
|
||||
prompt: 'Generate content'
|
||||
});
|
||||
```
|
||||
|
||||
### 3. Session Management
|
||||
|
||||
Ensure your MCP session remains active throughout Task Master operations:
|
||||
|
||||
```javascript
|
||||
// Check session health before operations
|
||||
if (!session || !session.capabilities) {
|
||||
throw new Error('MCP session not available');
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Tool Availability
|
||||
|
||||
Verify required capabilities are available in your MCP session:
|
||||
|
||||
```javascript
|
||||
// Check session health and capabilities
|
||||
if (session && session.clientCapabilities && session.clientCapabilities.sampling) {
|
||||
console.log('MCP sampling available');
|
||||
} else {
|
||||
console.log('MCP sampling not available');
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Error Recovery
|
||||
|
||||
Handle MCP-specific errors gracefully:
|
||||
|
||||
```javascript
|
||||
try {
|
||||
const result = await generateTextService({
|
||||
role: 'main',
|
||||
session: mcpSession,
|
||||
prompt: 'Generate content'
|
||||
});
|
||||
} catch (error) {
|
||||
if (error.message.includes('MCP')) {
|
||||
// Handle MCP-specific error
|
||||
console.log('MCP error, falling back to alternate provider');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **"MCP provider requires session context"**
|
||||
- Ensure `session` parameter is passed to service calls
|
||||
- Verify session has proper structure
|
||||
- Check that you're running in an MCP environment
|
||||
|
||||
2. **"MCP session must have client sampling capabilities"**
|
||||
- Check that `session.clientCapabilities.sampling` exists
|
||||
- Verify session has `requestSampling()` method
|
||||
- Ensure MCP client supports sampling feature
|
||||
|
||||
3. **"MCP Provider does not support streaming text, use generateText instead"**
|
||||
- **Common Error**: Occurs when calling `streamTextService()` with MCP provider
|
||||
- **Solution**: Use `generateTextService()` instead of `streamTextService()`
|
||||
- **Alternative**: Configure a non-MCP fallback provider for streaming operations
|
||||
|
||||
4. **"MCP sampling failed"** or **Timeout errors**
|
||||
- Check MCP client is responding to sampling requests
|
||||
- Verify session is still active and connected
|
||||
- Consider if request complexity requires longer processing time
|
||||
- Check for network connectivity issues
|
||||
|
||||
5. **"Model ID is required for MCP Remote Provider"**
|
||||
- Ensure `modelId` is specified in configuration
|
||||
- Use `mcp-sampling` as the standard model ID
|
||||
- Verify provider configuration is properly loaded
|
||||
|
||||
6. **Auto-registration failures**
|
||||
- Check that MCP session has required sampling capabilities
|
||||
- Verify server event listeners are properly configured
|
||||
- Look for provider registry initialization issues
|
||||
|
||||
### Streaming-Related Issues
|
||||
|
||||
**Error**: `streamTextService()` calls fail with MCP provider
|
||||
**Cause**: MCP provider has no streaming support
|
||||
**Solutions**:
|
||||
- Use `generateTextService()` for all MCP-based text generation
|
||||
- Configure non-MCP fallback providers for streaming requirements
|
||||
- Check your provider configuration to ensure fallback chain includes streaming-capable providers
|
||||
|
||||
### Debug Mode
|
||||
|
||||
Enable debug logging to see MCP provider operations:
|
||||
|
||||
```javascript
|
||||
// Set debug flag in config or environment
|
||||
process.env.DEBUG = 'true';
|
||||
|
||||
// Or in .taskmasterconfig
|
||||
{
|
||||
"debug": true,
|
||||
"models": { /* ... */ }
|
||||
}
|
||||
```
|
||||
|
||||
### Testing MCP Integration
|
||||
|
||||
Test MCP provider functionality:
|
||||
|
||||
```javascript
|
||||
// Check if MCP provider is properly registered
|
||||
import { MCPProvider } from './mcp-server/src/providers/mcp-provider.js';
|
||||
|
||||
// Test session capabilities
|
||||
if (session && session.clientCapabilities && session.clientCapabilities.sampling) {
|
||||
console.log('MCP sampling available');
|
||||
|
||||
// Test provider creation
|
||||
const provider = new MCPProvider();
|
||||
provider.setSession(session);
|
||||
console.log('MCP provider created successfully');
|
||||
} else {
|
||||
console.log('MCP session lacks required capabilities');
|
||||
}
|
||||
```
|
||||
|
||||
## Integration with Development Tools
|
||||
|
||||
### VS Code with MCP Extension
|
||||
|
||||
When using Task Master in VS Code with MCP support:
|
||||
|
||||
1. Configure Task Master MCP server in your `.vscode/mcp.json`
|
||||
2. Set MCP provider as main/research in `.taskmaster/config.json`
|
||||
3. Benefit from integrated AI assistance within your development workflow
|
||||
4. Use Task Master tools directly from VS Code's MCP interface
|
||||
|
||||
**Example VS Code MCP Configuration:**
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"task-master-dev": {
|
||||
"command": "node",
|
||||
"args": ["mcp-server/server.js"],
|
||||
"cwd": "/path/to/your/task-master-project",
|
||||
"env": {
|
||||
"NODE_ENV": "development",
|
||||
"ANTHROPIC_API_KEY": "${env:ANTHROPIC_API_KEY}",
|
||||
"TASK_MASTER_PROJECT_ROOT": "/path/to/your/project"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Claude Desktop
|
||||
|
||||
When using Task Master through Claude Desktop's MCP integration:
|
||||
|
||||
1. Configure Task Master as MCP provider in Claude Desktop
|
||||
2. Use MCP provider for AI operations within Task Master
|
||||
3. Benefit from nested MCP tool calling capabilities
|
||||
|
||||
### Cursor and Other MCP Clients
|
||||
|
||||
The MCP provider works with any MCP-compatible development environment:
|
||||
|
||||
1. Ensure your IDE has MCP client capabilities
|
||||
2. Configure Task Master MCP server endpoint
|
||||
3. Use MCP provider for enhanced AI-driven development
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
### Custom Tool Mapping
|
||||
|
||||
Advanced users can use MCP sampling for all roles:
|
||||
|
||||
```javascript
|
||||
// MCP sampling for all roles
|
||||
{
|
||||
"models": {
|
||||
"main": {
|
||||
"provider": "mcp",
|
||||
"modelId": "mcp-sampling"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Role-Specific Configuration
|
||||
|
||||
Configure MCP sampling for different roles:
|
||||
|
||||
```json
|
||||
{
|
||||
"models": {
|
||||
"main": {
|
||||
"provider": "mcp",
|
||||
"modelId": "mcp-sampling"
|
||||
},
|
||||
"research": {
|
||||
"provider": "mcp",
|
||||
"modelId": "mcp-sampling"
|
||||
},
|
||||
"fallback": {
|
||||
"provider": "mcp",
|
||||
"modelId": "backup-server:simple-generation"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### API Reference
|
||||
|
||||
### MCPProvider Methods
|
||||
|
||||
- `generateText(params)` - Generate text using MCP sampling ✅ **Supported**
|
||||
- `streamText(params)` - Stream text ❌ **Not supported** (throws error)
|
||||
- `generateObject(params)` - Generate structured objects ✅ **Supported**
|
||||
- `setSession(session)` - Update provider session
|
||||
- `validateAuth(params)` - Validate session capabilities
|
||||
- `getClient()` - Returns null (not applicable for MCP)
|
||||
|
||||
### Required Parameters
|
||||
|
||||
All MCP operations require:
|
||||
- `session` - Active MCP session object (auto-provided when registered)
|
||||
- `modelId` - MCP model identifier (typically "mcp-sampling")
|
||||
- `messages` - Array of message objects
|
||||
|
||||
### Optional Parameters
|
||||
|
||||
- `temperature` - Creativity control (if supported by MCP client)
|
||||
- `maxTokens` - Maximum response length (if supported)
|
||||
- `schema` - JSON schema for structured output (generateObject only)
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Session Security**: MCP sessions should be properly authenticated
|
||||
2. **Server Validation**: Only connect to trusted MCP servers
|
||||
3. **Data Privacy**: Ensure MCP clients handle data according to your privacy requirements
|
||||
4. **Error Exposure**: Be careful not to expose sensitive session information in error messages
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
Planned improvements for MCP provider:
|
||||
|
||||
1. **Native Streaming Support** - True streaming for compatible MCP clients (requires MCP protocol updates)
|
||||
2. **Enhanced Session Monitoring** - Automatic session validation and recovery
|
||||
3. **Performance Optimization** - Caching and connection pooling
|
||||
4. **Advanced Error Recovery** - Intelligent retry and fallback strategies
|
||||
|
||||
**Note**: True streaming support depends on future MCP protocol enhancements. Current implementation provides text generation without streaming capabilities.
|
||||
350
docs/mcp-provider.md
Normal file
350
docs/mcp-provider.md
Normal file
@@ -0,0 +1,350 @@
|
||||
# MCP Provider Implementation
|
||||
|
||||
## Overview
|
||||
|
||||
The MCP Provider creates a modern AI SDK-compliant custom provider that integrates with the existing Task Master MCP server infrastructure. This provider enables AI operations through MCP session sampling while following modern AI SDK patterns and **includes full support for structured object generation (generateObject)** for schema-driven features like PRD parsing and task creation.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Components
|
||||
|
||||
1. **MCPProvider** (`mcp-server/src/providers/mcp-provider.js`)
|
||||
- Main provider class following Claude Code pattern
|
||||
- Session-based provider (no API key required)
|
||||
- Registers with provider registry on MCP server connect
|
||||
|
||||
2. **AI SDK Implementation** (`mcp-server/src/custom-sdk/`)
|
||||
- `index.js` - Provider factory function
|
||||
- `language-model.js` - LanguageModelV1 implementation with **doGenerateObject support**
|
||||
- `message-converter.js` - Format conversion utilities
|
||||
- `json-extractor.js` - **NEW**: Robust JSON extraction from AI responses
|
||||
- `schema-converter.js` - **NEW**: Schema-to-instructions conversion utility
|
||||
- `errors.js` - Error handling and mapping
|
||||
|
||||
3. **Integration Points**
|
||||
- MCP Server registration (`mcp-server/src/index.js`)
|
||||
- AI Services integration (`scripts/modules/ai-services-unified.js`)
|
||||
- Model configuration (`scripts/modules/supported-models.json`)
|
||||
|
||||
### Session Flow
|
||||
|
||||
```
|
||||
MCP Client Connect → MCP Server → registerRemoteProvider()
|
||||
↓
|
||||
MCPRemoteProvider (existing)
|
||||
MCPProvider
|
||||
↓
|
||||
Provider Registry
|
||||
↓
|
||||
AI Services Layer
|
||||
↓
|
||||
Text Generation + Object Generation
|
||||
```
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Provider Registration
|
||||
|
||||
The MCP server registers **both** providers when a client connects:
|
||||
|
||||
```javascript
|
||||
// mcp-server/src/index.js
|
||||
registerRemoteProvider(session) {
|
||||
if (session?.clientCapabilities?.sampling) {
|
||||
// Register existing provider
|
||||
// Register unified MCP provider
|
||||
const mcpProvider = new MCPProvider();
|
||||
mcpProvider.setSession(session);
|
||||
|
||||
const providerRegistry = ProviderRegistry.getInstance();
|
||||
providerRegistry.registerProvider('mcp', mcpProvider);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### AI Services Integration
|
||||
|
||||
The AI services layer includes the new provider:
|
||||
|
||||
```javascript
|
||||
// scripts/modules/ai-services-unified.js
|
||||
const PROVIDERS = {
|
||||
// ... other providers
|
||||
'mcp': () => {
|
||||
const providerRegistry = ProviderRegistry.getInstance();
|
||||
return providerRegistry.getProvider('mcp');
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### Message Conversion
|
||||
|
||||
The provider converts between AI SDK and MCP formats:
|
||||
|
||||
```javascript
|
||||
// AI SDK prompt → MCP sampling format
|
||||
const { messages, systemPrompt } = convertToMCPFormat(options.prompt);
|
||||
|
||||
// MCP response → AI SDK format
|
||||
const result = convertFromMCPFormat(response);
|
||||
```
|
||||
|
||||
## Structured Object Generation (generateObject)
|
||||
|
||||
### Overview
|
||||
|
||||
The MCP Provider includes full support for structured object generation, enabling schema-driven features like PRD parsing, task creation, and any operations requiring validated JSON outputs.
|
||||
|
||||
### Architecture
|
||||
|
||||
The generateObject implementation includes:
|
||||
|
||||
1. **Schema-to-Instructions Conversion** (`schema-converter.js`)
|
||||
- Converts Zod schemas to natural language instructions
|
||||
- Generates example outputs to guide AI responses
|
||||
- Handles complex nested schemas and validation requirements
|
||||
|
||||
2. **JSON Extraction Pipeline** (`json-extractor.js`)
|
||||
- Multiple extraction strategies for robust JSON parsing
|
||||
- Handles code blocks, malformed JSON, and various response formats
|
||||
- Fallback mechanisms for maximum reliability
|
||||
|
||||
3. **Validation System**
|
||||
- Complete schema validation using Zod
|
||||
- Detailed error reporting for failed validations
|
||||
- Type-safe object generation
|
||||
|
||||
### Implementation Details
|
||||
|
||||
#### doGenerateObject Method
|
||||
|
||||
The `MCPLanguageModel` class implements the AI SDK's `doGenerateObject` method:
|
||||
|
||||
```javascript
|
||||
async doGenerateObject({ schema, objectName, prompt, ...options }) {
|
||||
// Convert schema to instructions
|
||||
const instructions = convertSchemaToInstructions(schema, objectName);
|
||||
|
||||
// Enhance prompt with structured output requirements
|
||||
const enhancedPrompt = enhancePromptForObjectGeneration(prompt, instructions);
|
||||
|
||||
// Generate response via MCP sampling
|
||||
const response = await this.doGenerate({ prompt: enhancedPrompt, ...options });
|
||||
|
||||
// Extract and validate JSON
|
||||
const extractedJson = extractJsonFromResponse(response.text);
|
||||
const validatedObject = schema.parse(extractedJson);
|
||||
|
||||
return {
|
||||
object: validatedObject,
|
||||
usage: response.usage,
|
||||
finishReason: response.finishReason
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
#### AI SDK Compatibility
|
||||
|
||||
The provider includes required properties for AI SDK object generation:
|
||||
|
||||
```javascript
|
||||
class MCPLanguageModel {
|
||||
get defaultObjectGenerationMode() {
|
||||
return 'tool';
|
||||
}
|
||||
|
||||
get supportsStructuredOutputs() {
|
||||
return true;
|
||||
}
|
||||
|
||||
// ... doGenerateObject implementation
|
||||
}
|
||||
```
|
||||
|
||||
### Usage Examples
|
||||
|
||||
#### PRD Parsing
|
||||
|
||||
```javascript
|
||||
import { z } from 'zod';
|
||||
|
||||
const taskSchema = z.object({
|
||||
title: z.string(),
|
||||
description: z.string(),
|
||||
priority: z.enum(['high', 'medium', 'low']),
|
||||
dependencies: z.array(z.number()).optional()
|
||||
});
|
||||
|
||||
const result = await generateObject({
|
||||
model: mcpModel,
|
||||
schema: taskSchema,
|
||||
prompt: 'Parse this PRD section into a task: [PRD content]'
|
||||
});
|
||||
|
||||
console.log(result.object); // Validated task object
|
||||
```
|
||||
|
||||
#### Task Creation
|
||||
|
||||
```javascript
|
||||
const taskCreationSchema = z.object({
|
||||
task: z.object({
|
||||
title: z.string(),
|
||||
description: z.string(),
|
||||
details: z.string(),
|
||||
testStrategy: z.string(),
|
||||
priority: z.enum(['high', 'medium', 'low']),
|
||||
dependencies: z.array(z.number()).optional()
|
||||
})
|
||||
});
|
||||
|
||||
const result = await generateObject({
|
||||
model: mcpModel,
|
||||
schema: taskCreationSchema,
|
||||
prompt: 'Create a comprehensive task for implementing user authentication'
|
||||
});
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
The implementation provides comprehensive error handling:
|
||||
|
||||
- **Schema Validation Errors**: Detailed Zod validation messages
|
||||
- **JSON Extraction Failures**: Fallback strategies and clear error reporting
|
||||
- **MCP Communication Errors**: Proper error mapping and recovery
|
||||
- **Timeout Handling**: Configurable timeouts for long-running operations
|
||||
|
||||
### Testing
|
||||
|
||||
The generateObject functionality is fully tested:
|
||||
|
||||
```bash
|
||||
# Test object generation
|
||||
npm test -- --grep "generateObject"
|
||||
|
||||
# Test with actual MCP session
|
||||
node test-object-generation.js
|
||||
```
|
||||
|
||||
### Supported Features
|
||||
|
||||
✅ **Schema Conversion**: Zod schemas → Natural language instructions
|
||||
✅ **JSON Extraction**: Multiple strategies for robust parsing
|
||||
✅ **Validation**: Complete schema validation with error reporting
|
||||
✅ **Error Recovery**: Fallback mechanisms for failed extractions
|
||||
✅ **Type Safety**: Full TypeScript support with inferred types
|
||||
✅ **AI SDK Compliance**: Complete LanguageModelV1 interface implementation
|
||||
|
||||
## Usage
|
||||
|
||||
### Configuration
|
||||
|
||||
Add to supported models configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcp": [
|
||||
{
|
||||
"id": "claude-3-5-sonnet-20241022",
|
||||
"swe_score": 0.623,
|
||||
"cost_per_1m_tokens": { "input": 0, "output": 0 },
|
||||
"allowed_roles": ["main", "fallback", "research"],
|
||||
"max_tokens": 200000
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### CLI Usage
|
||||
|
||||
```bash
|
||||
# Set provider for main role
|
||||
tm models set-main --provider mcp --model claude-3-5-sonnet-20241022
|
||||
|
||||
# Use in task operations
|
||||
tm add-task "Create user authentication system"
|
||||
```
|
||||
|
||||
### Programmatic Usage
|
||||
|
||||
```javascript
|
||||
const provider = registry.getProvider('mcp');
|
||||
if (provider && provider.hasValidSession()) {
|
||||
const client = provider.getClient({ temperature: 0.7 });
|
||||
const model = client({ modelId: 'claude-3-5-sonnet-20241022' });
|
||||
|
||||
const result = await model.doGenerate({
|
||||
prompt: [
|
||||
{ role: 'user', content: 'Hello!' }
|
||||
]
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### Component Tests
|
||||
|
||||
```bash
|
||||
# Test individual components
|
||||
node test-mcp-components.js
|
||||
```
|
||||
|
||||
### Integration Testing
|
||||
|
||||
1. Start MCP server
|
||||
2. Connect Claude client
|
||||
3. Verify both providers are registered
|
||||
4. Test AI operations through mcp provider
|
||||
|
||||
### Validation Checklist
|
||||
|
||||
- ✅ Provider creation and initialization
|
||||
- ✅ Registry integration
|
||||
- ✅ Session management
|
||||
- ✅ Message conversion
|
||||
- ✅ Error handling
|
||||
- ✅ AI Services integration
|
||||
- ✅ Model configuration
|
||||
|
||||
## Key Benefits
|
||||
|
||||
1. **AI SDK Compliance** - Full LanguageModelV1 implementation
|
||||
2. **Session Integration** - Leverages existing MCP session infrastructure
|
||||
3. **Registry Pattern** - Uses provider registry for discovery
|
||||
4. **Backward Compatibility** - Coexists with existing MCPRemoteProvider
|
||||
5. **Future Ready** - Supports AI SDK features and patterns
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Provider Not Found
|
||||
|
||||
```
|
||||
Error: Provider "mcp" not found in registry
|
||||
```
|
||||
|
||||
**Solution**: Ensure MCP server is running and client is connected
|
||||
|
||||
### Session Errors
|
||||
|
||||
```
|
||||
Error: MCP Provider requires active MCP session
|
||||
```
|
||||
|
||||
**Solution**: Check MCP client connection and session capabilities
|
||||
|
||||
### Sampling Errors
|
||||
|
||||
```
|
||||
Error: MCP session must have client sampling capabilities
|
||||
```
|
||||
|
||||
**Solution**: Verify MCP client supports sampling operations
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Performance Optimization** - Add caching and connection pooling
|
||||
2. **Enhanced Streaming** - Implement native streaming if MCP supports it
|
||||
3. **Tool Integration** - Add support for function calling through MCP tools
|
||||
4. **Monitoring** - Add metrics and logging for provider usage
|
||||
5. **Documentation** - Update user guides and API documentation
|
||||
@@ -40,6 +40,7 @@
|
||||
| perplexity | sonar-reasoning | 0.211 | 1 | 5 |
|
||||
| xai | grok-3 | — | 3 | 15 |
|
||||
| xai | grok-3-fast | — | 5 | 25 |
|
||||
| mcp | mcp-sampling | - | 0 | 0 |
|
||||
| ollama | devstral:latest | — | 0 | 0 |
|
||||
| ollama | qwen3:latest | — | 0 | 0 |
|
||||
| ollama | qwen3:14b | — | 0 | 0 |
|
||||
@@ -69,7 +70,6 @@
|
||||
| openrouter | qwen/qwen3-235b-a22b | — | 0.14 | 2 |
|
||||
| openrouter | mistralai/mistral-small-3.1-24b-instruct:free | — | 0 | 0 |
|
||||
| openrouter | mistralai/mistral-small-3.1-24b-instruct | — | 0.1 | 0.3 |
|
||||
| openrouter | mistralai/devstral-small | — | 0.1 | 0.3 |
|
||||
| openrouter | mistralai/mistral-nemo | — | 0.03 | 0.07 |
|
||||
| openrouter | thudm/glm-4-32b:free | — | 0 | 0 |
|
||||
| groq | llama-3.3-70b-versatile | 0.55 | 0.59 | 0.79 |
|
||||
@@ -113,6 +113,7 @@
|
||||
| groq | deepseek-r1-distill-llama-70b | 0.52 | 0.75 | 0.99 |
|
||||
| claude-code | opus | 0.725 | 0 | 0 |
|
||||
| claude-code | sonnet | 0.727 | 0 | 0 |
|
||||
| mcp | mcp-sampling | - | 0 | 0 |
|
||||
| gemini-cli | gemini-2.5-pro | 0.72 | 0 | 0 |
|
||||
| gemini-cli | gemini-2.5-flash | 0.71 | 0 | 0 |
|
||||
|
||||
@@ -147,6 +148,7 @@
|
||||
| perplexity | sonar-reasoning | 0.211 | 1 | 5 |
|
||||
| xai | grok-3 | — | 3 | 15 |
|
||||
| xai | grok-3-fast | — | 5 | 25 |
|
||||
| mcp | mcp-sampling | - | 0 | 0 |
|
||||
| ollama | devstral:latest | — | 0 | 0 |
|
||||
| ollama | qwen3:latest | — | 0 | 0 |
|
||||
| ollama | qwen3:14b | — | 0 | 0 |
|
||||
|
||||
Reference in New Issue
Block a user