@rakeshroushan/reposcout 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rakesh Roushan
+
+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

@@ -0,0 +1,98 @@
+# reposcout
+
+LLM-driven GitHub repo discovery and ranking, exposed as a Model Context Protocol (MCP) server.
+
+When an AI coding agent needs "the best open-source library for X", it usually falls back on stale training-data recall. reposcout gives the agent a fresh, evidence-backed view of the GitHub ecosystem: it searches by intent, pulls READMEs and metadata, computes deterministic popularity / maintenance / completeness signals, and combines them with the agent's own relevance judgment into a ranked, explainable shortlist.
+
+It ships as a stdio MCP server with three composable tools, plus a companion Claude Code skill that orchestrates them.
+
+## How it works
+
+Discovery is split into three tools so the deterministic math stays server-side and the judgment stays with the LLM driving the loop:
+
+| Tool | What it does |
+|------|--------------|
+| `repo_search` | Runs several GitHub search queries built from the objective, unions and dedupes them, and returns compact records with computed `popularity_score` and `maintenance_score`. |
+| `repo_enrich` | For a shortlist, fetches the cleaned + truncated README plus completeness signals (license, homepage, description, topic count, README size). Results are cached locally. |
+| `repo_rank` | Combines four sub-scores — relevance, popularity, maintenance, completeness — into a weighted ranking. The agent supplies relevance + completeness; reposcout owns popularity + maintenance and the final math. |
+
+Scoring is deterministic: log-scaled popularity (star/fork caps), exponential-decay maintenance (180-day half-life) with an open-issues penalty. Default weights are relevance 0.4 / popularity 0.2 / maintenance 0.2 / completeness 0.2 (normalized, overridable per call). Archived repos are excluded by default.
+
+## Requirements
+
+- Node.js >= 22 (uses the built-in `node:sqlite`).
+- A GitHub token. reposcout reads `GITHUB_TOKEN` or `GH_TOKEN`; if neither is set it falls back to `gh auth token`. So if your `gh` CLI is logged in (`gh auth login`), no extra setup is needed.
+
+## Install
+
+reposcout runs as a local stdio MCP server — point any MCP client at it.
+
+### Claude Code
+
+```bash
+claude mcp add reposcout -- npx -y @rakeshroushan/reposcout
+```
+
+### Claude Desktop / Cursor / other MCP clients
+
+Add to the client's MCP config (for Claude Desktop, `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "reposcout": {
+      "command": "npx",
+      "args": ["-y", "@rakeshroushan/reposcout"],
+      "env": { "GITHUB_TOKEN": "ghp_..." }
+    }
+  }
+}
+```
+
+Omit `env` to use your `gh` CLI login instead.
+
+### From source
+
+```bash
+git clone https://github.com/Rakesh1002/reposcout
+cd reposcout
+pnpm install
+pnpm build
+```
+
+Then point the client at the built server:
+
+```json
+{
+  "mcpServers": {
+    "reposcout": {
+      "command": "node",
+      "args": ["/absolute/path/to/reposcout/dist/server.js"]
+    }
+  }
+}
+```
+
+## Using it
+
+Once connected, state an objective in plain language:
+
+> Find the best TypeScript library to generate OpenAPI types from Zod schemas — min 100 stars, actively maintained.
+
+The agent expands that into complementary GitHub queries, calls `repo_search`, triages a shortlist, calls `repo_enrich`, scores relevance + completeness from the READMEs, and calls `repo_rank` to return a ranked shortlist with one-line reasoning per repo. The companion `reposcout` Claude Code skill encodes that pipeline so you never touch raw JSON.
+
+## Development
+
+```bash
+pnpm dev        # run the server from source (tsx)
+pnpm test       # node --test over tests/*.test.ts
+pnpm typecheck  # tsc --noEmit
+pnpm lint       # biome check
+pnpm build      # tsc -> dist/
+```
+
+The cache lives at `~/.reposcout/cache.sqlite` (24h TTL).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/cache.d.ts

@@ -0,0 +1,14 @@
+export interface CacheHit<T> {
+    value: T;
+    etag?: string;
+    fetchedAt: number;
+}
+export declare const DEFAULT_CACHE_PATH: string;
+export declare class RepoCache {
+    private db;
+    constructor(path?: string);
+    get<T>(key: string): CacheHit<T> | undefined;
+    getFresh<T>(key: string, ttlMs: number, now?: number): T | undefined;
+    set(key: string, value: unknown, etag?: string, now?: number): void;
+    close(): void;
+}

package/dist/cache.js

@@ -0,0 +1,48 @@
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+export const DEFAULT_CACHE_PATH = join(homedir(), ".reposcout", "cache.sqlite");
+export class RepoCache {
+    db;
+    constructor(path = DEFAULT_CACHE_PATH) {
+        if (path !== ":memory:") {
+            mkdirSync(dirname(path), { recursive: true });
+        }
+        this.db = new DatabaseSync(path);
+        this.db.exec(`CREATE TABLE IF NOT EXISTS cache (
+         key TEXT PRIMARY KEY,
+         value TEXT NOT NULL,
+         etag TEXT,
+         fetched_at INTEGER NOT NULL
+       )`);
+    }
+    get(key) {
+        const row = this.db
+            .prepare("SELECT value, etag, fetched_at FROM cache WHERE key = ?")
+            .get(key);
+        if (!row)
+            return undefined;
+        return {
+            value: JSON.parse(row.value),
+            etag: row.etag ?? undefined,
+            fetchedAt: row.fetched_at,
+        };
+    }
+    getFresh(key, ttlMs, now = Date.now()) {
+        const hit = this.get(key);
+        if (!hit)
+            return undefined;
+        return now - hit.fetchedAt <= ttlMs ? hit.value : undefined;
+    }
+    set(key, value, etag, now = Date.now()) {
+        this.db
+            .prepare(`INSERT INTO cache (key, value, etag, fetched_at) VALUES (?, ?, ?, ?)
+         ON CONFLICT(key) DO UPDATE SET value = excluded.value, etag = excluded.etag, fetched_at = excluded.fetched_at`)
+            .run(key, JSON.stringify(value), etag ?? null, now);
+    }
+    close() {
+        this.db.close();
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAc3C,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,YAAY,EAAE,cAAc,CAAC,CAAC;AAEhF,MAAM,OAAO,SAAS;IACZ,EAAE,CAAe;IAEzB,YAAY,OAAe,kBAAkB;QAC3C,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;YACxB,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,CAAC;QACD,IAAI,CAAC,EAAE,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;QACjC,IAAI,CAAC,EAAE,CAAC,IAAI,CACV;;;;;SAKG,CACJ,CAAC;IACJ,CAAC;IAED,GAAG,CAAI,GAAW;QAChB,MAAM,GAAG,GAAG,IAAI,CAAC,EAAE;aAChB,OAAO,CAAC,yDAAyD,CAAC;aAClE,GAAG,CAAC,GAAG,CAAoB,CAAC;QAC/B,IAAI,CAAC,GAAG;YAAE,OAAO,SAAS,CAAC;QAC3B,OAAO;YACL,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAM;YACjC,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,SAAS;YAC3B,SAAS,EAAE,GAAG,CAAC,UAAU;SAC1B,CAAC;IACJ,CAAC;IAED,QAAQ,CAAI,GAAW,EAAE,KAAa,EAAE,MAAc,IAAI,CAAC,GAAG,EAAE;QAC9D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAI,GAAG,CAAC,CAAC;QAC7B,IAAI,CAAC,GAAG;YAAE,OAAO,SAAS,CAAC;QAC3B,OAAO,GAAG,GAAG,GAAG,CAAC,SAAS,IAAI,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9D,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,KAAc,EAAE,IAAa,EAAE,MAAc,IAAI,CAAC,GAAG,EAAE;QACtE,IAAI,CAAC,EAAE;aACJ,OAAO,CACN;uHAC+G,CAChH;aACA,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,IAAI,IAAI,IAAI,EAAE,GAAG,CAAC,CAAC;IACxD,CAAC;IAED,KAAK;QACH,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;IAClB,CAAC;CACF"}

package/dist/github.d.ts

@@ -0,0 +1,56 @@
+import { Octokit } from "octokit";
+import type { RepoCache } from "./cache.js";
+import type { EnrichedRepo, RepoRecord } from "./types.js";
+export interface RawRepo {
+    full_name: string;
+    html_url: string;
+    description: string | null;
+    language: string | null;
+    topics?: string[];
+    stargazers_count: number;
+    forks_count: number;
+    open_issues_count: number;
+    pushed_at: string | null;
+    created_at: string | null;
+    license: {
+        spdx_id?: string | null;
+    } | null;
+    homepage: string | null;
+    archived: boolean;
+}
+export interface SearchClient {
+    rest: {
+        search: {
+            repos: (params: {
+                q: string;
+                per_page?: number;
+                page?: number;
+                sort?: "stars" | "forks" | "updated";
+                order?: "desc" | "asc";
+            }) => Promise<{
+                data: {
+                    items: RawRepo[];
+                };
+            }>;
+        };
+    };
+}
+export declare function resolveToken(): string;
+export declare function createClient(token?: string): Octokit;
+export declare function mapSearchItem(item: RawRepo, now: Date): RepoRecord;
+export interface SearchOptions {
+    queries: string[];
+    perQueryLimit?: number;
+    totalLimit?: number;
+    excludeArchived?: boolean;
+    now: Date;
+}
+export declare function searchRepos(client: SearchClient, opts: SearchOptions): Promise<RepoRecord[]>;
+export interface EnrichOptions {
+    now: Date;
+    cache?: RepoCache;
+    cacheTtlMs?: number;
+    readmeChars?: number;
+    concurrency?: number;
+}
+export declare function enrichRepos(client: Octokit, fullNames: string[], opts: EnrichOptions): Promise<EnrichedRepo[]>;

package/dist/github.js

@@ -0,0 +1,136 @@
+import { execFileSync } from "node:child_process";
+import { Octokit } from "octokit";
+import { buildCompletenessSignals, cleanReadme } from "./readme.js";
+import { maintenanceScore, popularityScore } from "./score.js";
+const DEFAULT_PER_QUERY = 30;
+const DEFAULT_TOTAL_LIMIT = 60;
+const DEFAULT_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_README_CHARS = 5000;
+export function resolveToken() {
+    const fromEnv = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+    if (fromEnv)
+        return fromEnv;
+    try {
+        return execFileSync("gh", ["auth", "token"], { encoding: "utf8" }).trim();
+    }
+    catch {
+        throw new Error("No GitHub token: set GITHUB_TOKEN or authenticate the gh CLI (gh auth login).");
+    }
+}
+export function createClient(token = resolveToken()) {
+    return new Octokit({
+        auth: token,
+        throttle: {
+            onRateLimit: (_retryAfter, _options, _octokit, retryCount) => retryCount < 2,
+            onSecondaryRateLimit: (_retryAfter, _options, _octokit, retryCount) => retryCount < 2,
+        },
+    });
+}
+const normLicense = (spdx) => spdx && spdx !== "NOASSERTION" ? spdx : null;
+export function mapSearchItem(item, now) {
+    const stars = item.stargazers_count ?? 0;
+    const forks = item.forks_count ?? 0;
+    const openIssues = item.open_issues_count ?? 0;
+    const pushedAt = item.pushed_at ?? new Date(0).toISOString();
+    return {
+        full_name: item.full_name,
+        html_url: item.html_url,
+        description: item.description ?? null,
+        language: item.language ?? null,
+        topics: item.topics ?? [],
+        stars,
+        forks,
+        open_issues: openIssues,
+        pushed_at: pushedAt,
+        created_at: item.created_at ?? pushedAt,
+        license: normLicense(item.license?.spdx_id),
+        homepage: item.homepage?.trim() ? item.homepage : null,
+        archived: Boolean(item.archived),
+        popularity_score: popularityScore(stars, forks),
+        maintenance_score: maintenanceScore({ pushed_at: pushedAt, archived: Boolean(item.archived), open_issues: openIssues, stars }, now),
+    };
+}
+export async function searchRepos(client, opts) {
+    const perPage = Math.min(opts.perQueryLimit ?? DEFAULT_PER_QUERY, 100);
+    const excludeArchived = opts.excludeArchived ?? true;
+    const byName = new Map();
+    for (const q of opts.queries) {
+        const res = await client.rest.search.repos({
+            q,
+            per_page: perPage,
+            sort: "stars",
+            order: "desc",
+        });
+        for (const item of res.data.items) {
+            const record = mapSearchItem(item, opts.now);
+            if (excludeArchived && record.archived)
+                continue;
+            if (!byName.has(record.full_name))
+                byName.set(record.full_name, record);
+        }
+    }
+    return [...byName.values()]
+        .sort((a, b) => b.stars - a.stars)
+        .slice(0, opts.totalLimit ?? DEFAULT_TOTAL_LIMIT);
+}
+async function mapWithConcurrency(items, limit, fn) {
+    const out = new Array(items.length);
+    let cursor = 0;
+    const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        while (cursor < items.length) {
+            const index = cursor++;
+            out[index] = await fn(items[index]);
+        }
+    });
+    await Promise.all(workers);
+    return out;
+}
+async function fetchReadmeRaw(client, owner, repo) {
+    try {
+        const res = await client.rest.repos.getReadme({
+            owner,
+            repo,
+            mediaType: { format: "raw" },
+        });
+        return res.data;
+    }
+    catch {
+        return "";
+    }
+}
+async function enrichOne(client, fullName, opts) {
+    const ttl = opts.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+    const cacheKey = `repo:${fullName}`;
+    const cached = opts.cache?.getFresh(cacheKey, ttl);
+    if (cached)
+        return cached;
+    const [owner, repo] = fullName.split("/");
+    if (!owner || !repo)
+        return null;
+    try {
+        const meta = await client.rest.repos.get({ owner, repo });
+        const record = mapSearchItem(meta.data, opts.now);
+        const readmeText = cleanReadme(await fetchReadmeRaw(client, owner, repo), opts.readmeChars ?? DEFAULT_README_CHARS);
+        const enriched = {
+            ...record,
+            readme_excerpt: readmeText,
+            completeness_signals: buildCompletenessSignals({
+                description: record.description,
+                license: record.license,
+                homepage: record.homepage,
+                topics: record.topics,
+                readmeText,
+            }),
+        };
+        opts.cache?.set(cacheKey, enriched);
+        return enriched;
+    }
+    catch {
+        return null;
+    }
+}
+export async function enrichRepos(client, fullNames, opts) {
+    const results = await mapWithConcurrency(fullNames, opts.concurrency ?? 5, (name) => enrichOne(client, name, opts));
+    return results.filter((r) => r !== null);
+}
+//# sourceMappingURL=github.js.map

package/dist/github.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"github.js","sourceRoot":"","sources":["../src/github.ts"],"names":[],"mappings":"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"}

package/dist/readme.d.ts

@@ -0,0 +1,11 @@
+import type { CompletenessSignals } from "./types.js";
+export declare function cleanReadme(raw: string, maxChars?: number): string;
+export declare function readmeLengthBucket(len: number): CompletenessSignals["readme_length_bucket"];
+export interface CompletenessInput {
+    description: string | null;
+    license: string | null;
+    homepage: string | null;
+    topics: string[];
+    readmeText: string;
+}
+export declare function buildCompletenessSignals(input: CompletenessInput): CompletenessSignals;

package/dist/readme.js

@@ -0,0 +1,38 @@
+const TRUNCATE_MARKER = " [truncated]";
+export function cleanReadme(raw, maxChars = 5000) {
+    let text = raw
+        .replace(/<!--[\s\S]*?-->/g, "")
+        .replace(/!\[[^\]]*\]\([^)]*\)/g, "")
+        .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+        .replace(/<[^>]+>/g, "")
+        .replace(/[ \t]+/g, " ")
+        .replace(/ *\n */g, "\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+    if (text.length > maxChars) {
+        const slice = text.slice(0, maxChars);
+        const lastBreak = Math.max(slice.lastIndexOf(" "), slice.lastIndexOf("\n"));
+        text = `${slice.slice(0, lastBreak > 0 ? lastBreak : maxChars).trimEnd()}${TRUNCATE_MARKER}`;
+    }
+    return text;
+}
+export function readmeLengthBucket(len) {
+    if (len === 0)
+        return "none";
+    if (len < 400)
+        return "thin";
+    if (len < 2000)
+        return "ok";
+    return "rich";
+}
+export function buildCompletenessSignals(input) {
+    return {
+        has_license: Boolean(input.license),
+        has_homepage: Boolean(input.homepage?.trim()),
+        has_description: Boolean(input.description?.trim()),
+        topic_count: input.topics.length,
+        readme_length: input.readmeText.length,
+        readme_length_bucket: readmeLengthBucket(input.readmeText.length),
+    };
+}
+//# sourceMappingURL=readme.js.map

package/dist/readme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readme.js","sourceRoot":"","sources":["../src/readme.ts"],"names":[],"mappings":"AAEA,MAAM,eAAe,GAAG,cAAc,CAAC;AAEvC,MAAM,UAAU,WAAW,CAAC,GAAW,EAAE,QAAQ,GAAG,IAAI;IACtD,IAAI,IAAI,GAAG,GAAG;SACX,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC;SAC/B,OAAO,CAAC,uBAAuB,EAAE,EAAE,CAAC;SACpC,OAAO,CAAC,wBAAwB,EAAE,IAAI,CAAC;SACvC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SACvB,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC;SACxB,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC;SAC1B,IAAI,EAAE,CAAC;IAEV,IAAI,IAAI,CAAC,MAAM,GAAG,QAAQ,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;QACtC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC;QAC5E,IAAI,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,GAAG,eAAe,EAAE,CAAC;IAC/F,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,IAAI,GAAG,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC;IAC7B,IAAI,GAAG,GAAG,GAAG;QAAE,OAAO,MAAM,CAAC;IAC7B,IAAI,GAAG,GAAG,IAAI;QAAE,OAAO,IAAI,CAAC;IAC5B,OAAO,MAAM,CAAC;AAChB,CAAC;AAUD,MAAM,UAAU,wBAAwB,CAAC,KAAwB;IAC/D,OAAO;QACL,WAAW,EAAE,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC;QACnC,YAAY,EAAE,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC;QAC7C,eAAe,EAAE,OAAO,CAAC,KAAK,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC;QACnD,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM;QAChC,aAAa,EAAE,KAAK,CAAC,UAAU,CAAC,MAAM;QACtC,oBAAoB,EAAE,kBAAkB,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC;KAClE,CAAC;AACJ,CAAC"}

package/dist/score.d.ts

@@ -0,0 +1,16 @@
+import { type HardFilters, type RankCandidate, type RankResult, type Weights } from "./types.js";
+export declare function popularityScore(stars: number, forks?: number): number;
+export interface MaintenanceInput {
+    pushed_at: string;
+    archived: boolean;
+    open_issues?: number;
+    stars?: number;
+}
+export declare function maintenanceScore(input: MaintenanceInput, now: Date): number;
+export declare function compositeScore(candidate: RankCandidate, weights?: Weights): number;
+export interface RankOptions {
+    weights?: Weights;
+    hardFilters?: HardFilters;
+    now: Date;
+}
+export declare function rankRepos(candidates: RankCandidate[], options: RankOptions): RankResult;

package/dist/score.js

@@ -0,0 +1,86 @@
+import { DEFAULT_WEIGHTS, } from "./types.js";
+const STAR_CAP = 50000;
+const FORK_CAP = 10000;
+const FORK_BONUS = 0.05;
+const MAINTENANCE_HALF_LIFE_DAYS = 180;
+const ISSUE_PENALTY_MAX = 0.15;
+const clamp01 = (n) => Math.max(0, Math.min(1, n));
+const logScale = (value, cap) => Math.log10(value + 1) / Math.log10(cap + 1);
+export function popularityScore(stars, forks = 0) {
+    const base = logScale(stars, STAR_CAP);
+    const bonus = FORK_BONUS * logScale(forks, FORK_CAP);
+    return clamp01(base + bonus);
+}
+export function maintenanceScore(input, now) {
+    if (input.archived)
+        return 0;
+    const days = (now.getTime() - new Date(input.pushed_at).getTime()) / 86400000;
+    const recency = Math.exp(-Math.max(0, days) / MAINTENANCE_HALF_LIFE_DAYS);
+    let penalty = 0;
+    if (input.stars && input.stars > 0 && input.open_issues !== undefined) {
+        penalty = ISSUE_PENALTY_MAX * Math.min(1, input.open_issues / input.stars);
+    }
+    return clamp01(recency - penalty);
+}
+function normalizeWeights(weights) {
+    const w = { ...DEFAULT_WEIGHTS, ...weights };
+    const sum = w.relevance + w.popularity + w.maintenance + w.completeness;
+    if (sum <= 0)
+        return { ...DEFAULT_WEIGHTS };
+    return {
+        relevance: w.relevance / sum,
+        popularity: w.popularity / sum,
+        maintenance: w.maintenance / sum,
+        completeness: w.completeness / sum,
+    };
+}
+export function compositeScore(candidate, weights) {
+    const w = normalizeWeights(weights);
+    return (w.relevance * candidate.relevance_score +
+        w.popularity * candidate.popularity_score +
+        w.maintenance * candidate.maintenance_score +
+        w.completeness * candidate.completeness_score);
+}
+function failedFilter(candidate, filters, now) {
+    if (filters.min_stars !== undefined && (candidate.stars ?? 0) < filters.min_stars) {
+        return `stars ${candidate.stars ?? 0} < min_stars ${filters.min_stars}`;
+    }
+    if (filters.language !== undefined &&
+        (candidate.language ?? "").toLowerCase() !== filters.language.toLowerCase()) {
+        return `language ${candidate.language ?? "none"} != ${filters.language}`;
+    }
+    if (filters.require_license && candidate.has_license !== true) {
+        return "no license";
+    }
+    if (filters.max_days_since_push !== undefined && candidate.pushed_at) {
+        const days = (now.getTime() - new Date(candidate.pushed_at).getTime()) / 86400000;
+        if (days > filters.max_days_since_push) {
+            return `pushed ${Math.round(days)}d ago > ${filters.max_days_since_push}d`;
+        }
+    }
+    return null;
+}
+export function rankRepos(candidates, options) {
+    const weights = normalizeWeights(options.weights);
+    const filters = options.hardFilters ?? {};
+    const dropped = [];
+    const kept = [];
+    for (const candidate of candidates) {
+        const reason = failedFilter(candidate, filters, options.now);
+        if (reason) {
+            dropped.push({ full_name: candidate.full_name, reason });
+        }
+        else {
+            kept.push(candidate);
+        }
+    }
+    const ranked = kept
+        .map((candidate) => ({
+        ...candidate,
+        composite: compositeScore(candidate, weights),
+    }))
+        .sort((a, b) => b.composite - a.composite)
+        .map((candidate, index) => ({ ...candidate, rank: index + 1 }));
+    return { ranked, dropped, weights };
+}
+//# sourceMappingURL=score.js.map

package/dist/score.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"score.js","sourceRoot":"","sources":["../src/score.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/server.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { RepoCache } from "./cache.js";
+import { createClient, enrichRepos, searchRepos } from "./github.js";
+import { rankRepos } from "./score.js";
+import { HardFiltersSchema, RankCandidateSchema, WeightsSchema } from "./types.js";
+const cache = new RepoCache();
+let client;
+const getClient = () => {
+    if (!client)
+        client = createClient();
+    return client;
+};
+const json = (value) => ({
+    content: [{ type: "text", text: JSON.stringify(value) }],
+});
+const fail = (err) => ({
+    isError: true,
+    content: [{ type: "text", text: err instanceof Error ? err.message : String(err) }],
+});
+const server = new McpServer({ name: "reposcout", version: "0.1.0" });
+server.registerTool("repo_search", {
+    title: "Search GitHub repos",
+    description: "Run one or more GitHub repo search queries (use qualifiers like language:, stars:>N, topic:, pushed:>YYYY-MM-DD, archived:false), union and dedupe the results, and return compact records with computed popularity_score and maintenance_score. Craft 3-6 complementary queries from the user's objective.",
+    inputSchema: {
+        queries: z.array(z.string().min(1)).min(1).describe("GitHub search query strings"),
+        per_query_limit: z.number().int().min(1).max(100).optional(),
+        total_limit: z.number().int().min(1).max(200).optional(),
+        exclude_archived: z.boolean().optional(),
+    },
+}, async (args) => {
+    try {
+        const records = await searchRepos(getClient(), {
+            queries: args.queries,
+            perQueryLimit: args.per_query_limit,
+            totalLimit: args.total_limit,
+            excludeArchived: args.exclude_archived,
+            now: new Date(),
+        });
+        return json({ count: records.length, repos: records });
+    }
+    catch (err) {
+        return fail(err);
+    }
+});
+server.registerTool("repo_enrich", {
+    title: "Enrich GitHub repos",
+    description: "For a shortlist of repos (owner/name), fetch the README (cleaned, truncated) plus extended metadata and deterministic completeness signals (license, homepage, description, topic count, README size). Results are cached. Use this on the ~10-20 most promising candidates from repo_search before judging relevance and completeness.",
+    inputSchema: {
+        full_names: z.array(z.string().min(1)).min(1).describe("Repos as owner/name"),
+        readme_chars: z.number().int().min(500).max(20000).optional(),
+    },
+}, async (args) => {
+    try {
+        const repos = await enrichRepos(getClient(), args.full_names, {
+            now: new Date(),
+            cache,
+            readmeChars: args.readme_chars,
+        });
+        return json({ count: repos.length, repos });
+    }
+    catch (err) {
+        return fail(err);
+    }
+});
+server.registerTool("repo_rank", {
+    title: "Rank repos by weighted score",
+    description: "Combine the four sub-scores into a final ranking. popularity_score and maintenance_score come from repo_search/repo_enrich; relevance_score and completeness_score are your 0-1 judgments. Weights default to relevance 0.4, popularity 0.2, maintenance 0.2, completeness 0.2 and are normalized. Optional hard_filters drop candidates before ranking.",
+    inputSchema: {
+        candidates: z.array(RankCandidateSchema).min(1),
+        weights: WeightsSchema.optional(),
+        hard_filters: HardFiltersSchema.optional(),
+    },
+}, async (args) => {
+    try {
+        const result = rankRepos(args.candidates, {
+            weights: args.weights,
+            hardFilters: args.hard_filters,
+            now: new Date(),
+        });
+        return json(result);
+    }
+    catch (err) {
+        return fail(err);
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    process.stderr.write(`reposcout fatal: ${err instanceof Error ? err.stack : String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,249 @@
+import { z } from "zod";
+export declare const WeightsSchema: z.ZodObject<{
+    relevance: z.ZodOptional<z.ZodNumber>;
+    popularity: z.ZodOptional<z.ZodNumber>;
+    maintenance: z.ZodOptional<z.ZodNumber>;
+    completeness: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    relevance?: number | undefined;
+    popularity?: number | undefined;
+    maintenance?: number | undefined;
+    completeness?: number | undefined;
+}, {
+    relevance?: number | undefined;
+    popularity?: number | undefined;
+    maintenance?: number | undefined;
+    completeness?: number | undefined;
+}>;
+export type Weights = z.infer<typeof WeightsSchema>;
+export declare const DEFAULT_WEIGHTS: Required<Weights>;
+export declare const HardFiltersSchema: z.ZodObject<{
+    min_stars: z.ZodOptional<z.ZodNumber>;
+    language: z.ZodOptional<z.ZodString>;
+    max_days_since_push: z.ZodOptional<z.ZodNumber>;
+    require_license: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    min_stars?: number | undefined;
+    language?: string | undefined;
+    max_days_since_push?: number | undefined;
+    require_license?: boolean | undefined;
+}, {
+    min_stars?: number | undefined;
+    language?: string | undefined;
+    max_days_since_push?: number | undefined;
+    require_license?: boolean | undefined;
+}>;
+export type HardFilters = z.infer<typeof HardFiltersSchema>;
+export declare const CompletenessSignalsSchema: z.ZodObject<{
+    has_license: z.ZodBoolean;
+    has_homepage: z.ZodBoolean;
+    has_description: z.ZodBoolean;
+    topic_count: z.ZodNumber;
+    readme_length: z.ZodNumber;
+    readme_length_bucket: z.ZodEnum<["none", "thin", "ok", "rich"]>;
+}, "strip", z.ZodTypeAny, {
+    has_license: boolean;
+    has_homepage: boolean;
+    has_description: boolean;
+    topic_count: number;
+    readme_length: number;
+    readme_length_bucket: "none" | "thin" | "ok" | "rich";
+}, {
+    has_license: boolean;
+    has_homepage: boolean;
+    has_description: boolean;
+    topic_count: number;
+    readme_length: number;
+    readme_length_bucket: "none" | "thin" | "ok" | "rich";
+}>;
+export type CompletenessSignals = z.infer<typeof CompletenessSignalsSchema>;
+export declare const RepoRecordSchema: z.ZodObject<{
+    full_name: z.ZodString;
+    html_url: z.ZodString;
+    description: z.ZodNullable<z.ZodString>;
+    language: z.ZodNullable<z.ZodString>;
+    topics: z.ZodArray<z.ZodString, "many">;
+    stars: z.ZodNumber;
+    forks: z.ZodNumber;
+    open_issues: z.ZodNumber;
+    pushed_at: z.ZodString;
+    created_at: z.ZodString;
+    license: z.ZodNullable<z.ZodString>;
+    homepage: z.ZodNullable<z.ZodString>;
+    archived: z.ZodBoolean;
+    popularity_score: z.ZodNumber;
+    maintenance_score: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    language: string | null;
+    full_name: string;
+    html_url: string;
+    description: string | null;
+    topics: string[];
+    stars: number;
+    forks: number;
+    open_issues: number;
+    pushed_at: string;
+    created_at: string;
+    license: string | null;
+    homepage: string | null;
+    archived: boolean;
+    popularity_score: number;
+    maintenance_score: number;
+}, {
+    language: string | null;
+    full_name: string;
+    html_url: string;
+    description: string | null;
+    topics: string[];
+    stars: number;
+    forks: number;
+    open_issues: number;
+    pushed_at: string;
+    created_at: string;
+    license: string | null;
+    homepage: string | null;
+    archived: boolean;
+    popularity_score: number;
+    maintenance_score: number;
+}>;
+export type RepoRecord = z.infer<typeof RepoRecordSchema>;
+export declare const EnrichedRepoSchema: z.ZodObject<{
+    full_name: z.ZodString;
+    html_url: z.ZodString;
+    description: z.ZodNullable<z.ZodString>;
+    language: z.ZodNullable<z.ZodString>;
+    topics: z.ZodArray<z.ZodString, "many">;
+    stars: z.ZodNumber;
+    forks: z.ZodNumber;
+    open_issues: z.ZodNumber;
+    pushed_at: z.ZodString;
+    created_at: z.ZodString;
+    license: z.ZodNullable<z.ZodString>;
+    homepage: z.ZodNullable<z.ZodString>;
+    archived: z.ZodBoolean;
+    popularity_score: z.ZodNumber;
+    maintenance_score: z.ZodNumber;
+} & {
+    readme_excerpt: z.ZodString;
+    completeness_signals: z.ZodObject<{
+        has_license: z.ZodBoolean;
+        has_homepage: z.ZodBoolean;
+        has_description: z.ZodBoolean;
+        topic_count: z.ZodNumber;
+        readme_length: z.ZodNumber;
+        readme_length_bucket: z.ZodEnum<["none", "thin", "ok", "rich"]>;
+    }, "strip", z.ZodTypeAny, {
+        has_license: boolean;
+        has_homepage: boolean;
+        has_description: boolean;
+        topic_count: number;
+        readme_length: number;
+        readme_length_bucket: "none" | "thin" | "ok" | "rich";
+    }, {
+        has_license: boolean;
+        has_homepage: boolean;
+        has_description: boolean;
+        topic_count: number;
+        readme_length: number;
+        readme_length_bucket: "none" | "thin" | "ok" | "rich";
+    }>;
+}, "strip", z.ZodTypeAny, {
+    language: string | null;
+    full_name: string;
+    html_url: string;
+    description: string | null;
+    topics: string[];
+    stars: number;
+    forks: number;
+    open_issues: number;
+    pushed_at: string;
+    created_at: string;
+    license: string | null;
+    homepage: string | null;
+    archived: boolean;
+    popularity_score: number;
+    maintenance_score: number;
+    readme_excerpt: string;
+    completeness_signals: {
+        has_license: boolean;
+        has_homepage: boolean;
+        has_description: boolean;
+        topic_count: number;
+        readme_length: number;
+        readme_length_bucket: "none" | "thin" | "ok" | "rich";
+    };
+}, {
+    language: string | null;
+    full_name: string;
+    html_url: string;
+    description: string | null;
+    topics: string[];
+    stars: number;
+    forks: number;
+    open_issues: number;
+    pushed_at: string;
+    created_at: string;
+    license: string | null;
+    homepage: string | null;
+    archived: boolean;
+    popularity_score: number;
+    maintenance_score: number;
+    readme_excerpt: string;
+    completeness_signals: {
+        has_license: boolean;
+        has_homepage: boolean;
+        has_description: boolean;
+        topic_count: number;
+        readme_length: number;
+        readme_length_bucket: "none" | "thin" | "ok" | "rich";
+    };
+}>;
+export type EnrichedRepo = z.infer<typeof EnrichedRepoSchema>;
+export declare const RankCandidateSchema: z.ZodObject<{
+    full_name: z.ZodString;
+    popularity_score: z.ZodNumber;
+    maintenance_score: z.ZodNumber;
+    relevance_score: z.ZodNumber;
+    completeness_score: z.ZodNumber;
+    stars: z.ZodOptional<z.ZodNumber>;
+    language: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    pushed_at: z.ZodOptional<z.ZodString>;
+    has_license: z.ZodOptional<z.ZodBoolean>;
+    note: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    full_name: string;
+    popularity_score: number;
+    maintenance_score: number;
+    relevance_score: number;
+    completeness_score: number;
+    language?: string | null | undefined;
+    has_license?: boolean | undefined;
+    stars?: number | undefined;
+    pushed_at?: string | undefined;
+    note?: string | undefined;
+}, {
+    full_name: string;
+    popularity_score: number;
+    maintenance_score: number;
+    relevance_score: number;
+    completeness_score: number;
+    language?: string | null | undefined;
+    has_license?: boolean | undefined;
+    stars?: number | undefined;
+    pushed_at?: string | undefined;
+    note?: string | undefined;
+}>;
+export type RankCandidate = z.infer<typeof RankCandidateSchema>;
+export interface RankedRepo extends RankCandidate {
+    rank: number;
+    composite: number;
+}
+export interface RankResult {
+    ranked: RankedRepo[];
+    dropped: {
+        full_name: string;
+        reason: string;
+    }[];
+    weights: Required<Weights>;
+}
+export declare const SCORE_KEYS: readonly ["relevance", "popularity", "maintenance", "completeness"];

package/dist/types.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+export const WeightsSchema = z
+    .object({
+    relevance: z.number().min(0),
+    popularity: z.number().min(0),
+    maintenance: z.number().min(0),
+    completeness: z.number().min(0),
+})
+    .partial();
+export const DEFAULT_WEIGHTS = {
+    relevance: 0.4,
+    popularity: 0.2,
+    maintenance: 0.2,
+    completeness: 0.2,
+};
+export const HardFiltersSchema = z
+    .object({
+    min_stars: z.number().int().min(0).optional(),
+    language: z.string().optional(),
+    max_days_since_push: z.number().int().min(0).optional(),
+    require_license: z.boolean().optional(),
+})
+    .strict();
+export const CompletenessSignalsSchema = z.object({
+    has_license: z.boolean(),
+    has_homepage: z.boolean(),
+    has_description: z.boolean(),
+    topic_count: z.number().int().min(0),
+    readme_length: z.number().int().min(0),
+    readme_length_bucket: z.enum(["none", "thin", "ok", "rich"]),
+});
+export const RepoRecordSchema = z.object({
+    full_name: z.string(),
+    html_url: z.string(),
+    description: z.string().nullable(),
+    language: z.string().nullable(),
+    topics: z.array(z.string()),
+    stars: z.number().int().min(0),
+    forks: z.number().int().min(0),
+    open_issues: z.number().int().min(0),
+    pushed_at: z.string(),
+    created_at: z.string(),
+    license: z.string().nullable(),
+    homepage: z.string().nullable(),
+    archived: z.boolean(),
+    popularity_score: z.number().min(0).max(1),
+    maintenance_score: z.number().min(0).max(1),
+});
+export const EnrichedRepoSchema = RepoRecordSchema.extend({
+    readme_excerpt: z.string(),
+    completeness_signals: CompletenessSignalsSchema,
+});
+export const RankCandidateSchema = z.object({
+    full_name: z.string(),
+    popularity_score: z.number().min(0).max(1),
+    maintenance_score: z.number().min(0).max(1),
+    relevance_score: z.number().min(0).max(1),
+    completeness_score: z.number().min(0).max(1),
+    stars: z.number().int().min(0).optional(),
+    language: z.string().nullable().optional(),
+    pushed_at: z.string().optional(),
+    has_license: z.boolean().optional(),
+    note: z.string().optional(),
+});
+export const SCORE_KEYS = ["relevance", "popularity", "maintenance", "completeness"];
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@rakeshroushan/reposcout",
+  "version": "0.1.0",
+  "description": "LLM-driven GitHub repo discovery and ranking, exposed as an MCP server",
+  "type": "module",
+  "mcpName": "io.github.rakesh1002/reposcout",
+  "license": "MIT",
+  "author": "Rakesh Roushan",
+  "homepage": "https://github.com/Rakesh1002/reposcout#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rakesh1002/reposcout.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Rakesh1002/reposcout/issues"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "model-context-protocol",
+    "mcp-server",
+    "github",
+    "repository-search",
+    "repo-discovery",
+    "ranking",
+    "claude",
+    "ai-agent"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "reposcout": "dist/server.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/server.ts",
+    "start": "node dist/server.js",
+    "test": "node --import tsx --test tests/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "biome check src tests",
+    "format": "biome format --write src tests"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "octokit": "^4.1.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/node": "^24.0.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}