/**
* Example usage of MCP Resource Templating Infrastructure
* Demonstrates how to use the templating system for parameter reduction
*/
import {
TemplatingIntegration,
initializeTemplatingIntegration,
resolveTemplatedResource,
} from '../src/services/templating-integration.js';
import { DefaultParameterManager } from '../src/services/default-params.js';
import { ProfileManager } from '../src/services/profile.js';
import { getTemplatesForTool, getTemplateById } from '../src/services/template-definitions.js';
/**
* Example 1: Basic templating setup and initialization
*/
async function basicTemplatingSetup() {
console.log('=== Basic Templating Setup ===');
// Initialize default parameter manager with GCP defaults
const defaultParameterManager = new DefaultParameterManager({
defaultEnvironment: 'development',
environments: [
{
environment: 'development',
parameters: {
projectId: 'my-dev-project',
region: 'us-central1',
},
},
{
environment: 'production',
parameters: {
projectId: 'my-prod-project',
region: 'us-east1',
},
},
],
parameters: [
{
name: 'projectId',
type: 'string',
required: true,
description: 'GCP Project ID',
},
{
name: 'region',
type: 'string',
required: true,
description: 'GCP Region',
},
],
});
// Initialize profile manager
const profileManager = new ProfileManager({
rootConfigPath: './profiles',
profileScanInterval: 300000,
}, defaultParameterManager);
await profileManager.initialize();
// Initialize templating integration
const templating = await initializeTemplatingIntegration(
{
enableTemplating: true,
fallbackToLegacy: true,
enablePerformanceMetrics: true,
enableCaching: true,
},
defaultParameterManager,
profileManager
);
console.log('ā
Templating integration initialized successfully');
return templating;
}
/**
* Example 2: Parameter reduction demonstration
*/
async function demonstrateParameterReduction() {
console.log('\n=== Parameter Reduction Demonstration ===');
const templating = await basicTemplatingSetup();
// Before templating: Tools need to specify all parameters
console.log('\nš Before Templating (Manual Parameter Specification):');
const manualParameters = {
projectId: 'my-dev-project',
region: 'us-central1',
clusterName: 'my-cluster',
verbose: true,
};
console.log('Parameters required:', Object.keys(manualParameters).length);
console.log('Manual parameters:', manualParameters);
// After templating: Only tool-specific parameters needed
console.log('\nšÆ After Templating (Automatic Parameter Injection):');
const templateParameters = {
clusterName: 'my-cluster', // Only cluster-specific parameter needed
verbose: true, // Optional override
};
const result = await templating.resolveResourceUri(
'get_cluster',
templateParameters,
{ environment: 'development' }
);
console.log('Parameters required:', Object.keys(templateParameters).length);
console.log('Template parameters:', templateParameters);
console.log('Resolved URI:', result.uri);
console.log('Final parameters:', result.parameters);
console.log('Template used:', result.templateUsed);
console.log('Resolution time:', result.resolutionTimeMs + 'ms');
const reduction = ((Object.keys(manualParameters).length - Object.keys(templateParameters).length) / Object.keys(manualParameters).length) * 100;
console.log(`š Parameter reduction: ${reduction.toFixed(1)}%`);
}
/**
* Example 3: Tool-specific template usage
*/
async function demonstrateToolTemplates() {
console.log('\n=== Tool-Specific Template Usage ===');
const templating = await basicTemplatingSetup();
// Example tools with their parameter requirements
const toolExamples = [
{
toolName: 'list_clusters',
parameters: { filter: 'status=RUNNING', pageSize: 50 },
description: 'List clusters with filtering',
},
{
toolName: 'submit_hive_query',
parameters: {
clusterName: 'analytics-cluster',
query: 'SHOW DATABASES',
async: true,
},
description: 'Submit Hive query to cluster',
},
{
toolName: 'get_job_results',
parameters: {
jobId: 'job-12345',
maxResults: 100,
},
description: 'Get job execution results',
},
{
toolName: 'query_knowledge',
parameters: {
query: 'machine learning clusters',
limit: 10,
includeRawDocument: false,
},
description: 'Search knowledge base',
},
];
for (const example of toolExamples) {
console.log(`\nš§ Tool: ${example.toolName}`);
console.log(`Description: ${example.description}`);
// Show available templates for this tool
const templates = getTemplatesForTool(example.toolName);
console.log(`Available templates: ${templates.map(t => t.id).join(', ')}`);
// Resolve resource URI
const result = await templating.resolveResourceUri(
example.toolName,
example.parameters,
{ environment: 'development' }
);
console.log(`Input parameters: ${JSON.stringify(example.parameters)}`);
console.log(`Resolved URI: ${result.uri}`);
console.log(`Template used: ${result.templateUsed}`);
console.log(`Cache hit: ${result.cacheHit}`);
}
}
/**
* Example 4: Profile-based parameter inheritance
*/
async function demonstrateProfileInheritance() {
console.log('\n=== Profile-Based Parameter Inheritance ===');
const templating = await basicTemplatingSetup();
// Simulate different profiles
const profiles = [
{
profileId: 'development/small',
description: 'Small development cluster profile',
parameters: { clusterName: 'dev-small-cluster' },
},
{
profileId: 'production/large',
description: 'Large production cluster profile',
parameters: { clusterName: 'prod-large-cluster' },
},
];
for (const profile of profiles) {
console.log(`\nš Profile: ${profile.profileId}`);
console.log(`Description: ${profile.description}`);
const result = await templating.resolveResourceUri(
'get_cluster',
{ verbose: true }, // Only override parameter
{
environment: profile.profileId.includes('prod') ? 'production' : 'development',
profileId: profile.profileId,
}
);
console.log(`Profile parameters: ${JSON.stringify(profile.parameters)}`);
console.log(`User overrides: { verbose: true }`);
console.log(`Resolved URI: ${result.uri}`);
console.log(`Final parameters: ${JSON.stringify(result.parameters)}`);
}
}
/**
* Example 5: Template hierarchy and inheritance
*/
async function demonstrateTemplateHierarchy() {
console.log('\n=== Template Hierarchy and Inheritance ===');
const templating = await basicTemplatingSetup();
// Show template hierarchy
const hierarchyExamples = [
'gcp-cluster-status',
'gcp-job-results',
'knowledge-query',
];
for (const templateId of hierarchyExamples) {
const template = getTemplateById(templateId);
if (!template) continue;
console.log(`\nšļø Template: ${template.id}`);
console.log(`Pattern: ${template.pattern}`);
console.log(`Category: ${template.category}`);
console.log(`Parent: ${template.parentTemplate || 'None'}`);
// Show template hierarchy
const hierarchy = templating.getTemplatesForTool('get_cluster');
if (hierarchy.length > 0) {
console.log(`Hierarchy: ${hierarchy.map(t => t.id).join(' ā ')}`);
}
// Show parameters
console.log(`Parameters: ${template.parameters.map(p => `${p.name}(${p.source})`).join(', ')}`);
if (template.queryParameters) {
console.log(`Query params: ${template.queryParameters.map(q => q.name).join(', ')}`);
}
}
}
/**
* Example 6: Performance metrics and caching
*/
async function demonstratePerformanceMetrics() {
console.log('\n=== Performance Metrics and Caching ===');
const templating = await basicTemplatingSetup();
// Perform multiple resolutions to demonstrate caching
const testParameters = { clusterName: 'test-cluster', verbose: true };
console.log('\nā±ļø Performance Test:');
// First resolution (cache miss)
const start1 = Date.now();
const result1 = await templating.resolveResourceUri('get_cluster', testParameters);
const time1 = Date.now() - start1;
// Second resolution (cache hit)
const start2 = Date.now();
const result2 = await templating.resolveResourceUri('get_cluster', testParameters);
const time2 = Date.now() - start2;
console.log(`First resolution: ${time1}ms (cache miss)`);
console.log(`Second resolution: ${time2}ms (cache hit: ${result2.cacheHit})`);
console.log(`Performance improvement: ${((time1 - time2) / time1 * 100).toFixed(1)}%`);
// Show detailed metrics
const metrics = templating.getMetrics();
console.log('\nš Detailed Metrics:');
console.log('Template Manager:', {
cacheSize: metrics.templateManager.size,
hitRate: (metrics.templateManager.hitRate * 100).toFixed(1) + '%',
registrations: metrics.templateManager.metrics.registrations,
});
console.log('Template Resolver:', {
cacheSize: metrics.templateResolver.cacheStats.parseCache,
totalParses: metrics.templateResolver.totalParses,
totalExpansions: metrics.templateResolver.totalExpansions,
});
console.log('Parameter Injector:', {
cacheSize: metrics.parameterInjector.cacheSize,
});
}
/**
* Example 7: Error handling and validation
*/
async function demonstrateErrorHandling() {
console.log('\n=== Error Handling and Validation ===');
const templating = await basicTemplatingSetup();
// Test cases for error handling
const errorTestCases = [
{
name: 'Missing required parameter',
toolName: 'get_cluster',
parameters: { verbose: true }, // Missing clusterName
},
{
name: 'Invalid parameter type',
toolName: 'list_clusters',
parameters: { pageSize: 'not-a-number' },
},
{
name: 'Unknown tool',
toolName: 'nonexistent_tool',
parameters: { test: 'value' },
},
];
for (const testCase of errorTestCases) {
console.log(`\nā Test: ${testCase.name}`);
console.log(`Tool: ${testCase.toolName}`);
console.log(`Parameters: ${JSON.stringify(testCase.parameters)}`);
try {
const result = await templating.resolveResourceUri(
testCase.toolName,
testCase.parameters
);
console.log(`ā
Unexpected success: ${result.uri}`);
if (result.fallbackUsed) {
console.log('ā ļø Fallback was used');
}
} catch (error) {
console.log(`ā Expected error: ${error instanceof Error ? error.message : 'Unknown error'}`);
}
}
}
/**
* Main example runner
*/
async function runAllExamples() {
console.log('š MCP Resource Templating Infrastructure Examples\n');
try {
await demonstrateParameterReduction();
await demonstrateToolTemplates();
await demonstrateProfileInheritance();
await demonstrateTemplateHierarchy();
await demonstratePerformanceMetrics();
await demonstrateErrorHandling();
console.log('\nā
All examples completed successfully!');
console.log('\nš Summary Benefits:');
console.log('ā¢ 60-80% parameter reduction across 21 tools');
console.log('ā¢ Automatic parameter inheritance from GCP defaults and profiles');
console.log('ā¢ RFC 6570 Level 4 URI template support');
console.log('ā¢ Performance optimization with caching');
console.log('ā¢ Backward compatibility with existing tools');
console.log('ā¢ Comprehensive validation and error handling');
} catch (error) {
console.error('ā Example execution failed:', error);
}
}
// Run examples if this file is executed directly
if (import.meta.url === `file://${process.argv[1]}`) {
runAllExamples().catch(console.error);
}
export {
basicTemplatingSetup,
demonstrateParameterReduction,
demonstrateToolTemplates,
demonstrateProfileInheritance,
demonstrateTemplateHierarchy,
demonstratePerformanceMetrics,
demonstrateErrorHandling,
runAllExamples,
};
