stacksfinder-mcp

Instructions

Implementation Reference

• src/tools/recommend.ts:142-173 (handler)

  Main handler function for the recommend_stack tool. Calls the scoring API with project inputs, formats the response as a markdown table with JSON, and handles errors.

  export async function executeRecommendStack(
  	input: RecommendStackInput
  ): Promise<{ text: string; isError?: boolean }> {
  	const { projectType, scale = 'mvp', priorities = [], constraints = [] } = input;
  
  	// Deduplicate priorities
  	const uniquePriorities = [...new Set(priorities)].slice(0, 3);
  
  	debug('Calling score API', { projectType, scale, priorities: uniquePriorities, constraints });
  
  	try {
  		const response = await scoreRequest<ScoreApiResponse>({
  			projectType,
  			scale,
  			priorities: uniquePriorities,
  			constraints
  		});
  
  		const text = formatResponse(response, projectType, scale);
  		return { text };
  	} catch (err) {
  		if (err instanceof McpError) {
  			return { text: err.toResponseText(), isError: true };
  		}
  
  		const error = new McpError(
  			ErrorCode.API_ERROR,
  			err instanceof Error ? err.message : 'Failed to get recommendations'
  		);
  		return { text: error.toResponseText(), isError: true };
  	}
  }

• src/tools/recommend.ts:42-52 (schema)

  Zod input schema for validating recommend_stack tool arguments.

  export const RecommendStackInputSchema = z.object({
  	projectType: z.enum(PROJECT_TYPES).describe('Type of project'),
  	scale: z.enum(SCALES).optional().default('mvp').describe('Project scale'),
  	priorities: z
  		.array(z.enum(PRIORITIES))
  		.max(3)
  		.optional()
  		.default([])
  		.describe('Top priorities (max 3)'),
  	constraints: z.array(z.string()).optional().default([]).describe('Project constraints')
  });

• src/server.ts:163-216 (registration)

  MCP server registration of the recommend_stack tool, including input schema override and handler wrapper.

  // Register recommend_stack tool (API-based, requires API key)
  server.registerTool(
  	recommendStackToolDefinition.name,
  	{
  		title: 'Recommend Stack',
  		description: recommendStackToolDefinition.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'),
  			priorities: z
  				.array(
  					z.enum([
  						'time-to-market',
  						'scalability',
  						'developer-experience',
  						'cost-efficiency',
  						'performance',
  						'security',
  						'maintainability'
  					])
  				)
  				.max(3)
  				.optional()
  				.describe('Top priorities (max 3)'),
  			constraints: z.array(z.string()).optional().describe('Project constraints')
  		},
  		annotations: {
  			readOnlyHint: true,
  			destructiveHint: false,
  			openWorldHint: false
  		}
  	},
  	async (args) => {
  		debug('recommend_stack called', args);
  		const input = RecommendStackInputSchema.parse(args);
  		const { text, isError } = await executeRecommendStack(input);
  		return {
  			content: [{ type: 'text', text }],
  			isError
  		};
  	}
  );

• src/tools/recommend.ts:59-90 (schema)

  Tool definition exported for MCP registration, confirming the tool name 'recommend_stack' and providing the input schema structure.

  export const recommendStackToolDefinition = {
  	name: 'recommend_stack',
  	description:
  		'Recommends the best tech stack for a project using real-time scoring with context adjustments. Requires API key.',
  	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)'
  			},
  			priorities: {
  				type: 'array',
  				items: { type: 'string', enum: PRIORITIES },
  				maxItems: 3,
  				description: 'Top priorities (max 3)'
  			},
  			constraints: {
  				type: 'array',
  				items: { type: 'string' },
  				description: 'Project constraints (e.g., real-time, multi-tenant)'
  			}
  		},
  		required: ['projectType']
  	}
  };

• src/tools/recommend.ts:110-137 (helper)

  Helper function to format the API response into a markdown table with embedded JSON for the tool output.

  function formatResponse(response: ScoreApiResponse, projectType: string, scale: string): string {
  	let text = `## Recommended Stack for ${projectType.replace('-', ' ').replace(/\b\w/g, (c) => c.toUpperCase())} (${scale})
  
  | Category | Technology | Score | Grade |
  |----------|------------|-------|-------|
  `;
  
  	for (const stack of response.stacks) {
  		text += `| ${stack.category} | ${stack.technology} | ${stack.score} | ${stack.grade} |\n`;
  	}
  
  	text += `
  **Confidence**: ${response.confidence}`;
  
  	if (response.requestId) {
  		text += `
  **Request ID**: ${response.requestId}`;
  	}
  
  	// Include raw JSON for programmatic access
  	text += `
  
  <json>
  ${JSON.stringify({ stacks: response.stacks, confidence: response.confidence, inputsNormalized: response.inputsNormalized })}
  </json>`;
  
  	return text;
  }