awesome-lite-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Verchiel666
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,76 @@
-# Temporary Holding Version
+# awesome-lite-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+离线检索整个 **awesome 清单生态**的 MCP 服务 + CLI。零依赖，一个 index.json 装下 9,000+ 条精选资源。
+
+> 起因：awesome（[sindresorhus/awesome](https://github.com/sindresorhus/awesome)，53 万 star）是「清单的清单」，
+> 但它的用法是「开浏览器 → 点 awesome.re → 上一页页翻」。这个项目把它变成**可检索、可离线、能被 AI 调用的索引**。
+
+## 装
+
+```bash
+npx -y awesome-lite-mcp          # 直接起 MCP 服务（stdio）
+npm i -g awesome-lite-mcp        # 或者全局装 CLI：awesome-lite search "mcp server"
+```
+
+MCP 客户端（Cursor / Claude Desktop / DSH / 自研 Agent）配置：
+
+```json
+{
+  "mcpServers": {
+    "awesomelite": { "command": "npx", "args": ["-y", "awesome-lite-mcp"] }
+  }
+}
+```
+
+## 5 个工具
+
+| 工具 | 干什么 |
+|---|---|
+| `awesome_search` | 跨清单按相关度检索（name > desc > category 加权） |
+| `awesome_lists` | 列出已索引的 12 张清单、条目数、为什么收录 |
+| `awesome_cat` | 按清单 / 分类摊开一份清单 |
+| `awesome_sync` | 从 GitHub 重新抓 README 重建索引（支持深抓分册） |
+| `awesome_stats` | 索引统计 |
+
+## CLI
+
+```bash
+awesome-lite lists
+awesome-lite search "android reverse engineering" --limit=8
+awesome-lite search "python" --list=vinta/awesome-python --all
+awesome-lite cat EbookFoundation/free-programming-books "Books / Chinese" --limit=20
+awesome-lite sync [repo...] [--force]
+awesome-lite stats
+```
+
+## 索引里有什么（随包附带，开箱即用）
+
+`index.json`：**9,317 条 / 12 张清单**，含
+
+- 总目录 `sindresorhus/awesome`（28 类）
+- `codecrafters-io/build-your-own-x`（亲手造 Redis/Git/Docker，GitHub star 第一）
+- `EbookFoundation/free-programming-books`（含 119 个语言分册；本项目默认深抓 30 个、中文优先 → 中文 379 条）
+- `vinta/awesome-python` / `sindresorhus/awesome-nodejs` / `awesome-selfhosted` / `public-apis`
+- `punkpeye/awesome-mcp-servers`（97k star）/ `wtsxDev/reverse-engineering` / `JStumpp/awesome-android`
+- `e2b-dev/awesome-ai-agents` / `Hannibal046/Awesome-LLM`
+
+## 刷新索引
+
+```bash
+AWESOME_GH_TOKEN=ghp_xxx awesome-lite sync          # 有 token：5000 次/时；无 token：60 次/时
+AWESOME_LITE_HOME=/some/writable/dir awesome-lite sync   # 数据目录（默认包目录）
+```
+
+抓取走 `api.github.com/repos/{owner}/{repo}/readme`（`Accept: application/vnd.github.raw`）——
+`raw.githubusercontent.com` 在很多网络环境（含蜂窝网络/企业网）是被墙的，这条不会。
+
+## 已知边界
+
+- 只解析 `- [名](url) - 说明` 与 markdown 表格两种条目写法；内联 HTML 卡片式的清单会漏。
+- 分册（如 free-programming-books 的 119 个语言文件）默认只抓 30 个，`--deep` 可调。
+- 清单里的项目不保证在你的平台上能用。实测：`any-cli-mcp-server` 在 Android 上把 toybox 命令的
+  合体 `--help` 解析成 0 个参数——「清单收了」≠「你机器上能跑」。
+
+## License
+
+MIT。索引内容版权归各清单原作者（awesome 主清单为 CC0-1.0）。

package/cli.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { sync, loadIndex, search, stats, loadLists } from './src/store.mjs';
+const [, , cmd = 'help', ...rest] = process.argv;
+const opt = Object.fromEntries(rest.filter(a => a.startsWith('--')).map(a => { const [k, ...v] = a.slice(2).split('='); return [k, v.join('=') || true]; }));
+const args = rest.filter(a => !a.startsWith('--'));
+const out = (s) => process.stdout.write(s + '\n');
+
+const tag = (repo) => (loadLists().find(l => l.repo === repo) || {}).tag || '';
+const line = (e) => `  ${e.name}  [${tag(e.list) || e.list}${e.category ? ' / ' + e.category : ''}]  score=${e.score ?? '-'}\n     ${e.url}\n     ${(e.desc || '').slice(0, 160)}`;
+
+if (cmd === 'sync') {
+  const idx = await sync({ force: !!opt.force, only: args.length ? args : [], log: out });
+  out(`\n索引: ${idx.entries.length} 条 / ${idx.lists.length} 清单，写入 index.json`);
+} else if (cmd === 'lists') {
+  const idx = loadIndex();
+  out(`索引时间 ${idx.builtAt || '(未建)'}，共 ${idx.entries.length} 条\n`);
+  for (const l of idx.lists) out(`${String(l.entries).padStart(5)}  ${(l.tag || '').padEnd(7)}  ${l.repo.padEnd(42)} ${l.categories} 类  ${(l.why || '')}`);
+} else if (cmd === 'cat') {
+  const idx = loadIndex();
+  const repo = args[0];
+  const cat = args[1];
+  const rows = idx.entries.filter(e => (!repo || e.list === repo) && (!cat || (e.category || '').toLowerCase().includes(cat.toLowerCase())));
+  out(`${repo || '全部'}${cat ? ' / ' + cat : ''}: ${rows.length} 条`);
+  for (const e of rows.slice(0, Number(opt.limit || 40))) out(line(e));
+} else if (cmd === 'search') {
+  const idx = loadIndex();
+  const q = args.join(' ');
+  if (!q) { out('用法: node cli.mjs search <关键词> [--limit=10] [--list=repo] [--all]'); process.exit(1); }
+  const hits = search(idx, q, { limit: Number(opt.limit || 12), list: opt.list || '', all: !!opt.all });
+  out(`「${q}」命中 ${hits.length} 条`);
+  for (const e of hits) out(line(e));
+} else if (cmd === 'stats') {
+  out(JSON.stringify(stats(loadIndex()), null, 1));
+} else {
+  out(`awesome-lite CLI
+  sync [repo...] [--force]   抓取并重建索引
+  lists                      已索引清单与条目数
+  cat <repo> [分类] [--limit] 列条目
+  search <关键词> [--list=] [--all] [--limit=]  检索
+  stats                      统计`);
+}