stacksfinder-mcp

Instructions

Implementation Reference

• src/tools/recommend-demo.ts:162-242 (handler)

  The core handler function executeRecommendStackDemo that implements the tool's logic: checks daily usage limit, selects best technologies for project categories based on scores, formats a markdown table response, and promotes the pro version.

  export function executeRecommendStackDemo(
  	input: RecommendStackDemoInput
  ): { text: string; isError?: boolean } {
  	const { projectType, scale = 'mvp' } = input;
  
  	debug('recommend_stack_demo called', { projectType, scale });
  
  	// Check rate limit
  	if (wasDemoUsedToday()) {
  		const deviceId = getDeviceId();
  		return {
  			text: `## Daily Demo Limit Reached
  
  You've already used your free demo today.
  
  **Options:**
  1. Come back tomorrow for another free demo
  2. Create a free account at https://stacksfinder.com/register
  3. Upgrade to Pro for unlimited recommendations: https://stacksfinder.com/pricing
  
  **Pro benefits:**
  - Unlimited stack recommendations
  - Custom priorities (time-to-market, scalability, security, etc.)
  - Technology constraints
  - AI-generated implementation narratives
  - API access for automation
  - MCP integration with full features
  
  ---
  *Device ID: ${deviceId.slice(0, 8)}...*`,
  			isError: true
  		};
  	}
  
  	// Get categories for this project type
  	const categories = PROJECT_TYPE_CATEGORIES[projectType] || ['meta-framework', 'database', 'auth', 'hosting'];
  
  	// Get scoring context
  	const context = scaleToContext(scale);
  
  	// Select best tech per category
  	const recommendations = selectBestTechPerCategory(categories, context, projectType);
  
  	// Record usage
  	recordDemoUsage();
  
  	// Format response
  	const projectLabel = projectType.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
  
  	let text = `## Recommended Stack for ${projectLabel} (${scale})
  
  | Category | Technology | Score | Grade |
  |----------|------------|-------|-------|
  `;
  
  	for (const rec of recommendations) {
  		text += `| ${rec.category} | ${rec.technology} | ${rec.score} | ${rec.grade} |\n`;
  	}
  
  	text += `
  **Confidence**: medium (demo mode - no priorities/constraints applied)
  
  ---
  
  ### Want More?
  
  This is a **simplified demo**. The full version includes:
  - Custom priorities (time-to-market, scalability, security, etc.)
  - Technology constraints ("must use PostgreSQL", "no AWS")
  - Compatibility scoring between all selected technologies
  - AI-generated implementation narrative with setup guides
  - Confidence scoring (high/medium/low) based on your inputs
  
  **Upgrade to Pro**: https://stacksfinder.com/pricing
  **Create free account**: https://stacksfinder.com/register
  
  ---
  *Data version: ${DATA_VERSION} | Demo (1/day limit)*`;
  
  	return { text };
  }

• src/tools/recommend-demo.ts:37-40 (schema)

  Zod input schema validation for the tool parameters: projectType (required enum) and scale (optional enum).

  export const RecommendStackDemoInputSchema = z.object({
  	projectType: z.enum(PROJECT_TYPES).describe('Type of project'),
  	scale: z.enum(SCALES).optional().default('mvp').describe('Project scale')
  });

• src/server.ts:124-161 (registration)

  MCP server tool registration for 'recommend_stack_demo', including input schema definition, annotations, and handler wrapper that parses input and calls executeRecommendStackDemo.

  // Register recommend_stack_demo tool (FREE, local scoring, 1/day limit)
  server.registerTool(
  	recommendStackDemoToolDefinition.name,
  	{
  		title: 'Recommend Stack (Demo)',
  		description: recommendStackDemoToolDefinition.description,
  		inputSchema: {
  			projectType: z
  				.enum([
  					'web-app',
  					'mobile-app',
  					'api',
  					'desktop',
  					'cli',
  					'library',
  					'e-commerce',
  					'saas',
  					'marketplace'
  				])
  				.describe('Type of project'),
  			scale: z.enum(['mvp', 'startup', 'growth', 'enterprise']).optional().describe('Project scale')
  		},
  		annotations: {
  			readOnlyHint: true,
  			destructiveHint: false,
  			openWorldHint: false
  		}
  	},
  	async (args) => {
  		debug('recommend_stack_demo called', args);
  		const input = RecommendStackDemoInputSchema.parse(args);
  		const { text, isError } = executeRecommendStackDemo(input);
  		return {
  			content: [{ type: 'text', text }],
  			isError
  		};
  	}
  );

• src/tools/recommend-demo.ts:47-69 (schema)

  Tool definition object with name, description, and JSON schema for MCP tool listing/discovery.

  export const recommendStackDemoToolDefinition = {
  	name: 'recommend_stack_demo',
  	description: `Try StacksFinder's tech stack recommendations for FREE - once per day, no account required.
  
  Returns the optimal technology for each category based on deterministic scoring.
  For unlimited access, priorities, constraints, and AI-generated narratives, upgrade to Pro at https://stacksfinder.com/pricing`,
  	inputSchema: {
  		type: 'object' as const,
  		properties: {
  			projectType: {
  				type: 'string',
  				enum: PROJECT_TYPES,
  				description: 'Type of project (e.g., saas, web-app, api)'
  			},
  			scale: {
  				type: 'string',
  				enum: SCALES,
  				description: 'Project scale (mvp, startup, growth, enterprise)'
  			}
  		},
  		required: ['projectType']
  	}
  };

• src/tools/recommend-demo.ts:114-157 (helper)

  Helper function that selects the best technology for each category by calculating weighted overall scores from data module, used by the handler.

  function selectBestTechPerCategory(
  	categories: Category[],
  	context: Context,
  	projectType: string
  ): Array<{ category: Category; technology: string; score: number; grade: string }> {
  	const results: Array<{ category: Category; technology: string; score: number; grade: string }> = [];
  	const weights = PROJECT_TYPE_WEIGHTS[projectType] || {};
  
  	for (const category of categories) {
  		const techs = getTechnologiesByCategory(category);
  		if (techs.length === 0) continue;
  
  		let bestTech = techs[0];
  		let bestScore = 0;
  
  		for (const tech of techs) {
  			const scores = getScores(tech.id, context);
  			if (!scores) continue;
  
  			let overall = calculateOverallScore(scores);
  
  			// Apply project-type specific weight
  			const weight = weights[category] || 1.0;
  			overall = Math.round(overall * weight);
  
  			if (overall > bestScore) {
  				bestScore = overall;
  				bestTech = tech;
  			}
  		}
  
  		const finalScores = getScores(bestTech.id, context);
  		const finalScore = finalScores ? calculateOverallScore(finalScores) : 0;
  
  		results.push({
  			category,
  			technology: bestTech.name,
  			score: finalScore,
  			grade: scoreToGrade(finalScore)
  		});
  	}
  
  	return results;
  }