awess 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "awess",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "MCP server for searching curated awesome lists and their contents",
   "type": "module",
   "main": "src/index.ts",
@@ -34,7 +34,6 @@
     "@modelcontextprotocol/sdk": "^1.0.0",
     "mdast-util-from-markdown": "^2.0.2",
     "minisearch": "^7.2.0",
-    "octokit": "^5.0.5",
     "zod": "^4.3.5"
   }
 }

package/src/diff.ts

@@ -0,0 +1,42 @@
+import type { Item, DiffResult } from "./types";
+
+export function diffItems(oldItems: Item[], newItems: Item[]): DiffResult {
+  const oldByUrl = new Map(oldItems.map(i => [i.url, i]));
+  const newByUrl = new Map(newItems.map(i => [i.url, i]));
+
+  const added: Item[] = [];
+  const removed: Item[] = [];
+  const unchanged: Item[] = [];
+  const updated: Item[] = [];
+
+  // Check new items against old
+  for (const newItem of newItems) {
+    const oldItem = oldByUrl.get(newItem.url);
+    if (!oldItem) {
+      added.push(newItem);
+    } else if (oldItem.name === newItem.name && oldItem.description === newItem.description) {
+      // Unchanged - preserve enrichment data from old item
+      unchanged.push({
+        ...newItem,
+        github: oldItem.github,
+        lastEnriched: oldItem.lastEnriched,
+      });
+    } else {
+      // Updated - preserve enrichment data, use new metadata
+      updated.push({
+        ...newItem,
+        github: oldItem.github,
+        lastEnriched: oldItem.lastEnriched,
+      });
+    }
+  }
+
+  // Find removed items
+  for (const oldItem of oldItems) {
+    if (!newByUrl.has(oldItem.url)) {
+      removed.push(oldItem);
+    }
+  }
+
+  return { added, removed, unchanged, updated };
+}

package/src/enricher.ts

@@ -1,10 +1,29 @@
 // src/enricher.ts
-import { Octokit } from "octokit";
 import type { Item } from "./types";
 
 export function extractGitHubRepo(url: string): string | null {
   const match = url.match(/github\.com\/([^\/]+\/[^\/]+)/);
-  return match ? match[1].replace(/\.git$/, "") : null;
+  if (!match) return null;
+
+  // Clean up repo name: remove .git, #readme, query params, etc.
+  let repo = match[1]
+    .replace(/\.git$/, "")
+    .replace(/#.*$/, "")
+    .replace(/\?.*$/, "");
+
+  // Skip non-repo paths like "topics/awesome", "sponsors/foo"
+  const invalidPrefixes = ["topics", "sponsors", "orgs", "settings", "marketplace"];
+  if (invalidPrefixes.some(p => repo.startsWith(p + "/"))) {
+    return null;
+  }
+
+  return repo;
+}
+
+// Sleep helper with jitter
+function sleep(ms: number, jitter = 0.2): Promise<void> {
+  const jitterMs = ms * jitter * (Math.random() - 0.5) * 2;
+  return new Promise(resolve => setTimeout(resolve, ms + jitterMs));
 }
 
 export async function batchEnrichItems(items: Item[]): Promise<Item[]> {
@@ -14,8 +33,6 @@ export async function batchEnrichItems(items: Item[]): Promise<Item[]> {
     return items;
   }
 
-  const octokit = new Octokit({ auth: token });
-
   // Extract unique GitHub repos
   const repoMap = new Map<string, Item[]>();
   for (const item of items) {
@@ -29,13 +46,26 @@ export async function batchEnrichItems(items: Item[]): Promise<Item[]> {
   const repos = Array.from(repoMap.keys());
   console.log(`Enriching ${repos.length} unique repos...`);
 
-  // Batch query using GraphQL (100 at a time)
-  const batchSize = 100;
+  // Tuned for GitHub's secondary rate limits
+  const batchSize = 50;        // Smaller batches = lower query cost
+  const baseDelayMs = 500;     // Base delay between batches
+  let currentDelay = baseDelayMs;
+  let consecutiveErrors = 0;
+
   for (let i = 0; i < repos.length; i += batchSize) {
     const batch = repos.slice(i, i + batchSize);
+    const batchNum = Math.floor(i / batchSize) + 1;
+    const totalBatches = Math.ceil(repos.length / batchSize);
+
+    // Add delay between batches (except first)
+    if (i > 0) {
+      await sleep(currentDelay);
+    }
 
+    // Include rateLimit in query to monitor usage
     const query = `
       query {
+        rateLimit { cost remaining resetAt }
         ${batch.map((repo, idx) => {
           const [owner, name] = repo.split("/");
           return `repo${idx}: repository(owner: "${owner}", name: "${name}") {
@@ -48,8 +78,55 @@ export async function batchEnrichItems(items: Item[]): Promise<Item[]> {
     `;
 
     try {
-      const result: any = await octokit.graphql(query);
+      // Use fetch instead of octokit.graphql to handle partial results
+      const response = await fetch("https://api.github.com/graphql", {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ query }),
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+      }
+
+      const json: any = await response.json();
+
+      // Check for complete failure (errors but no data)
+      if (json.errors && !json.data) {
+        throw new Error(json.errors[0]?.message || "GraphQL query failed");
+      }
+
+      // Log any partial errors (repos that don't exist, etc.)
+      if (json.errors) {
+        const failedRepos = json.errors
+          .filter((e: any) => e.path?.[0]?.startsWith("repo"))
+          .map((e: any) => batch[parseInt(e.path[0].slice(4))])
+          .filter(Boolean);
+        if (failedRepos.length > 0) {
+          console.log(`  [${batchNum}/${totalBatches}] ${failedRepos.length} repos not found`);
+        }
+      }
+
+      const result = json.data;
+
+      // Log rate limit status periodically
+      const rl = result.rateLimit;
+      if (batchNum % 10 === 0 || rl?.remaining < 100) {
+        console.log(`  [${batchNum}/${totalBatches}] Rate limit: ${rl?.remaining} remaining, cost: ${rl?.cost}`);
+      } else {
+        process.stdout.write(`  [${batchNum}/${totalBatches}]\r`);
+      }
 
+      // If running low on points, slow down
+      if (rl?.remaining < 500) {
+        currentDelay = Math.min(currentDelay * 1.5, 5000);
+        console.log(`  ⚠️ Low rate limit (${rl.remaining}), increasing delay to ${currentDelay}ms`);
+      }
+
+      // Process results - now handles partial data correctly
       for (let j = 0; j < batch.length; j++) {
         const data = result[`repo${j}`];
         if (data) {
@@ -64,10 +141,115 @@ export async function batchEnrichItems(items: Item[]): Promise<Item[]> {
           }
         }
       }
+
+      // Reset on success
+      consecutiveErrors = 0;
+      currentDelay = Math.max(currentDelay * 0.9, baseDelayMs); // Gradually speed up
+
     } catch (error: any) {
-      console.error(`Error enriching batch ${i}-${i + batchSize}:`, error.message);
+      consecutiveErrors++;
+
+      // Check for secondary rate limit
+      if (error.message?.includes("SecondaryRateLimit") || error.message?.includes("403")) {
+        // Exponential backoff with jitter
+        const backoffMs = Math.min(baseDelayMs * Math.pow(2, consecutiveErrors), 60000);
+        console.log(`  ⚠️ Secondary rate limit hit, backing off for ${backoffMs}ms...`);
+        await sleep(backoffMs, 0.3);
+        currentDelay = backoffMs; // Keep the higher delay
+        i -= batchSize; // Retry this batch
+        continue;
+      }
+
+      // Log other errors but continue
+      console.error(`  Error batch ${batchNum}: ${error.message?.slice(0, 100)}`);
+
+      // If too many consecutive errors, slow down
+      if (consecutiveErrors >= 3) {
+        currentDelay = Math.min(currentDelay * 2, 10000);
+        console.log(`  Multiple errors, slowing to ${currentDelay}ms`);
+      }
     }
   }
 
+  console.log(""); // Clear the \r line
   return items;
 }
+
+export async function batchQueryListRepos(
+  repos: string[]
+): Promise<Map<string, { pushedAt: string } | null>> {
+  const results = new Map<string, { pushedAt: string } | null>();
+
+  const token = process.env.GITHUB_TOKEN;
+  if (!token) {
+    console.warn("No GITHUB_TOKEN - skipping list repo query");
+    return results;
+  }
+
+  const BATCH_SIZE = 50;
+
+  for (let i = 0; i < repos.length; i += BATCH_SIZE) {
+    const batch = repos.slice(i, i + BATCH_SIZE);
+    const batchNum = Math.floor(i / BATCH_SIZE) + 1;
+    const totalBatches = Math.ceil(repos.length / BATCH_SIZE);
+    process.stdout.write(`  [${batchNum}/${totalBatches}]\r`);
+
+    // Build GraphQL query for this batch
+    const repoQueries = batch.map((repo, idx) => {
+      const [owner, name] = repo.split("/");
+      return `repo${idx}: repository(owner: "${owner}", name: "${name}") {
+        pushedAt
+      }`;
+    });
+
+    const query = `query { ${repoQueries.join("\n")} }`;
+
+    try {
+      const response = await fetch("https://api.github.com/graphql", {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ query }),
+      });
+
+      if (!response.ok) {
+        console.error(`  Error batch ${batchNum}: HTTP ${response.status}`);
+        for (const repo of batch) {
+          results.set(repo, null);
+        }
+        continue;
+      }
+
+      const json = await response.json();
+
+      if (json.errors && !json.data) {
+        console.error(`  Error batch ${batchNum}:`, json.errors[0]?.message);
+        // Mark all repos in batch as null
+        for (const repo of batch) {
+          results.set(repo, null);
+        }
+        continue;
+      }
+
+      // Extract results
+      batch.forEach((repo, idx) => {
+        const data = json.data?.[`repo${idx}`];
+        if (data?.pushedAt) {
+          results.set(repo, { pushedAt: data.pushedAt });
+        } else {
+          results.set(repo, null);
+        }
+      });
+    } catch (error: any) {
+      console.error(`  Error batch ${batchNum}:`, error.message);
+      for (const repo of batch) {
+        results.set(repo, null);
+      }
+    }
+  }
+
+  console.log(); // newline after progress
+  return results;
+}

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,14 +14,30 @@ interface AwesomeList {
   source: string;
 }
 
-// Data URL - GitHub raw (no file size limits, 5 min cache)
-const DATA_URL = "https://raw.githubusercontent.com/arimxyer/ass/main/data";
+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";
 
-// Load data from GitHub, fallback to local for development
+// Load data from CDN, fallback to local for development
 async function loadData<T>(filename: string): Promise<T> {
-  // Try remote first
+  // Try jsDelivr first (faster global CDN)
+  try {
+    const res = await fetch(`${JSDELIVR_URL}/${filename}`);
+    if (res.ok) {
+      return res.json();
+    }
+  } catch {
+    // jsDelivr failed, try GitHub raw
+  }
+
+  // Try GitHub raw as fallback
   try {
-    const res = await fetch(`${DATA_URL}/${filename}`);
+    const res = await fetch(`${GITHUB_RAW_URL}/${filename}`);
     if (res.ok) {
       return res.json();
     }
@@ -34,11 +50,44 @@ async function loadData<T>(filename: string): Promise<T> {
   return Bun.file(localPath).json();
 }
 
+// Load gzipped data from CDN, fallback to local
+async function loadGzippedData<T>(filename: string): Promise<T> {
+  // Try jsDelivr first
+  try {
+    const res = await fetch(`${JSDELIVR_URL}/${filename}`);
+    if (res.ok) {
+      const compressed = new Uint8Array(await res.arrayBuffer());
+      const decompressed = Bun.gunzipSync(compressed);
+      return JSON.parse(new TextDecoder().decode(decompressed));
+    }
+  } catch {
+    // jsDelivr failed, try GitHub raw
+  }
+
+  // Try GitHub raw as fallback
+  try {
+    const res = await fetch(`${GITHUB_RAW_URL}/${filename}`);
+    if (res.ok) {
+      const compressed = new Uint8Array(await res.arrayBuffer());
+      const decompressed = Bun.gunzipSync(compressed);
+      return JSON.parse(new TextDecoder().decode(decompressed));
+    }
+  } catch {
+    // Remote failed, try local
+  }
+
+  // Fallback to local file
+  const localPath = new URL(`../data/${filename}`, import.meta.url);
+  const compressed = new Uint8Array(await Bun.file(localPath).arrayBuffer());
+  const decompressed = Bun.gunzipSync(compressed);
+  return JSON.parse(new TextDecoder().decode(decompressed));
+}
+
 // 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: {
@@ -48,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");
 
-// 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,
-      }));
-    }
+    let results: any[];
 
-    const top = filtered
-      .sort((a, b) => b.stars - a.stars)
-      .slice(0, limit)
-      .map((l) => ({
+    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));
+      }
+
+      // Sort
+      if (effectiveSortBy === "updated") {
+        filtered.sort((a, b) => (b.pushed_at || "").localeCompare(a.pushed_at || ""));
+      } else {
+        filtered.sort((a, b) => b.stars - a.stars);
+      }
+
+      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 loadData<ItemsIndex>("items.json");
-  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()];
+    async ({ query, repo, category, language, minStars = 0, sortBy, limit = 50 }) => {
+      const effectiveSortBy = sortBy || (query ? "relevance" : "stars");
 
-      if (!listEntry) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: `List not found: ${repo}. Use the 'search' tool to find available lists.`,
-            },
-          ],
-        };
+      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)
         );
       }
 
-      // Apply limit
-      items = items.slice(0, limit);
+      if (language) {
+        const langLower = language.toLowerCase();
+        results = results.filter(i =>
+          i.github?.language?.toLowerCase() === langLower
+        );
+      }
 
-      // Format output
-      const result = {
-        repo,
-        totalItems: listEntry.items.length,
-        returnedItems: items.length,
-        lastParsed: listEntry.lastParsed,
-        items: items.map((i) => ({
+      if (minStars > 0) {
+        results = results.filter(i => (i.github?.stars || 0) >= minStars);
+      }
+
+      // 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,
@@ -284,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);

package/src/types.ts

@@ -26,3 +26,10 @@ export interface ItemsIndex {
   itemCount: number;
   lists: Record<string, ListEntry>;
 }
+
+export interface DiffResult {
+  added: Item[];
+  removed: Item[];
+  unchanged: Item[];
+  updated: Item[];
+}