@depthark/css-first

Instructions

Implementation Reference

• src/index.ts:79-162 (handler)

  Primary execution logic for the suggest_css_solution tool. Processes input parameters, performs semantic analysis, searches MDN for CSS properties, adds consent prompts, and returns structured JSON response.
  async (args: { task_description: string; preferred_approach?: "modern" | "compatible" | "progressive"; target_browsers?: string[]; project_context?: string; include_analysis?: boolean; }) => { try { const { task_description, preferred_approach = "modern", project_context, include_analysis = false, } = args; // Enhanced semantic analysis and intelligent search const suggestions: CSSPropertySuggestion[] = await searchMDNForCSSProperties( task_description, preferred_approach, project_context ); // Get analysis details if requested let analysisDetails = null; if (include_analysis) { const { analyzeTaskIntent } = await import("./services/mdnApi.js"); analysisDetails = analyzeTaskIntent(task_description, project_context); } const result = suggestions.length === 0 ? { success: false, message: "No CSS-ONLY solutions found. This tool provides ONLY CSS solutions - no JavaScript alternatives will be suggested. Please rephrase your request to focus on CSS-achievable UI patterns.", suggestions: [], ...(analysisDetails && { analysis: analysisDetails }), } : { success: true, message: `Found ${suggestions.length} CSS-ONLY solution(s) using modern CSS features. All solutions are JavaScript-free and use logical properties by default.`, suggestions: suggestions.map((suggestion) => ({ ...suggestion, needs_consent: true, consent_message: `Do you want to use the CSS property "${suggestion.property}" which has ${suggestion.browser_support.overall_support}% browser support?`, })), ...(analysisDetails && { analysis: { ...analysisDetails, explanation: `Analyzed with ${Math.round( analysisDetails.confidence * 100 )}% confidence. Detected intent: ${analysisDetails.intent.join( ", " )}.`, }, }), }; return { content: [ { type: "text" as const, text: JSON.stringify(result, null, 2), }, ], }; } catch (error) { return { content: [ { type: "text" as const, text: JSON.stringify( { error: error instanceof Error ? error.message : "Unknown error", }, null, 2 ), }, ], }; } }
• src/index.ts:49-163 (registration)

  Registration of the 'suggest_css_solution' tool on the MCP server, including name, description, input schema, and inline handler function.
  server.tool( "suggest_css_solution", "CSS-ONLY solution engine with strict enforcement of modern CSS features. Provides zero-JavaScript solutions using cutting-edge CSS (2021-2025) with logical properties, modern carousels, and light-dark() theming.", { task_description: z .string() .describe("Description of the UI task or problem to solve"), preferred_approach: z .enum(["modern", "compatible", "progressive"]) .optional() .describe( "Preferred CSS approach - modern (latest features), compatible (wide browser support), or progressive (with fallbacks)" ), target_browsers: z .array(z.string()) .optional() .describe( 'Target browsers/versions (e.g., ["Chrome 90+", "Firefox 88+", "Safari 14+"])' ), project_context: z .string() .optional() .describe( "Project context (framework, existing CSS patterns, constraints)" ), include_analysis: z .boolean() .optional() .describe("Include semantic analysis details in response"), }, async (args: { task_description: string; preferred_approach?: "modern" | "compatible" | "progressive"; target_browsers?: string[]; project_context?: string; include_analysis?: boolean; }) => { try { const { task_description, preferred_approach = "modern", project_context, include_analysis = false, } = args; // Enhanced semantic analysis and intelligent search const suggestions: CSSPropertySuggestion[] = await searchMDNForCSSProperties( task_description, preferred_approach, project_context ); // Get analysis details if requested let analysisDetails = null; if (include_analysis) { const { analyzeTaskIntent } = await import("./services/mdnApi.js"); analysisDetails = analyzeTaskIntent(task_description, project_context); } const result = suggestions.length === 0 ? { success: false, message: "No CSS-ONLY solutions found. This tool provides ONLY CSS solutions - no JavaScript alternatives will be suggested. Please rephrase your request to focus on CSS-achievable UI patterns.", suggestions: [], ...(analysisDetails && { analysis: analysisDetails }), } : { success: true, message: `Found ${suggestions.length} CSS-ONLY solution(s) using modern CSS features. All solutions are JavaScript-free and use logical properties by default.`, suggestions: suggestions.map((suggestion) => ({ ...suggestion, needs_consent: true, consent_message: `Do you want to use the CSS property "${suggestion.property}" which has ${suggestion.browser_support.overall_support}% browser support?`, })), ...(analysisDetails && { analysis: { ...analysisDetails, explanation: `Analyzed with ${Math.round( analysisDetails.confidence * 100 )}% confidence. Detected intent: ${analysisDetails.intent.join( ", " )}.`, }, }), }; return { content: [ { type: "text" as const, text: JSON.stringify(result, null, 2), }, ], }; } catch (error) { return { content: [ { type: "text" as const, text: JSON.stringify( { error: error instanceof Error ? error.message : "Unknown error", }, null, 2 ), }, ], }; } } );
• src/index.ts:52-78 (schema)

  Zod input schema defining parameters for the tool: task_description, preferred_approach, target_browsers, project_context, include_analysis.
  { task_description: z .string() .describe("Description of the UI task or problem to solve"), preferred_approach: z .enum(["modern", "compatible", "progressive"]) .optional() .describe( "Preferred CSS approach - modern (latest features), compatible (wide browser support), or progressive (with fallbacks)" ), target_browsers: z .array(z.string()) .optional() .describe( 'Target browsers/versions (e.g., ["Chrome 90+", "Firefox 88+", "Safari 14+"])' ), project_context: z .string() .optional() .describe( "Project context (framework, existing CSS patterns, constraints)" ), include_analysis: z .boolean() .optional() .describe("Include semantic analysis details in response"), },
• src/services/css/suggestions.ts:289-302 (helper)

  Core helper function called by the handler to perform semantic analysis and search for relevant CSS properties based on task description.
  export async function searchMDNForCSSProperties( description: string | string[], approach: 'modern' | 'compatible' | 'progressive' = 'modern', projectContext?: any ): Promise<CSSPropertySuggestion[]> { // Handle backward compatibility with keyword array if (Array.isArray(description)) { return searchLegacyKeywords(description, approach); } // New semantic analysis approach const analysis = analyzeTaskIntent(description, projectContext); return searchWithIntelligentRanking(analysis, approach, projectContext); }
• src/services/css/suggestions.ts:79-159 (helper)

  Helper function for semantic analysis of task intent, keyword extraction, framework detection, and category suggestion. Used optionally in handler and by searchMDNForCSSProperties.
  export function analyzeTaskIntent(description: string, projectContext?: any): { keywords: string[]; intent: string[]; confidence: number; suggestedCategories: CSSFeatureCategory[]; frameworkHints: string[]; contextAnalysis?: any; recommendations?: string[]; } { const keywords: string[] = []; const intent: string[] = []; const suggestedCategories: CSSFeatureCategory[] = []; const frameworkHints: string[] = []; let totalMatches = 0; let totalPatterns = 0; // Analyze project context const contextAnalysis = analyzeProjectContext(projectContext); // Analyze intent patterns for (const [intentType, config] of Object.entries(INTENT_PATTERNS)) { let intentMatches = 0; for (const pattern of config.patterns) { totalPatterns++; if (pattern.test(description)) { intentMatches++; totalMatches++; } } if (intentMatches > 0) { intent.push(intentType); suggestedCategories.push(...config.categories); } } // Extract framework hints from project context and description if (contextAnalysis.framework) { frameworkHints.push(contextAnalysis.framework); } if (contextAnalysis.cssFramework) { frameworkHints.push(contextAnalysis.cssFramework); } // Additional framework detection from description for (const [framework, indicators] of Object.entries(FRAMEWORK_INDICATORS)) { if (indicators.some(indicator => description.toLowerCase().includes(indicator) )) { frameworkHints.push(framework); } } // Legacy keyword extraction for backward compatibility keywords.push(...extractLegacyKeywords(description)); const confidence = totalPatterns > 0 ? totalMatches / totalPatterns : 0; // Generate context-aware recommendations const recommendations: string[] = []; if (contextAnalysis.framework) { recommendations.push(...getFrameworkSpecificRecommendations(contextAnalysis.framework)); } if (contextAnalysis.cssFramework) { recommendations.push(...getCSSFrameworkRecommendations(contextAnalysis.cssFramework)); } // Add logical units recommendations const writingModeRecommendations = getWritingModeRecommendations(projectContext); recommendations.push(...writingModeRecommendations); return { keywords: [...new Set(keywords)], intent: [...new Set(intent)], confidence, suggestedCategories: [...new Set(suggestedCategories)], frameworkHints: [...new Set(frameworkHints)], contextAnalysis, recommendations: recommendations.length > 0 ? recommendations : undefined }; }