context-awesome

Instructions

Implementation Reference

• src/index.ts:122-239 (registration)

  Registration of the 'find_awesome_section' MCP tool, including schema definition and handler function.
  server.registerTool( "find_awesome_section", { title: "Find Awesome List Section", description: `Discovers sections/categories across awesome lists matching a search query and returns matching sections from awesome lists. You MUST call this function before 'get_awesome_items' to discover available sections UNLESS the user explicitly provides a githubRepo or listId. Selection Process: 1. Analyze the query to understand what type of resources the user is looking for 2. Return the most relevant matches based on: - Name similarity to the query and the awesome lists section - Category/section relevance of the awesome lists - Number of items in the section - Confidence score Response Format: - Returns matching sections of the awesome lists with metadata - Includes repository information, item counts, and confidence score - Use the githubRepo or listId with relevant sections from results for get_awesome_items For ambiguous queries, multiple relevant sections will be returned for the user to choose from.`, inputSchema: { query: z .string() .describe("Search terms for finding sections across awesome lists"), confidence: z .number() .min(0) .max(1) .optional() .default(0.3) .describe("Minimum confidence score (0-1)"), limit: z .number() .min(1) .max(50) .optional() .default(10) .describe("Maximum sections to return"), }, }, async ({ query, confidence = 0.3, limit = 10 }) => { try { const response = await apiClient.findSections({ query, confidence, limit }); if (!response.sections || response.sections.length === 0) { return { content: [ { type: "text", text: `No sections found matching "${query}". Try different search terms or browse available lists.`, }, ], }; } const formattedSections = response.sections .map( (section) => { const githubUrl = `https://github.com/${section.githubRepo}`; const sectionPath = section.category.toLowerCase().replace(/\s+/g, '-'); const sectionUrl = `${githubUrl}#${sectionPath}`; return `### ${section.listName} - ${section.category}${ section.subcategory ? ` > ${section.subcategory}` : '' } - **Repository**: \`${section.githubRepo}\` - **GitHub URL**: ${githubUrl} - **Section URL**: ${sectionUrl} - **Items**: ${section.itemCount} - **Confidence**: ${(section.confidence * 100).toFixed(1)}% - **Description**: ${ section.description || `A curated collection of ${section.itemCount} ${section.category.toLowerCase()} resources from ${section.listName}` }`; } ) .join('\n\n'); return { content: [ { type: "text", text: `# Search Results for "${query}" Found ${response.sections.length} relevant sections across awesome lists. ${formattedSections} --- ## How to retrieve items To get detailed items from any section above, use the \`get_awesome_items\` tool with: - **githubRepo**: The repository path (e.g., \`"${response.sections[0]?.githubRepo || 'repo/name'}"\`) - **section** (optional): The category name to filter results (e.g., \`"${response.sections[0]?.category || 'Section Name'}"\`) - **tokens** (optional): Maximum tokens to return (default: 10000) - **offset** (optional): For pagination (default: 0) Higher confidence scores indicate better matches for your search query.`, }, ], }; } catch (error: any) { const apiError = error as APIError; return { content: [ { type: "text", text: apiError.message || "Failed to search for sections. Please try again.", }, ], }; } } );
• src/index.ts:164-239 (handler)

  The main handler function that executes the tool logic: calls the API client, formats results into markdown, handles errors.
  async ({ query, confidence = 0.3, limit = 10 }) => { try { const response = await apiClient.findSections({ query, confidence, limit }); if (!response.sections || response.sections.length === 0) { return { content: [ { type: "text", text: `No sections found matching "${query}". Try different search terms or browse available lists.`, }, ], }; } const formattedSections = response.sections .map( (section) => { const githubUrl = `https://github.com/${section.githubRepo}`; const sectionPath = section.category.toLowerCase().replace(/\s+/g, '-'); const sectionUrl = `${githubUrl}#${sectionPath}`; return `### ${section.listName} - ${section.category}${ section.subcategory ? ` > ${section.subcategory}` : '' } - **Repository**: \`${section.githubRepo}\` - **GitHub URL**: ${githubUrl} - **Section URL**: ${sectionUrl} - **Items**: ${section.itemCount} - **Confidence**: ${(section.confidence * 100).toFixed(1)}% - **Description**: ${ section.description || `A curated collection of ${section.itemCount} ${section.category.toLowerCase()} resources from ${section.listName}` }`; } ) .join('\n\n'); return { content: [ { type: "text", text: `# Search Results for "${query}" Found ${response.sections.length} relevant sections across awesome lists. ${formattedSections} --- ## How to retrieve items To get detailed items from any section above, use the \`get_awesome_items\` tool with: - **githubRepo**: The repository path (e.g., \`"${response.sections[0]?.githubRepo || 'repo/name'}"\`) - **section** (optional): The category name to filter results (e.g., \`"${response.sections[0]?.category || 'Section Name'}"\`) - **tokens** (optional): Maximum tokens to return (default: 10000) - **offset** (optional): For pagination (default: 0) Higher confidence scores indicate better matches for your search query.`, }, ], }; } catch (error: any) { const apiError = error as APIError; return { content: [ { type: "text", text: apiError.message || "Failed to search for sections. Please try again.", }, ], }; } } );
• src/index.ts:144-162 (schema)

  Zod input schema validation for the tool parameters.
  inputSchema: { query: z .string() .describe("Search terms for finding sections across awesome lists"), confidence: z .number() .min(0) .max(1) .optional() .default(0.3) .describe("Minimum confidence score (0-1)"), limit: z .number() .min(1) .max(50) .optional() .default(10) .describe("Maximum sections to return"), },
• src/index.ts:1-22 (schema)

  TypeScript interfaces defining input parameters, section data, and response structure for find_awesome_section.
  #!/usr/bin/env node import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"; import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js"; import { z } from "zod"; import { createServer } from "http"; import { Command } from "commander"; import { IncomingMessage } from "http"; import { AwesomeContextAPIClient } from "./api-client.js"; import { APIError } from "./types.js"; const DEFAULT_MINIMUM_TOKENS = 10000; // Parse CLI arguments using commander const program = new Command() .option("--transport <stdio|http>", "transport type", "stdio") .option("--port <number>", "port for HTTP transport", "3000") .option("--api-host <url>", "Backend API host URL", process.env.AWESOME_CONTEXT_API_HOST || "https://api.context-awesome.com") .option("--api-key <key>", "API key for authentication") .option("--debug", "Enable debug logging")
• src/api-client.ts:116-142 (helper)

  API client method that performs the actual backend API call for finding sections.
  async findSections(params: FindSectionParams): Promise<FindSectionResponse> { this.log('Finding sections with params:', params); const response = await this.request<any>('/api/find-section', { query: params.query, // Changed from 'q' to 'query' confidence: params.confidence, limit: params.limit, }); // Handle both 'results' and 'sections' response formats const sections = response.results || response.sections || []; return { sections: sections.map((section: any) => ({ id: section.id || section._id || '', listId: section.listId || '', listName: section.listName || section.list_name || '', githubRepo: section.githubRepo || section.github_repo || '', category: section.category || section.section || '', subcategory: section.subcategory || section.sub_category || '', itemCount: section.itemCount || section.item_count || 0, confidence: section.confidence || section.score || 0, description: section.description || '', })), total: response.total || sections.length, }; }