docs/mcp-provider.md
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.
MCPProvider (mcp-server/src/providers/mcp-provider.js)
AI SDK Implementation (mcp-server/src/custom-sdk/)
index.js - Provider factory functionlanguage-model.js - LanguageModelV1 implementation with doGenerateObject supportmessage-converter.js - Format conversion utilitiesjson-extractor.js - NEW: Robust JSON extraction from AI responsesschema-converter.js - NEW: Schema-to-instructions conversion utilityerrors.js - Error handling and mappingIntegration Points
mcp-server/src/index.js)scripts/modules/ai-services-unified.js)scripts/modules/supported-models.json)MCP Client Connect → MCP Server → registerRemoteProvider()
↓
MCPRemoteProvider (existing)
MCPProvider
↓
Provider Registry
↓
AI Services Layer
↓
Text Generation + Object Generation
The MCP server registers both providers when a client connects:
// 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);
}
}
The AI services layer includes the new provider:
// scripts/modules/ai-services-unified.js
const PROVIDERS = {
// ... other providers
'mcp': () => {
const providerRegistry = ProviderRegistry.getInstance();
return providerRegistry.getProvider('mcp');
}
};
The provider converts between AI SDK and MCP formats:
// AI SDK prompt → MCP sampling format
const { messages, systemPrompt } = convertToMCPFormat(options.prompt);
// MCP response → AI SDK format
const result = convertFromMCPFormat(response);
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.
The generateObject implementation includes:
Schema-to-Instructions Conversion (schema-converter.js)
JSON Extraction Pipeline (json-extractor.js)
Validation System
The MCPLanguageModel class implements the AI SDK's doGenerateObject method:
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
};
}
The provider includes required properties for AI SDK object generation:
class MCPLanguageModel {
get defaultObjectGenerationMode() {
return 'tool';
}
get supportsStructuredOutputs() {
return true;
}
// ... doGenerateObject implementation
}
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
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'
});
The implementation provides comprehensive error handling:
The generateObject functionality is fully tested:
# Test object generation
npm test -- --grep "generateObject"
# Test with actual MCP session
node test-object-generation.js
✅ 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
Add to supported models configuration:
{
"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
}
]
}
# 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"
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!' }
]
});
}
# Test individual components
node test-mcp-components.js
Error: Provider "mcp" not found in registry
Solution: Ensure MCP server is running and client is connected
Error: MCP Provider requires active MCP session
Solution: Check MCP client connection and session capabilities
Error: MCP session must have client sampling capabilities
Solution: Verify MCP client supports sampling operations