# oss-trends-mcp

Task-driven trending-OSS recommender for AI builders, exposed as an [MCP](https://modelcontextprotocol.io) server. Ask "what OSS is trending for building X?" and get ranked open-source projects backed by live signals: GitHub star momentum, npm/PyPI download growth, and Hacker News buzz.

Awesome lists go stale in weeks; the AI tooling landscape moves in days. oss-trends-mcp ranks candidates at question time from real signals instead of hand-curated links — and separates established players from **rising newcomers** (repos younger than 18 months).

## Tools

### recommend_oss (main)
Inputs: task (what you want to build), queries (focused GitHub search terms — recommended; expanded from the task text otherwise), ecosystem (auto/npm/pypi/none), limit. Returns an established ranking plus risingNewcomers, each with a transparent score breakdown so the calling LLM can explain the "why". The LLM expands the task into search queries; the server does deterministic collection and scoring.

### search_repos
Raw GitHub repository search with normalized output.

### repo_health
Deep signals for one repository: star momentum, maintenance freshness, npm/PyPI adoption, HN buzz, and a 0-100 score.

### compare_repos
Side-by-side trend comparison of 2-6 repositories, ranked by composite score.

## Scoring (0-100)
- momentum 35 — stars gained in the last 30 days (log scale)
- maintenance 20 — push freshness decay; archived repos score 0
- adoption 20 — npm or PyPI monthly downloads plus growth bonus (last 28d vs previous 28d)
- community 15 — forks, license, topics
- buzz 10 — Hacker News stories and top score over the last 180 days

## Setup

Build and register with Claude Code:

    npm install && npm run build
    claude mcp add oss-trends -s user -- node /absolute/path/to/oss-trends-mcp/dist/index.js

Recommended: give the server a GITHUB_TOKEN. Without it GitHub allows 10 searches/min and 60 core requests/hour, so star-momentum sampling often degrades to fallback signals:

    claude mcp add oss-trends -s user -e GITHUB_TOKEN=ghp_xxx -- node /absolute/path/to/dist/index.js

Works in any MCP client (Claude Code, Cursor, etc.) via stdio.

## Limitations
- Repos above ~40k stars: the stargazers API caps at 400 pages, so recent star history is unreachable; momentum falls back to age-adjusted average velocity plus npm growth.
- Star velocity for other large repos is a sampled lower bound (last pages x 100 stars).
- npm/PyPI package matching is heuristic (repository URL match); unmatched repos simply skip adoption signals.

## Development
npm run build, npm test, npm run lint. A live end-to-end check drives the compiled server over stdio and calls recommend_oss against real APIs: see scripts/smoke.mjs.

## License
MIT