context-awesome

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

• src/index.ts:280-381 (handler)

  MCP tool handler: validates input, fetches items via API client, formats them into structured Markdown with metadata, handles errors and empty results.
  async ({ listId, githubRepo, section, subcategory, tokens = DEFAULT_MINIMUM_TOKENS, offset = 0 }) => { if (!listId && !githubRepo) { return { content: [ { type: "text", text: "Either listId or githubRepo must be provided. Use 'find_awesome_section' first to discover available lists and sections.", }, ], }; } try { const response = await apiClient.getItems({ listId, githubRepo, section, subcategory, tokens, offset, }); if (!response.items || response.items.length === 0) { return { content: [ { type: "text", text: "No items found for the specified criteria. Try adjusting your filters or use find_awesome_section to discover available sections.", }, ], }; } const { metadata, items, tokenUsage } = response; const header = `# ${metadata.list.name}` + (metadata.section ? ` - ${metadata.section}` : '') + (metadata.subcategory ? ` > ${metadata.subcategory}` : '') + '\n\n'; const listDescription = metadata.list.description ? `> ${metadata.list.description}\n\n` : ''; const formattedItems = items .map((item, index) => { let itemText = `## ${index + 1}. ${item.name}\n\n`; if (item.description) { itemText += `${item.description}\n\n`; } itemText += `**URL**: ${item.url}\n`; if (item.githubRepo) { itemText += `**GitHub**: https://github.com/${item.githubRepo}\n`; } if (item.githubStars) { itemText += `**Stars**: ${item.githubStars.toLocaleString()}\n`; } if (item.tags && item.tags.length > 0) { itemText += `**Tags**: ${item.tags.join(', ')}\n`; } return itemText; }) .join('\n---\n\n'); const footer = `\n---\n\n` + `## Metadata\n\n` + `- **Token usage**: ${tokenUsage.used.toLocaleString()}/${tokenUsage.limit.toLocaleString()}` + (tokenUsage.truncated ? ' (truncated)' : '') + '\n' + `- **Items displayed**: ${items.length} of ${metadata.totalItems}\n` + (metadata.hasMore ? `- **Next page**: Use \`offset: ${metadata.offset + items.length}\` to get more items\n` : ''); return { content: [ { type: "text", text: header + listDescription + formattedItems + footer, }, ], }; } catch (error: any) { const apiError = error as APIError; return { content: [ { type: "text", text: apiError.message || "Failed to retrieve items. Please check your parameters and try again.", }, ], }; } }
• src/index.ts:248-279 (schema)

  Zod input schema definition for the get_awesome_items tool parameters including listId, githubRepo, section, subcategory, tokens, offset.
  inputSchema: { listId: z .string() .optional() .describe("UUID of the list (from find_awesome_section results)"), githubRepo: z .string() .optional() .describe("GitHub repo path (e.g., 'sindresorhus/awesome') from find_awesome_section results"), section: z .string() .optional() .describe("Category/section name to filter"), subcategory: z .string() .optional() .describe("Subcategory to filter"), tokens: z .preprocess((val) => (typeof val === "string" ? Number(val) : val), z.number()) .transform((val) => (val < DEFAULT_MINIMUM_TOKENS ? DEFAULT_MINIMUM_TOKENS : val)) .optional() .describe( `Maximum number of tokens to return (default: ${DEFAULT_MINIMUM_TOKENS}). Higher values provide more items but consume more tokens.` ), offset: z .number() .min(0) .optional() .default(0) .describe("Pagination offset for retrieving more items"), }, },
• src/index.ts:241-382 (registration)

  Registration of the get_awesome_items tool with MCP server using registerTool, including title, description, input schema, and handler reference.
  // Register get_awesome_items tool server.registerTool( "get_awesome_items", { title: "Get Awesome List Items", description: "Retrieves items from a specific awesome list or section with token limiting. You must call 'find_awesome_section' first to discover available sections, UNLESS the user explicitly provides a githubRepo or listId.", inputSchema: { listId: z .string() .optional() .describe("UUID of the list (from find_awesome_section results)"), githubRepo: z .string() .optional() .describe("GitHub repo path (e.g., 'sindresorhus/awesome') from find_awesome_section results"), section: z .string() .optional() .describe("Category/section name to filter"), subcategory: z .string() .optional() .describe("Subcategory to filter"), tokens: z .preprocess((val) => (typeof val === "string" ? Number(val) : val), z.number()) .transform((val) => (val < DEFAULT_MINIMUM_TOKENS ? DEFAULT_MINIMUM_TOKENS : val)) .optional() .describe( `Maximum number of tokens to return (default: ${DEFAULT_MINIMUM_TOKENS}). Higher values provide more items but consume more tokens.` ), offset: z .number() .min(0) .optional() .default(0) .describe("Pagination offset for retrieving more items"), }, }, async ({ listId, githubRepo, section, subcategory, tokens = DEFAULT_MINIMUM_TOKENS, offset = 0 }) => { if (!listId && !githubRepo) { return { content: [ { type: "text", text: "Either listId or githubRepo must be provided. Use 'find_awesome_section' first to discover available lists and sections.", }, ], }; } try { const response = await apiClient.getItems({ listId, githubRepo, section, subcategory, tokens, offset, }); if (!response.items || response.items.length === 0) { return { content: [ { type: "text", text: "No items found for the specified criteria. Try adjusting your filters or use find_awesome_section to discover available sections.", }, ], }; } const { metadata, items, tokenUsage } = response; const header = `# ${metadata.list.name}` + (metadata.section ? ` - ${metadata.section}` : '') + (metadata.subcategory ? ` > ${metadata.subcategory}` : '') + '\n\n'; const listDescription = metadata.list.description ? `> ${metadata.list.description}\n\n` : ''; const formattedItems = items .map((item, index) => { let itemText = `## ${index + 1}. ${item.name}\n\n`; if (item.description) { itemText += `${item.description}\n\n`; } itemText += `**URL**: ${item.url}\n`; if (item.githubRepo) { itemText += `**GitHub**: https://github.com/${item.githubRepo}\n`; } if (item.githubStars) { itemText += `**Stars**: ${item.githubStars.toLocaleString()}\n`; } if (item.tags && item.tags.length > 0) { itemText += `**Tags**: ${item.tags.join(', ')}\n`; } return itemText; }) .join('\n---\n\n'); const footer = `\n---\n\n` + `## Metadata\n\n` + `- **Token usage**: ${tokenUsage.used.toLocaleString()}/${tokenUsage.limit.toLocaleString()}` + (tokenUsage.truncated ? ' (truncated)' : '') + '\n' + `- **Items displayed**: ${items.length} of ${metadata.totalItems}\n` + (metadata.hasMore ? `- **Next page**: Use \`offset: ${metadata.offset + items.length}\` to get more items\n` : ''); return { content: [ { type: "text", text: header + listDescription + formattedItems + footer, }, ], }; } catch (error: any) { const apiError = error as APIError; return { content: [ { type: "text", text: apiError.message || "Failed to retrieve items. Please check your parameters and try again.", }, ], }; } } );
• src/api-client.ts:144-206 (helper)

  API client helper method that performs HTTP request to backend /api/get-items, processes and maps response data, handles token truncation and estimation.
  async getItems(params: GetItemsParams): Promise<GetItemsResponse> { this.log('Getting items with params:', params); if (!params.listId && !params.githubRepo) { const error: APIError = { code: 'INVALID_PARAMS', message: 'Either listId or githubRepo must be provided', }; throw error; } const response = await this.request<any>('/api/get-items', { listId: params.listId, githubRepo: params.githubRepo, section: params.section, subcategory: params.subcategory, limit: params.tokens ? Math.floor(params.tokens / 50) : undefined, offset: params.offset, }); const items = response.items || response.data || []; const metadata = response.metadata || response.meta || {}; const tokenCount = this.estimateTokens(items); const tokenLimit = params.tokens || 10000; const truncated = tokenCount > tokenLimit; const truncatedItems = truncated ? this.truncateToTokenLimit(items, tokenLimit) : items; return { items: truncatedItems.map((item: any) => ({ id: item.id || item._id || '', name: item.name || item.title || '', description: item.description || '', url: item.url || item.link || '', githubStars: item.stars || item.githubStars || item.github_stars, githubRepo: item.repo || item.githubRepo || item.github_repo, tags: item.tags || [], lastUpdated: item.lastUpdated || item.updated_at || item.last_updated, })), metadata: { list: { id: metadata.listId || metadata.list_id || params.listId || '', name: metadata.listName || metadata.list_name || '', githubRepo: metadata.githubRepo || metadata.github_repo || params.githubRepo || '', description: metadata.description || '', totalItems: metadata.totalItems || metadata.total_items || items.length, }, section: metadata.section || params.section, subcategory: metadata.subcategory || params.subcategory, totalItems: metadata.totalItems || metadata.total_items || items.length, offset: metadata.offset || params.offset || 0, hasMore: metadata.hasMore || metadata.has_more || false, }, tokenUsage: { used: this.estimateTokens(truncatedItems), limit: tokenLimit, truncated, }, }; }