Awesome Awesome

English | 中文

Discover and rank libraries from awesome lists — MCP server + Skill.

awesome-awesome helps you pick libraries for a specific technology stack. Give it a tech and a category (e.g. "vue" + "icon"), and it will:

1. Find the matching awesome-list(s)
2. Locate the relevant section
3. Collect every GitHub repo under that section
4. Rank them by stars → last-update → forks → watchers (archived projects excluded)
5. Present a table for you to choose from

It's a state-machine: you (or your AI client) make repeated discover calls, picking an awesome-list, then a section, until you get a ranked candidate list.

Install

Prerequisites

• Node.js 20+ (or Bun 1.2+)
• A GitHub Personal Access Token with public_repo scope — generate one here

For AI clients (MCP)

Add to your MCP client config (e.g., Claude Code's mcp.json):

{
  "mcpServers": {
    "awesome-awesome": {
      "command": "npx",
      "args": ["-y", "github:awesome-awesome/awesome-awesome/packages/mcp"],
      "env": { "GITHUB_TOKEN": "ghp_your_token_here" }
    }
  }
}

Then install the Skill so your AI knows how to drive the tools:

# Ask your AI client to call the install_skill tool, or run manually:
GITHUB_TOKEN=ghp_xxx npx -y github:awesome-awesome/awesome-awesome/packages/mcp --install-skill

For humans (direct)

git clone https://github.com/awesome-awesome/awesome-awesome
cd awesome-awesome
bun install

Usage

Once configured, just ask your AI client naturally:

"Find me a Vue icon library"

The Skill will drive the discover tool, ask you to pick from any ambiguous choices, and return a ranked table.

Tools

Tool	Purpose
discover	Main state-machine entry — finds candidates or asks for choices
list_sections	Inspect an awesome-list's sections manually
get_repo_details	Deep stats on one repo (for final comparison)
install_skill	Copy the Skill files to your local skills directory

Development

bun install
bun test                       # unit tests
GITHUB_TOKEN=ghp_xxx bun test:integration
bun run lint

See docs/superpowers/specs/2026-07-21-awesome-awesome-design.md for the full design and docs/superpowers/plans/2026-07-21-mvp.md for the build plan.

License

MIT — see LICENSE.