# awesome-awesome

**English** | [中文](./README_ZH.md)

> Discover and rank libraries from [awesome lists](https://github.com/sindresorhus/awesome) — 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](https://github.com/settings/tokens)

### For AI clients (MCP)

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

```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)

```bash
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

```bash
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](LICENSE).