mcp-context-engineering
Version:
The intelligent context optimization system for AI coding assistants. Built with Cole's PRP methodology, Context Portal knowledge graphs, and production-ready MongoDB architecture.
569 lines (567 loc) • 26.7 kB
JavaScript
import { z } from 'zod';
// Cole's verified PRP template structure
export const PRPTemplateSchema = z.object({
// Header: Clear goal definition
header: z.object({
goal: z.string(),
business_value: z.string(),
success_criteria: z.array(z.string()),
estimated_complexity: z.enum(['low', 'medium', 'high'])
}),
// Research: Comprehensive analysis (Cole's methodology)
research_section: z.object({
codebase_analysis: z.array(z.string()),
external_research: z.array(z.string()),
existing_patterns: z.array(z.string()),
potential_challenges: z.array(z.string()),
best_practices: z.array(z.string()),
confidence_score: z.number().min(1).max(10)
}),
// Implementation: Step-by-step blueprint
implementation_section: z.object({
technical_requirements: z.array(z.string()),
pseudocode: z.string(),
task_breakdown: z.array(z.object({
task: z.string(),
order: z.number(),
dependencies: z.array(z.string()),
validation: z.string(),
estimated_effort: z.string()
})),
integration_points: z.array(z.string()),
error_handling_strategy: z.string()
}),
// Validation: Quality assurance framework
validation_section: z.object({
syntax_checks: z.array(z.string()),
unit_test_commands: z.array(z.string()),
integration_tests: z.array(z.string()),
quality_checklist: z.array(z.string()),
acceptance_criteria: z.array(z.string())
}),
// Context Portal integration: Knowledge graph connections
knowledge_connections: z.object({
related_decisions: z.array(z.string()),
dependent_patterns: z.array(z.string()),
potential_conflicts: z.array(z.string()),
architecture_impact: z.string()
}),
// Agent-specific optimizations
agent_guidance: z.object({
cursor_specific: z.string(),
windsurf_specific: z.string(),
claude_code_specific: z.string(),
universal_notes: z.string()
})
});
export const PRPGenerationRequestSchema = z.object({
feature_description: z.string(),
project_context: z.object({
project_id: z.string(),
current_patterns: z.array(z.string()).optional(),
tech_stack: z.array(z.string()),
complexity_preference: z.enum(['low', 'medium', 'high']).default('medium')
}),
agent_type: z.enum(['cursor', 'windsurf', 'claude_code', 'generic']).default('generic'),
research_depth: z.enum(['basic', 'comprehensive', 'exhaustive']).default('comprehensive'),
include_learning: z.boolean().default(true)
});
/**
* PRP Generator - Core engine combining Cole's methodology with Context Portal knowledge graphs
*
* Perfect harmony: MongoDB (memory) → MCP (interface) → AI Agent (execution)
*
* This creates intelligent, memory-backed planning templates that:
* 1. Remember what worked before (MongoDB effectiveness tracking)
* 2. Adapt to different AI agents (Universal optimization)
* 3. Integrate knowledge graphs (Context Portal patterns)
* 4. Follow Cole's proven methodology (PRP structure)
*/
export class PRPGenerator {
researchEngine;
mongoOperations;
embeddingService;
constructor(researchEngine, mongoOperations, // Will be MongoDB operations interface
embeddingService // Will be Voyage AI embedding service
) {
this.researchEngine = researchEngine;
this.mongoOperations = mongoOperations;
this.embeddingService = embeddingService;
}
/**
* Generate complete PRP following Cole's template with Context Portal integration
*
* This is the core method that creates perfect planning templates by:
* 1. Using Cole's research methodology
* 2. Leveraging stored knowledge patterns
* 3. Optimizing for specific AI agents
* 4. Learning from past effectiveness
*/
async generatePRP(request) {
const validatedRequest = PRPGenerationRequestSchema.parse(request);
// Step 1: Conduct Cole's systematic research
console.log('🔍 Conducting systematic research using Cole\'s methodology...');
const researchRequest = {
feature_description: validatedRequest.feature_description,
project_context: {
type: 'software project',
tech_stack: validatedRequest.project_context.tech_stack,
existing_patterns: validatedRequest.project_context.current_patterns
},
research_depth: validatedRequest.research_depth
};
const research = await this.researchEngine.conductResearch(researchRequest);
// Step 2: Query MongoDB for similar successful patterns
console.log('🧠 Retrieving similar successful patterns from memory...');
const similarPatterns = await this.findSimilarPatterns(validatedRequest);
// Step 3: Apply learned optimizations for target agent
console.log('🎯 Applying agent-specific optimizations...');
const agentOptimizations = await this.getAgentOptimizations(validatedRequest.agent_type, similarPatterns);
// Step 4: Generate Context Portal knowledge graph connections
console.log('🕸️ Building knowledge graph connections...');
const knowledgeConnections = await this.buildKnowledgeConnections(validatedRequest, similarPatterns);
// Step 5: Create the complete PRP template
console.log('📋 Assembling complete PRP template...');
const prpTemplate = await this.assemblePRPTemplate(validatedRequest, research, agentOptimizations, knowledgeConnections);
// Step 6: Create universal context pattern for storage
const contextPattern = await this.createContextPattern(prpTemplate, validatedRequest, research, knowledgeConnections);
// Step 7: Calculate confidence and learning applied
const confidenceScore = this.calculateOverallConfidence(research, similarPatterns.length);
const learningApplied = this.extractLearningApplied(similarPatterns, agentOptimizations);
console.log('✅ PRP generation complete with confidence:', confidenceScore);
return {
prp_template: prpTemplate,
context_pattern: contextPattern,
confidence_score: confidenceScore,
learning_applied: learningApplied
};
}
/**
* Find similar successful patterns from MongoDB
* Uses hybrid search: embeddings + metadata filtering
*/
async findSimilarPatterns(request) {
// This will use MongoDB Atlas Vector Search with effectiveness filtering
// For now, return empty array - will be implemented with MongoDB operations
return [];
}
/**
* Get agent-specific optimizations based on historical effectiveness
*/
async getAgentOptimizations(agentType, similarPatterns) {
// Extract learnings from similar patterns for this agent type
const agentLearnings = similarPatterns
.map(pattern => pattern.agent_optimizations[agentType])
.filter(opt => opt?.effectiveness_score > 7);
return {
format_preferences: agentLearnings.flatMap(opt => opt?.preferred_sections || []),
focus_areas: agentLearnings.flatMap(opt => opt?.focus || []),
avoid_patterns: agentLearnings.flatMap(opt => opt?.avoid_patterns || []),
effectiveness_score: agentLearnings.length > 0
? agentLearnings.reduce((sum, opt) => sum + (opt?.effectiveness_score || 0), 0) / agentLearnings.length
: 5
};
}
/**
* Build Context Portal style knowledge graph connections
*/
async buildKnowledgeConnections(request, similarPatterns) {
const connections = {
related_decisions: [],
dependent_patterns: [],
potential_conflicts: [],
architecture_impact: ''
};
// Extract knowledge graph connections from similar patterns
for (const pattern of similarPatterns) {
const kg = pattern.knowledge_graph;
// Find related architectural decisions
connections.related_decisions.push(...kg.decisions
.filter(d => d.status === 'accepted')
.map(d => `${d.title}: ${d.description}`));
// Find dependent patterns
connections.dependent_patterns.push(...kg.relationships.depends_on, ...kg.relationships.related_patterns);
// Find potential conflicts
connections.potential_conflicts.push(...kg.relationships.conflicts_with);
}
// Analyze architecture impact
connections.architecture_impact = this.analyzeArchitectureImpact(request.feature_description, request.project_context.tech_stack);
return connections;
}
/**
* Assemble the complete PRP template following Cole's verified structure
*/
async assemblePRPTemplate(request, research, agentOptimizations, knowledgeConnections) {
return {
// Header: Clear goal definition (Cole's emphasis on clarity)
header: {
goal: `Implement ${request.feature_description}`,
business_value: this.extractBusinessValue(request.feature_description),
success_criteria: this.generateSuccessCriteria(request.feature_description, research),
estimated_complexity: request.project_context.complexity_preference
},
// Research: Cole's comprehensive analysis
research_section: {
codebase_analysis: research.codebase_analysis,
external_research: research.external_research,
existing_patterns: research.existing_patterns,
potential_challenges: research.potential_challenges,
best_practices: research.best_practices,
confidence_score: research.confidence_score
},
// Implementation: Step-by-step blueprint (Cole's structured approach)
implementation_section: {
technical_requirements: this.generateTechnicalRequirements(request, research),
pseudocode: this.generatePseudocode(request, research),
task_breakdown: this.generateTaskBreakdown(request, research),
integration_points: this.identifyIntegrationPoints(request, research),
error_handling_strategy: this.generateErrorHandlingStrategy(request, research)
},
// Validation: Quality assurance (Cole's quality focus)
validation_section: {
syntax_checks: this.generateSyntaxChecks(request.project_context.tech_stack),
unit_test_commands: this.generateTestCommands(request.project_context.tech_stack),
integration_tests: this.generateIntegrationTests(request),
quality_checklist: this.generateQualityChecklist(request),
acceptance_criteria: this.generateAcceptanceCriteria(request.feature_description)
},
// Context Portal: Knowledge graph integration
knowledge_connections: knowledgeConnections,
// Agent-specific guidance (Universal optimization)
agent_guidance: {
cursor_specific: this.generateCursorGuidance(agentOptimizations, request),
windsurf_specific: this.generateWindsurfGuidance(agentOptimizations, request),
claude_code_specific: this.generateClaudeCodeGuidance(agentOptimizations, request),
universal_notes: this.generateUniversalNotes(agentOptimizations, request)
}
};
}
/**
* Create universal context pattern for MongoDB storage
*/
async createContextPattern(prpTemplate, request, research, knowledgeConnections) {
// Generate embeddings for the English methodology descriptions
const methodologyText = `${prpTemplate.header.goal}. ${prpTemplate.research_section.best_practices.join(' ')}`;
const contextText = `${prpTemplate.knowledge_connections.architecture_impact}. ${prpTemplate.knowledge_connections.related_decisions.join(' ')}`;
const queryText = request.feature_description;
// These would use Voyage AI embedding service
const embeddings = {
methodology_vector: await this.generateEmbedding(methodologyText),
context_vector: await this.generateEmbedding(contextText),
query_vector: await this.generateEmbedding(queryText)
};
return {
prp_methodology: {
research: {
codebase_analysis: research.codebase_analysis,
external_research: research.external_research,
documentation_urls: research.documentation_urls,
existing_patterns: research.existing_patterns,
potential_challenges: research.potential_challenges
},
implementation: {
goal: prpTemplate.header.goal,
business_value: prpTemplate.header.business_value,
technical_requirements: prpTemplate.implementation_section.technical_requirements,
pseudocode: prpTemplate.implementation_section.pseudocode,
task_breakdown: prpTemplate.implementation_section.task_breakdown,
error_handling_strategy: prpTemplate.implementation_section.error_handling_strategy,
integration_points: prpTemplate.implementation_section.integration_points
},
validation: {
syntax_checks: prpTemplate.validation_section.syntax_checks,
unit_test_commands: prpTemplate.validation_section.unit_test_commands,
integration_tests: prpTemplate.validation_section.integration_tests,
confidence_score: research.confidence_score,
quality_checklist: prpTemplate.validation_section.quality_checklist
}
},
knowledge_graph: {
decisions: [],
progress_entries: [],
system_patterns: [],
context_links: [],
custom_data: {},
workspace_context: {
workspace_id: 'default',
project_id: request.project_context.project_id
},
relationships: {
depends_on: knowledgeConnections.dependent_patterns,
enables: [],
conflicts_with: knowledgeConnections.potential_conflicts,
related_patterns: []
}
},
embeddings,
agent_optimizations: {
cursor: {
format: 'concise',
focus: ['implementation', 'validation'],
effectiveness_score: 7,
preferred_sections: ['header', 'implementation_section'],
avoid_patterns: ['lengthy_explanations']
},
windsurf: {
format: 'step_by_step',
focus: ['task_breakdown', 'error_handling'],
effectiveness_score: 7,
preferred_sections: ['implementation_section', 'validation_section'],
avoid_patterns: ['abstract_concepts']
},
claude_code: {
format: 'full_prp',
focus: ['research', 'comprehensive_analysis'],
effectiveness_score: 8,
preferred_sections: ['research_section', 'knowledge_connections'],
avoid_patterns: ['minimal_context']
},
generic: {
format: 'balanced',
focus: ['all_sections'],
effectiveness_score: 6,
preferred_sections: ['header', 'implementation_section'],
avoid_patterns: []
}
},
effectiveness_metrics: {
overall_success_rate: 0.0,
implementation_success_count: 0,
usage_count: 0,
last_used: new Date(),
improvement_suggestions: [],
feedback_history: []
},
metadata: {
pattern_type: this.classifyPatternType(request.feature_description),
complexity: request.project_context.complexity_preference,
project_types: ['universal'],
tech_stacks: request.project_context.tech_stack,
tags: this.generateTags(request.feature_description, request.project_context.tech_stack),
created_at: new Date(),
updated_at: new Date(),
version: 1
}
};
}
// Helper methods for PRP generation
extractBusinessValue(featureDescription) {
return `Enhance system capabilities by implementing ${featureDescription}, improving user experience and system functionality.`;
}
generateSuccessCriteria(featureDescription, research) {
return [
`${featureDescription} is fully implemented and functional`,
'All tests pass successfully',
'Code follows project standards and best practices',
'Integration with existing system is seamless',
'Performance meets or exceeds requirements'
];
}
generateTechnicalRequirements(request, research) {
const requirements = [
`Implement ${request.feature_description} using ${request.project_context.tech_stack.join(', ')}`,
'Follow existing code patterns and conventions',
'Ensure proper error handling and validation',
'Include comprehensive testing',
'Document API interfaces and usage'
];
// Add research-based requirements
requirements.push(...research.best_practices.slice(0, 3));
return requirements;
}
generatePseudocode(request, research) {
return `
// ${request.feature_description} Implementation Pseudocode
1. Initialize ${request.feature_description} module
2. Define core interfaces and types
3. Implement main functionality
4. Add error handling and validation
5. Create tests and documentation
6. Integrate with existing system
7. Validate and deploy
// Key considerations from research:
${research.potential_challenges.slice(0, 2).map(challenge => `// - ${challenge}`).join('\n')}
`.trim();
}
generateTaskBreakdown(request, research) {
return [
{
task: `Set up ${request.feature_description} foundation`,
order: 1,
dependencies: [],
validation: 'Basic structure created and compiles',
estimated_effort: '1-2 hours'
},
{
task: `Implement core ${request.feature_description} logic`,
order: 2,
dependencies: ['Set up foundation'],
validation: 'Core functionality works as expected',
estimated_effort: '2-4 hours'
},
{
task: 'Add error handling and validation',
order: 3,
dependencies: ['Implement core logic'],
validation: 'All edge cases handled properly',
estimated_effort: '1-2 hours'
},
{
task: 'Create comprehensive tests',
order: 4,
dependencies: ['Add error handling'],
validation: 'All tests pass with good coverage',
estimated_effort: '1-3 hours'
},
{
task: 'Integration and documentation',
order: 5,
dependencies: ['Create tests'],
validation: 'Feature fully integrated and documented',
estimated_effort: '1-2 hours'
}
];
}
identifyIntegrationPoints(request, research) {
return [
'Existing API endpoints and interfaces',
'Database schema and data models',
'Authentication and authorization systems',
'Configuration and environment setup',
'Logging and monitoring integration'
];
}
generateErrorHandlingStrategy(request, research) {
return `Implement comprehensive error handling with:
1. Input validation at all entry points
2. Graceful degradation for non-critical failures
3. Detailed logging for debugging and monitoring
4. User-friendly error messages
5. Proper HTTP status codes and responses
6. Transaction rollback for data consistency`;
}
generateSyntaxChecks(techStack) {
const checks = ['Basic syntax validation'];
if (techStack.includes('typescript')) {
checks.push('TypeScript type checking', 'ESLint validation');
}
if (techStack.includes('python')) {
checks.push('Python syntax check', 'Flake8 linting');
}
if (techStack.includes('rust')) {
checks.push('Cargo check', 'Clippy linting');
}
return checks;
}
generateTestCommands(techStack) {
const commands = [];
if (techStack.includes('javascript') || techStack.includes('typescript')) {
commands.push('npm test', 'npm run test:coverage');
}
if (techStack.includes('python')) {
commands.push('pytest', 'python -m pytest --cov');
}
if (techStack.includes('rust')) {
commands.push('cargo test');
}
return commands.length > 0 ? commands : ['Run project-specific test command'];
}
generateIntegrationTests(request) {
return [
`Test ${request.feature_description} with existing system components`,
'Verify database integration and data flow',
'Test API endpoints and responses',
'Validate authentication and authorization',
'Test error scenarios and edge cases'
];
}
generateQualityChecklist(request) {
return [
'Code follows project style guidelines',
'All functions have proper documentation',
'Error handling is comprehensive',
'Tests cover main functionality and edge cases',
'Performance is acceptable',
'Security considerations are addressed',
'Integration points work correctly'
];
}
generateAcceptanceCriteria(featureDescription) {
return [
`${featureDescription} meets all specified requirements`,
'User can successfully use the new feature',
'System performance is not negatively impacted',
'All existing functionality continues to work',
'Feature is properly documented and testable'
];
}
generateCursorGuidance(optimizations, request) {
return `Cursor optimization: Focus on concise, actionable implementation steps. Prioritize code examples and clear validation points.`;
}
generateWindsurfGuidance(optimizations, request) {
return `Windsurf optimization: Provide step-by-step breakdown with clear dependencies. Emphasize error handling and validation at each step.`;
}
generateClaudeCodeGuidance(optimizations, request) {
return `Claude Code optimization: Include comprehensive research context and detailed analysis. Provide full PRP with all supporting information.`;
}
generateUniversalNotes(optimizations, request) {
return `Universal notes: This PRP can be adapted for any AI coding agent. Focus areas and validation criteria are designed to work across different AI systems.`;
}
analyzeArchitectureImpact(featureDescription, techStack) {
return `Implementation of ${featureDescription} will integrate with existing ${techStack.join(', ')} architecture. Requires careful consideration of data flow, API design, and system boundaries.`;
}
async generateEmbedding(text) {
// Placeholder for Voyage AI embedding service
// Will return actual embeddings in implementation
return new Array(1024).fill(0).map(() => Math.random());
}
classifyPatternType(featureDescription) {
const lowerDesc = featureDescription.toLowerCase();
if (lowerDesc.includes('api') || lowerDesc.includes('endpoint'))
return 'api_implementation';
if (lowerDesc.includes('ui') || lowerDesc.includes('component'))
return 'ui_component';
if (lowerDesc.includes('database') || lowerDesc.includes('data'))
return 'data_management';
if (lowerDesc.includes('auth') || lowerDesc.includes('security'))
return 'security_feature';
if (lowerDesc.includes('test') || lowerDesc.includes('testing'))
return 'testing_framework';
return 'general_feature';
}
generateTags(featureDescription, techStack) {
const tags = [...techStack];
const lowerDesc = featureDescription.toLowerCase();
if (lowerDesc.includes('crud'))
tags.push('crud');
if (lowerDesc.includes('api'))
tags.push('api');
if (lowerDesc.includes('ui'))
tags.push('frontend');
if (lowerDesc.includes('database'))
tags.push('backend');
if (lowerDesc.includes('auth'))
tags.push('authentication');
if (lowerDesc.includes('test'))
tags.push('testing');
return [...new Set(tags)]; // Remove duplicates
}
calculateOverallConfidence(research, similarPatternsCount) {
let confidence = research.confidence_score;
// Boost confidence based on similar successful patterns
if (similarPatternsCount > 0) {
confidence += Math.min(similarPatternsCount * 0.5, 2);
}
return Math.min(confidence, 10);
}
extractLearningApplied(patterns, optimizations) {
const learning = ['Applied Cole\'s systematic research methodology'];
if (patterns.length > 0) {
learning.push(`Leveraged insights from ${patterns.length} similar successful patterns`);
}
if (optimizations.effectiveness_score > 7) {
learning.push('Applied high-effectiveness agent optimizations');
}
return learning;
}
}