stacksfinder-mcp

Instructions

Implementation Reference

• src/tools/blueprint.ts:102-131 (handler)

  The main handler function executeGetBlueprint that fetches the blueprint from the API using getBlueprintRequest, formats it with formatBlueprint, and handles errors.
  export async function executeGetBlueprint( input: GetBlueprintInput ): Promise<{ text: string; isError?: boolean }> { const { blueprintId } = input; debug('Fetching blueprint', { blueprintId }); try { const response = await getBlueprintRequest<BlueprintApiResponse>(blueprintId); const text = formatBlueprint(response); return { text }; } catch (err) { if (err instanceof McpError) { // Add helpful suggestion for NOT_FOUND if (err.code === ErrorCode.NOT_FOUND) { err.suggestions = [ 'Blueprints are generated via the StacksFinder web UI.', 'Visit https://stacksfinder.com to create a new blueprint.' ]; } return { text: err.toResponseText(), isError: true }; } const error = new McpError( ErrorCode.API_ERROR, err instanceof Error ? err.message : 'Failed to fetch blueprint' ); return { text: error.toResponseText(), isError: true }; } }
• src/tools/blueprint.ts:15-17 (schema)

  Zod schema for validating the input to the get_blueprint tool, requiring a blueprintId UUID.
  export const GetBlueprintInputSchema = z.object({ blueprintId: z.string().uuid().describe('Blueprint UUID') });
• src/server.ts:219-241 (registration)

  Registers the 'get_blueprint' tool with the MCP server, specifying input schema, annotations, and wiring the executeGetBlueprint handler.
  server.registerTool( getBlueprintToolDefinition.name, { title: 'Get Blueprint', description: getBlueprintToolDefinition.description, inputSchema: { blueprintId: z.string().uuid().describe('Blueprint UUID') }, annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false } }, async (args) => { debug('get_blueprint called', args); const input = GetBlueprintInputSchema.parse(args); const { text, isError } = await executeGetBlueprint(input); return { content: [{ type: 'text', text }], isError }; }
• src/tools/blueprint.ts:24-39 (schema)

  MCP tool definition including name, description, and strict input schema used during registration.
  export const getBlueprintToolDefinition = { name: 'get_blueprint', description: 'Fetches an existing blueprint by ID. Blueprints are generated via the StacksFinder web UI. Requires API key.', inputSchema: { type: 'object' as const, properties: { blueprintId: { type: 'string', format: 'uuid', description: 'Blueprint UUID' } }, required: ['blueprintId'] } };
• src/tools/blueprint.ts:63-97 (helper)

  Helper function that formats the raw API blueprint response into a readable Markdown table with project details and tech stack.
  function formatBlueprint(blueprint: BlueprintApiResponse): string { const projectName = blueprint.projectContext?.projectName || 'Unnamed Project'; const projectType = blueprint.projectContext?.projectType || 'Unknown'; const scale = blueprint.projectContext?.scale || 'mvp'; const createdDate = new Date(blueprint.createdAt).toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' }); let text = `## Blueprint: ${projectName} **ID**: ${blueprint.id} **Type**: ${projectType} **Scale**: ${scale} **Created**: ${createdDate} ### Selected Stack | Category | Technology | |----------|------------| `; for (const tech of blueprint.selectedTechs) { text += `| ${tech.category} | ${tech.technology} |\n`; } if (blueprint.narrative) { text += ` ### Narrative ${blueprint.narrative}`; } return text; }