# @hublens/mcp-server

MCP (Model Context Protocol) server for [HubLens](https://hublens.dev) — query trending open-source projects and AI-generated summaries from Claude, Cursor, and other MCP-compatible AI tools.

HubLens automatically detects trending OSS on GitHub and Hacker News daily, then generates EN/ZH summaries, categories, and scoring via Vertex AI (Gemini). This MCP server wraps the [HubLens Public REST API](https://hublens.dev/en/api) so any AI agent can ground its OSS recommendations in fresh, structured, multi-day data.

## Install

```bash
# Claude Code
claude mcp add hublens -- npx -y @hublens/mcp-server
```

For Claude Desktop or other clients, add to your MCP config:

```json
{
  "mcpServers": {
    "hublens": {
      "command": "npx",
      "args": ["-y", "@hublens/mcp-server"]
    }
  }
}
```

No API key required. The server calls public, cached endpoints rate-limited to 60 req/hr per IP.

## Tools

### `hublens_trending`

Today's trending OSS projects ranked by the HubLens score.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `limit` | number (1–50) | 10 | Number of results |
| `category` | string | — | Filter by category (e.g. `AI`, `DevTools`) |
| `source` | string | — | Filter by source (`github` or `hn`) |

### `hublens_search`

Search the full HubLens archive of every tracked OSS.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `q` | string | — | Text search on slug / title |
| `limit` | number (1–100) | 20 | Results per page |
| `offset` | number | 0 | Pagination offset |
| `category` | string | — | Category filter |
| `source` | string | — | Source filter |

### `hublens_article`

Fetch full article details (EN + ZH summaries, use cases, highlights, tags, stars, category, score) by slug.

| Parameter | Type | Description |
|---|---|---|
| `slug` | string | Project slug, e.g. `facebook-react` |

## Example prompts

- "What AI OSS projects are trending today?" → `hublens_trending(category: "AI")`
- "Find me Rust-based vector databases tracked by HubLens." → `hublens_search(q: "vector")`
- "Summarize the HubLens writeup for langchain." → `hublens_article(slug: "langchain-ai-langchain")`

## Data source

This server is a thin wrapper around the HubLens REST API (`https://hublens.dev/api/v1/*`). No local state, no credentials. See the [API spec](https://hublens.dev/en/api) for endpoint details.

## License

MIT © HubLens