awess 0.1.0

package/README.md

@@ -0,0 +1,142 @@
+# Awesome Search Services
+
+MCP server for searching 631+ curated awesome lists and 164,000+ tools/libraries within them.
+
+## Features
+
+- **Search lists** - Find awesome lists by keyword (e.g., "machine learning", "rust")
+- **Browse items** - Get tools/libraries from within any list
+- **GitHub metadata** - Star counts, languages, last updated
+- **Zero setup** - Data loaded from CDN, no cloning required
+
+## Quick Start
+
+### Claude Code
+
+```bash
+claude mcp add awess -- bunx awess
+```
+
+### Claude Desktop
+
+Add to your config file:
+
+```json
+{
+  "mcpServers": {
+    "awess": {
+      "command": "bunx",
+      "args": ["awess"]
+    }
+  }
+}
+```
+
+**Config locations:**
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
+
+### Run directly
+
+```bash
+bunx awess
+```
+
+### Test with MCP Inspector
+
+```bash
+npx @modelcontextprotocol/inspector bunx awess
+```
+
+## Development
+
+```bash
+git clone https://github.com/arimxyer/ass.git
+cd ass
+bun install
+bun run start
+```
+
+## Tools
+
+### search
+
+Search curated awesome lists by keyword. Returns matching lists sorted by relevance and stars.
+
+**Parameters:**
+- `query` (required): Search query (e.g., "rust", "machine learning", "react")
+- `limit` (optional): Maximum results to return (default: 10)
+- `minStars` (optional): Minimum star count filter (default: 0)
+
+**Example:**
+```json
+{
+  "query": "machine learning",
+  "limit": 5,
+  "minStars": 1000
+}
+```
+
+### get_list
+
+Get details for a specific awesome list by repository name.
+
+**Parameters:**
+- `repo` (required): Repository name (e.g., "sindresorhus/awesome")
+
+**Example:**
+```json
+{
+  "repo": "sindresorhus/awesome"
+}
+```
+
+### top_lists
+
+Get top awesome lists by star count.
+
+**Parameters:**
+- `limit` (optional): Number of lists to return (default: 20)
+- `category` (optional): Optional keyword to filter by (e.g., "python", "web")
+
+**Example:**
+```json
+{
+  "limit": 10,
+  "category": "python"
+}
+```
+
+### stats
+
+Get statistics about the curated awesome lists collection.
+
+**Parameters:** None
+
+**Example:**
+```json
+{}
+```
+
+### get_items
+
+Get resources/items from an awesome list.
+
+**Parameters:**
+- `repo` (required): Repository name (e.g., "vinta/awesome-python")
+- `category` (optional): Filter by category/section name
+- `limit` (optional): Maximum items to return (default: 50)
+
+**Example:**
+```json
+{
+  "repo": "vinta/awesome-python",
+  "category": "Web Frameworks",
+  "limit": 10
+}
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "awess",
+  "version": "0.1.0",
+  "description": "MCP server for searching curated awesome lists and their contents",
+  "type": "module",
+  "main": "src/index.ts",
+  "bin": {
+    "awess": "src/index.ts"
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/*.test.ts"
+  ],
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "dev": "bun run --watch src/index.ts"
+  },
+  "keywords": [
+    "mcp",
+    "awesome-lists",
+    "search",
+    "claude",
+    "model-context-protocol"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/arimxyer/ass.git"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "dependencies": {
+    "@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/enricher.ts

@@ -0,0 +1,73 @@
+// 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;
+}
+
+export async function batchEnrichItems(items: Item[]): Promise<Item[]> {
+  const token = process.env.GITHUB_TOKEN;
+  if (!token) {
+    console.warn("No GITHUB_TOKEN - skipping enrichment");
+    return items;
+  }
+
+  const octokit = new Octokit({ auth: token });
+
+  // Extract unique GitHub repos
+  const repoMap = new Map<string, Item[]>();
+  for (const item of items) {
+    const repo = extractGitHubRepo(item.url);
+    if (repo) {
+      if (!repoMap.has(repo)) repoMap.set(repo, []);
+      repoMap.get(repo)!.push(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;
+  for (let i = 0; i < repos.length; i += batchSize) {
+    const batch = repos.slice(i, i + batchSize);
+
+    const query = `
+      query {
+        ${batch.map((repo, idx) => {
+          const [owner, name] = repo.split("/");
+          return `repo${idx}: repository(owner: "${owner}", name: "${name}") {
+            stargazerCount
+            primaryLanguage { name }
+            pushedAt
+          }`;
+        }).join("\n")}
+      }
+    `;
+
+    try {
+      const result: any = await octokit.graphql(query);
+
+      for (let j = 0; j < batch.length; j++) {
+        const data = result[`repo${j}`];
+        if (data) {
+          const itemsForRepo = repoMap.get(batch[j])!;
+          for (const item of itemsForRepo) {
+            item.github = {
+              stars: data.stargazerCount,
+              language: data.primaryLanguage?.name || null,
+              pushedAt: data.pushedAt,
+            };
+            item.lastEnriched = new Date().toISOString();
+          }
+        }
+      }
+    } catch (error: any) {
+      console.error(`Error enriching batch ${i}-${i + batchSize}:`, error.message);
+    }
+  }
+
+  return items;
+}

package/src/index.ts

@@ -0,0 +1,304 @@
+#!/usr/bin/env bun
+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";
+
+interface AwesomeList {
+  repo: string;
+  name: string;
+  stars: number;
+  description: string;
+  pushed_at?: string;
+  source: string;
+}
+
+// Data URL - GitHub raw (no file size limits, 5 min cache)
+const DATA_URL = "https://raw.githubusercontent.com/arimxyer/ass/main/data";
+
+// Load data from GitHub, fallback to local for development
+async function loadData<T>(filename: string): Promise<T> {
+  // Try remote first
+  try {
+    const res = await fetch(`${DATA_URL}/${filename}`);
+    if (res.ok) {
+      return res.json();
+    }
+  } catch {
+    // Remote failed, try local
+  }
+
+  // Fallback to local file
+  const localPath = new URL(`../data/${filename}`, import.meta.url);
+  return Bun.file(localPath).json();
+}
+
+// Load curated data
+const lists: AwesomeList[] = await loadData("lists.json");
+
+// Initialize search index
+const search = new MiniSearch<AwesomeList>({
+  fields: ["name", "repo", "description"],
+  storeFields: ["repo", "name", "stars", "description", "pushed_at", "source"],
+  searchOptions: {
+    boost: { name: 2, repo: 1.5, description: 1 },
+    fuzzy: 0.2,
+    prefix: true,
+  },
+});
+
+// Index all lists with repo as id
+search.addAll(lists.map((list, i) => ({ id: i, ...list })));
+
+// Create MCP server
+const server = new McpServer({
+  name: "ass",
+  version: "0.1.0",
+});
+
+// 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,
+      }));
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(results, null, 2),
+        },
+      ],
+    };
+  }
+);
+
+// Tool: Get list details
+server.tool(
+  "get_list",
+  "Get details for a specific awesome list by repository name",
+  {
+    repo: z.string().describe("Repository name (e.g., 'sindresorhus/awesome')"),
+  },
+  async ({ 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: 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
+          ),
+        },
+      ],
+    };
+  }
+);
+
+// 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,
+      }));
+    }
+
+    const top = filtered
+      .sort((a, b) => b.stars - a.stars)
+      .slice(0, limit)
+      .map((l) => ({
+        repo: l.repo,
+        name: l.name,
+        stars: l.stars,
+        description: l.description?.slice(0, 100),
+      }));
+
+    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
+          ),
+        },
+      ],
+    };
+  }
+);
+
+// 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) {
+  server.tool(
+    "get_items",
+    "Get resources/items from an awesome list. Returns tools, libraries, and resources curated in the 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)"),
+    },
+    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.`,
+            },
+          ],
+        };
+      }
+
+      let items = listEntry.items;
+
+      // 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)
+        );
+      }
+
+      // Apply limit
+      items = items.slice(0, limit);
+
+      // Format output
+      const result = {
+        repo,
+        totalItems: listEntry.items.length,
+        returnedItems: items.length,
+        lastParsed: listEntry.lastParsed,
+        items: items.map((i) => ({
+          name: i.name,
+          url: i.url,
+          description: i.description,
+          category: i.category,
+          subcategory: i.subcategory,
+          stars: i.github?.stars,
+          language: i.github?.language,
+        })),
+      };
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result, null, 2),
+          },
+        ],
+      };
+    }
+  );
+}
+
+// Start server
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/parser.ts

@@ -0,0 +1,68 @@
+// src/parser.ts
+import { fromMarkdown } from "mdast-util-from-markdown";
+import type { Item } from "./types";
+
+export function parseReadme(markdown: string): Item[] {
+  const tree = fromMarkdown(markdown);
+  const items: Item[] = [];
+  let currentCategory = "";
+  let currentSubcategory = "";
+
+  function walk(node: any) {
+    // Track h2 headings as categories
+    if (node.type === "heading" && node.depth === 2) {
+      const text = node.children?.find((c: any) => c.type === "text")?.value || "";
+      currentCategory = text;
+      currentSubcategory = "";
+    }
+
+    // Track h3 headings as subcategories
+    if (node.type === "heading" && node.depth === 3) {
+      const text = node.children?.find((c: any) => c.type === "text")?.value || "";
+      currentSubcategory = text;
+    }
+
+    // Extract list items with links
+    if (node.type === "listItem" && currentCategory) {
+      const paragraph = node.children?.find((c: any) => c.type === "paragraph");
+      if (paragraph) {
+        const link = paragraph.children?.find((c: any) => c.type === "link");
+        if (link) {
+          const name = link.children?.find((c: any) => c.type === "text")?.value || "";
+          const url = link.url || "";
+
+          // Get description (text after the link)
+          const linkIndex = paragraph.children.indexOf(link);
+          const afterLink = paragraph.children.slice(linkIndex + 1);
+          const description = afterLink
+            .filter((c: any) => c.type === "text")
+            .map((c: any) => c.value)
+            .join("")
+            .replace(/^\s*[-–—]\s*/, "")
+            .trim();
+
+          // Skip anchor links and empty names
+          if (name && url && !url.startsWith("#")) {
+            items.push({
+              name,
+              url,
+              description,
+              category: currentCategory,
+              ...(currentSubcategory && { subcategory: currentSubcategory }),
+            });
+          }
+        }
+      }
+    }
+
+    // Recurse into children
+    if (node.children) {
+      for (const child of node.children) {
+        walk(child);
+      }
+    }
+  }
+
+  walk(tree);
+  return items;
+}

package/src/types.ts

@@ -0,0 +1,28 @@
+// src/types.ts
+
+export interface Item {
+  name: string;
+  url: string;
+  description: string;
+  category: string;
+  subcategory?: string;
+  lastEnriched?: string;
+  github?: {
+    stars: number;
+    language: string | null;
+    pushedAt: string;
+  };
+}
+
+export interface ListEntry {
+  lastParsed: string;
+  pushedAt: string;
+  items: Item[];
+}
+
+export interface ItemsIndex {
+  generatedAt: string;
+  listCount: number;
+  itemCount: number;
+  lists: Record<string, ListEntry>;
+}