awess 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "awess",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "MCP server for searching curated awesome lists and their contents",
   "type": "module",
   "main": "src/index.ts",

package/src/index.ts

@@ -3,7 +3,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import MiniSearch from "minisearch";
 import { z } from "zod";
-import type { ItemsIndex } from "./types";
+import type { ItemsIndex, Item } from "./types";
 
 interface AwesomeList {
   repo: string;
@@ -14,6 +14,11 @@ interface AwesomeList {
   source: string;
 }
 
+interface IndexedItem extends Item {
+  id: number;
+  listRepo: string;
+}
+
 // CDN URLs - jsDelivr primary (faster, global CDN), GitHub raw fallback
 const JSDELIVR_URL = "https://cdn.jsdelivr.net/gh/arimxyer/ass@main/data";
 const GITHUB_RAW_URL = "https://raw.githubusercontent.com/arimxyer/ass/main/data";
@@ -81,8 +86,8 @@ async function loadGzippedData<T>(filename: string): Promise<T> {
 // Load curated data
 const lists: AwesomeList[] = await loadData("lists.json");
 
-// Initialize search index
-const search = new MiniSearch<AwesomeList>({
+// Initialize list search index
+const listSearch = new MiniSearch<AwesomeList>({
   fields: ["name", "repo", "description"],
   storeFields: ["repo", "name", "stars", "description", "pushed_at", "source"],
   searchOptions: {
@@ -92,235 +97,216 @@ const search = new MiniSearch<AwesomeList>({
   },
 });
 
-// Index all lists with repo as id
-search.addAll(lists.map((list, i) => ({ id: i, ...list })));
+// Index all lists
+listSearch.addAll(lists.map((list, i) => ({ id: i, ...list })));
 
-// Create MCP server
-const server = new McpServer({
-  name: "ass",
-  version: "0.1.0",
-});
+// Load items index
+let itemsIndex: ItemsIndex | null = null;
+let allItems: IndexedItem[] = [];
+let itemSearch: MiniSearch<IndexedItem> | null = null;
 
-// Tool: Search awesome lists
-server.tool(
-  "search",
-  "Search curated awesome lists by keyword. Returns matching lists sorted by relevance and stars.",
-  {
-    query: z.string().describe("Search query (e.g., 'rust', 'machine learning', 'react')"),
-    limit: z.number().optional().describe("Maximum results to return (default: 10)"),
-    minStars: z.number().optional().describe("Minimum star count filter (default: 0)"),
-  },
-  async ({ query, limit = 10, minStars = 0 }) => {
-    const results = search
-      .search(query)
-      .filter((r) => r.stars >= minStars)
-      .slice(0, limit)
-      .map((r) => ({
-        repo: r.repo,
-        name: r.name,
-        stars: r.stars,
-        description: r.description,
-        lastUpdated: r.pushed_at,
-        score: r.score,
-      }));
+try {
+  itemsIndex = await loadGzippedData<ItemsIndex>("items.json.gz");
 
-    return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify(results, null, 2),
-        },
-      ],
-    };
+  // Build flat list of all items for global search
+  let itemId = 0;
+  for (const [listRepo, entry] of Object.entries(itemsIndex.lists)) {
+    for (const item of entry.items) {
+      allItems.push({ ...item, id: itemId++, listRepo });
+    }
   }
-);
 
-// Tool: Get list details
+  // Initialize item search index
+  itemSearch = new MiniSearch<IndexedItem>({
+    fields: ["name", "description", "category"],
+    storeFields: ["name", "url", "description", "category", "subcategory", "github", "listRepo"],
+    searchOptions: {
+      boost: { name: 2, category: 1.5, description: 1 },
+      fuzzy: 0.2,
+      prefix: true,
+    },
+  });
+
+  itemSearch.addAll(allItems);
+
+  console.error(`Loaded ${itemsIndex.itemCount} items from ${itemsIndex.listCount} lists`);
+} catch {
+  console.error("No items.json.gz found - item search will be unavailable");
+}
+
+// Create MCP server
+const server = new McpServer({
+  name: "awess",
+  version: "0.3.0",
+});
+
+// Tool: Search awesome lists (unified search, top_lists, get_list)
 server.tool(
-  "get_list",
-  "Get details for a specific awesome list by repository name",
+  "search_lists",
+  "Search curated awesome lists. Returns lists sorted by relevance (if query provided) or stars.",
   {
-    repo: z.string().describe("Repository name (e.g., 'sindresorhus/awesome')"),
+    query: z.string().optional().describe("Search query (e.g., 'rust', 'machine learning')"),
+    repo: z.string().optional().describe("Exact repo lookup (e.g., 'sindresorhus/awesome')"),
+    sortBy: z.enum(["relevance", "stars", "updated"]).optional().describe("Sort order (default: 'stars', or 'relevance' if query provided)"),
+    minStars: z.number().optional().describe("Minimum star count filter"),
+    limit: z.number().optional().describe("Maximum results (default: 20)"),
   },
-  async ({ repo }) => {
-    const list = lists.find(
-      (l) => l.repo.toLowerCase() === repo.toLowerCase()
-    );
-
-    if (!list) {
+  async ({ query, repo, sortBy, minStars = 0, limit = 20 }) => {
+    // Exact repo lookup
+    if (repo) {
+      const list = lists.find(l => l.repo.toLowerCase() === repo.toLowerCase());
+      if (!list) {
+        return {
+          content: [{ type: "text", text: `List not found: ${repo}` }],
+        };
+      }
       return {
-        content: [
-          {
-            type: "text",
-            text: `List not found: ${repo}`,
-          },
-        ],
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            repo: list.repo,
+            name: list.name,
+            stars: list.stars,
+            description: list.description,
+            lastUpdated: list.pushed_at,
+            source: list.source,
+            githubUrl: `https://github.com/${list.repo}`,
+          }, null, 2),
+        }],
       };
     }
 
-    return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify(
-            {
-              repo: list.repo,
-              name: list.name,
-              stars: list.stars,
-              description: list.description,
-              lastUpdated: list.pushed_at,
-              source: list.source,
-              githubUrl: `https://github.com/${list.repo}`,
-            },
-            null,
-            2
-          ),
-        },
-      ],
-    };
-  }
-);
+    // Determine sort order
+    const effectiveSortBy = sortBy || (query ? "relevance" : "stars");
+
+    let results: any[];
+
+    if (query && effectiveSortBy === "relevance") {
+      // Search with relevance sorting
+      results = listSearch
+        .search(query)
+        .filter(r => r.stars >= minStars)
+        .slice(0, limit)
+        .map(r => ({
+          repo: r.repo,
+          name: r.name,
+          stars: r.stars,
+          description: r.description,
+          lastUpdated: r.pushed_at,
+        }));
+    } else {
+      // Filter and sort manually
+      let filtered = lists.filter(l => l.stars >= minStars);
+
+      if (query) {
+        const searchResults = new Set(listSearch.search(query).map(r => r.repo));
+        filtered = filtered.filter(l => searchResults.has(l.repo));
+      }
 
-// Tool: List top repos by stars
-server.tool(
-  "top_lists",
-  "Get top awesome lists by star count",
-  {
-    limit: z.number().optional().describe("Number of lists to return (default: 20)"),
-    category: z.string().optional().describe("Optional keyword to filter by (e.g., 'python', 'web')"),
-  },
-  async ({ limit = 20, category }) => {
-    let filtered = lists;
-
-    if (category) {
-      const categoryResults = search.search(category);
-      filtered = categoryResults.map((r) => ({
-        repo: r.repo,
-        name: r.name,
-        stars: r.stars,
-        description: r.description,
-        pushed_at: r.pushed_at,
-        source: r.source,
-      }));
-    }
+      // Sort
+      if (effectiveSortBy === "updated") {
+        filtered.sort((a, b) => (b.pushed_at || "").localeCompare(a.pushed_at || ""));
+      } else {
+        filtered.sort((a, b) => b.stars - a.stars);
+      }
 
-    const top = filtered
-      .sort((a, b) => b.stars - a.stars)
-      .slice(0, limit)
-      .map((l) => ({
+      results = filtered.slice(0, limit).map(l => ({
         repo: l.repo,
         name: l.name,
         stars: l.stars,
-        description: l.description?.slice(0, 100),
+        description: l.description,
+        lastUpdated: l.pushed_at,
       }));
+    }
 
     return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify(top, null, 2),
-        },
-      ],
-    };
-  }
-);
-
-// Tool: Stats
-server.tool(
-  "stats",
-  "Get statistics about the curated awesome lists collection",
-  {},
-  async () => {
-    const totalLists = lists.length;
-    const totalStars = lists.reduce((sum, l) => sum + l.stars, 0);
-    const avgStars = Math.round(totalStars / totalLists);
-
-    const starBrackets = {
-      "10000+": lists.filter((l) => l.stars >= 10000).length,
-      "5000-9999": lists.filter((l) => l.stars >= 5000 && l.stars < 10000)
-        .length,
-      "1000-4999": lists.filter((l) => l.stars >= 1000 && l.stars < 5000)
-        .length,
-      "500-999": lists.filter((l) => l.stars >= 500 && l.stars < 1000).length,
-      "<500": lists.filter((l) => l.stars < 500).length,
-    };
-
-    return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify(
-            {
-              totalLists,
-              totalStars,
-              avgStars,
-              starDistribution: starBrackets,
-            },
-            null,
-            2
-          ),
-        },
-      ],
+      content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
     };
   }
 );
 
-// Load items index
-let itemsIndex: ItemsIndex | null = null;
-
-try {
-  itemsIndex = await loadGzippedData<ItemsIndex>("items.json.gz");
-  console.error(`Loaded ${itemsIndex?.itemCount} items from ${itemsIndex?.listCount} lists`);
-} catch {
-  console.error("No items.json found - get_items will be unavailable");
-}
-
-// Tool: Get items from a list
-if (itemsIndex) {
+// Tool: Search items (global search with filters)
+if (itemsIndex && itemSearch) {
   server.tool(
-    "get_items",
-    "Get resources/items from an awesome list. Returns tools, libraries, and resources curated in the list.",
+    "search_items",
+    "Search tools, libraries, and resources across all awesome lists. Supports global search or filtering within a specific list.",
     {
-      repo: z.string().describe("Repository name (e.g., 'vinta/awesome-python')"),
-      category: z.string().optional().describe("Filter by category/section name"),
-      limit: z.number().optional().describe("Maximum items to return (default: 50)"),
+      query: z.string().optional().describe("Search item names/descriptions"),
+      repo: z.string().optional().describe("Limit to a specific list (e.g., 'vinta/awesome-python')"),
+      category: z.string().optional().describe("Filter by category"),
+      language: z.string().optional().describe("Filter by programming language"),
+      minStars: z.number().optional().describe("Minimum GitHub stars"),
+      sortBy: z.enum(["relevance", "stars", "updated"]).optional().describe("Sort order (default: 'stars', or 'relevance' if query provided)"),
+      limit: z.number().optional().describe("Maximum results (default: 50)"),
     },
-    async ({ repo, category, limit = 50 }) => {
-      const listEntry = itemsIndex!.lists[repo] || itemsIndex!.lists[repo.toLowerCase()];
-
-      if (!listEntry) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: `List not found: ${repo}. Use the 'search' tool to find available lists.`,
-            },
-          ],
-        };
+    async ({ query, repo, category, language, minStars = 0, sortBy, limit = 50 }) => {
+      const effectiveSortBy = sortBy || (query ? "relevance" : "stars");
+
+      let results: IndexedItem[];
+
+      if (query && effectiveSortBy === "relevance") {
+        // Search with relevance
+        results = itemSearch!.search(query).map(r => ({
+          id: r.id,
+          name: r.name,
+          url: r.url,
+          description: r.description,
+          category: r.category,
+          subcategory: r.subcategory,
+          github: r.github,
+          listRepo: r.listRepo,
+        })) as IndexedItem[];
+      } else {
+        // Start with all items or query results
+        if (query) {
+          const searchResultIds = new Set(itemSearch!.search(query).map(r => r.id));
+          results = allItems.filter(i => searchResultIds.has(i.id));
+        } else {
+          results = [...allItems];
+        }
       }
 
-      let items = listEntry.items;
+      // Apply filters
+      if (repo) {
+        const repoLower = repo.toLowerCase();
+        results = results.filter(i => i.listRepo.toLowerCase() === repoLower);
+      }
 
-      // Filter by category if provided
       if (category) {
-        const categoryLower = category.toLowerCase();
-        items = items.filter(
-          (i) =>
-            i.category.toLowerCase().includes(categoryLower) ||
-            i.subcategory?.toLowerCase().includes(categoryLower)
+        const catLower = category.toLowerCase();
+        results = results.filter(i =>
+          i.category?.toLowerCase().includes(catLower) ||
+          i.subcategory?.toLowerCase().includes(catLower)
+        );
+      }
+
+      if (language) {
+        const langLower = language.toLowerCase();
+        results = results.filter(i =>
+          i.github?.language?.toLowerCase() === langLower
         );
       }
 
-      // Apply limit
-      items = items.slice(0, limit);
+      if (minStars > 0) {
+        results = results.filter(i => (i.github?.stars || 0) >= minStars);
+      }
 
-      // Format output
-      const result = {
-        repo,
-        totalItems: listEntry.items.length,
-        returnedItems: items.length,
-        lastParsed: listEntry.lastParsed,
-        items: items.map((i) => ({
+      // Sort (if not already sorted by relevance)
+      if (effectiveSortBy === "stars") {
+        results.sort((a, b) => (b.github?.stars || 0) - (a.github?.stars || 0));
+      } else if (effectiveSortBy === "updated") {
+        results.sort((a, b) =>
+          (b.github?.pushedAt || "").localeCompare(a.github?.pushedAt || "")
+        );
+      }
+
+      // Apply limit and format
+      const limited = results.slice(0, limit);
+
+      const output = {
+        totalMatches: results.length,
+        returned: limited.length,
+        items: limited.map(i => ({
           name: i.name,
           url: i.url,
           description: i.description,
@@ -328,21 +314,92 @@ if (itemsIndex) {
           subcategory: i.subcategory,
           stars: i.github?.stars,
           language: i.github?.language,
+          lastUpdated: i.github?.pushedAt,
+          list: i.listRepo,
         })),
       };
 
       return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(result, null, 2),
-          },
-        ],
+        content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
       };
     }
   );
 }
 
+// Tool: Stats (enhanced with item statistics)
+server.tool(
+  "stats",
+  "Get statistics about the curated awesome lists collection and items",
+  {},
+  async () => {
+    const totalLists = lists.length;
+    const totalStars = lists.reduce((sum, l) => sum + l.stars, 0);
+    const avgStars = Math.round(totalStars / totalLists);
+
+    const listStarBrackets = {
+      "10000+": lists.filter(l => l.stars >= 10000).length,
+      "5000-9999": lists.filter(l => l.stars >= 5000 && l.stars < 10000).length,
+      "1000-4999": lists.filter(l => l.stars >= 1000 && l.stars < 5000).length,
+      "500-999": lists.filter(l => l.stars >= 500 && l.stars < 1000).length,
+      "<500": lists.filter(l => l.stars < 500).length,
+    };
+
+    // Item statistics
+    let itemStats: any = null;
+    if (itemsIndex && allItems.length > 0) {
+      const enrichedItems = allItems.filter(i => i.github);
+
+      // Count languages
+      const languageCounts = new Map<string, number>();
+      for (const item of enrichedItems) {
+        const lang = item.github?.language;
+        if (lang) {
+          languageCounts.set(lang, (languageCounts.get(lang) || 0) + 1);
+        }
+      }
+      const topLanguages = [...languageCounts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 10)
+        .reduce((acc, [lang, count]) => ({ ...acc, [lang]: count }), {});
+
+      // Count categories
+      const categoryCounts = new Map<string, number>();
+      for (const item of allItems) {
+        if (item.category) {
+          categoryCounts.set(item.category, (categoryCounts.get(item.category) || 0) + 1);
+        }
+      }
+      const topCategories = [...categoryCounts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 10)
+        .reduce((acc, [cat, count]) => ({ ...acc, [cat]: count }), {});
+
+      itemStats = {
+        totalItems: allItems.length,
+        enrichedItems: enrichedItems.length,
+        listsWithItems: itemsIndex.listCount,
+        topLanguages,
+        topCategories,
+      };
+    }
+
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          lists: {
+            total: totalLists,
+            totalStars,
+            avgStars,
+            starDistribution: listStarBrackets,
+          },
+          items: itemStats,
+        }, null, 2),
+      }],
+    };
+  }
+);
+
 // Start server
 const transport = new StdioServerTransport();
 await server.connect(transport);