Metadata-Version: 2.4
Name: ossinsight-mcp
Version: 0.2.0
Summary: MCP server wrapping the OSSInsight REST API — GitHub repo analytics, collections, trending, search, compare, rankings
Author-email: GeniusTechnoMystic <hermes@nousresearch.com>
License: MIT
Project-URL: Homepage, https://github.com/GeniusTechnoMystic/ossinsight-mcp
Project-URL: Repository, https://github.com/GeniusTechnoMystic/ossinsight-mcp
Project-URL: Issues, https://github.com/GeniusTechnoMystic/ossinsight-mcp/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: httpx>=0.27.0
Dynamic: license-file

# OSSInsight MCP Server

A Model Context Protocol (MCP) server for querying GitHub repository analytics from [OSSInsight](https://ossinsight.io) (by PingCAP). Provides repo metadata, trending repos, curated collections, search, compare, and collection rankings — no API key required.

## Features

- **`ossinsight_repo`** — GitHub repo metadata: stars, forks, language, license, description
- **`ossinsight_trending`** — Trending repos by language and timeframe
- **`ossinsight_collections`** — List all 102 curated collections
- **`ossinsight_search`** — Search repos and collections by keyword
- **`ossinsight_compare`** — Side-by-side comparison of two repos
- **`ossinsight_ranking`** — Rank repos in a collection by stars, issues, or PRs

## Installation

### uv (recommended)

```bash
uvx ossinsight-mcp
```

### pip

```bash
pip install ossinsight-mcp
ossinsight-mcp
```

## Configuration

### Claude Desktop

```json
{
  "mcpServers": {
    "ossinsight-mcp": {
      "command": "uvx",
      "args": ["ossinsight-mcp"]
    }
  }
}
```

### Cursor / VS Code

```json
{
  "mcpServers": {
    "ossinsight-mcp": {
      "command": "uvx",
      "args": ["ossinsight-mcp"]
    }
  }
}
```

## Tools

| Tool | Description | Key Params |
|------|-------------|-----------|
| `ossinsight_repo` | Repo metadata — stars, forks, language, license | `owner`, `repo` (required) |
| `ossinsight_trending` | Trending repos by language/timeframe | `language`, `period` (past_24h/past_week/past_month/past_3mo) |
| `ossinsight_collections` | List all curated collections | (none) |
| `ossinsight_search` | Search repos and collections | `q` (required), `page`, `page_size`, `sort` |
| `ossinsight_compare` | Compare two repos side-by-side | `repo1`, `repo2` (required) |
| `ossinsight_ranking` | Rank repos in a collection | `collection_id` (required), `metric`, `range` |

## Examples

```python
# Get repo metadata
ossinsight_repo({"owner": "grafana", "repo": "grafana"})
# → stars: 76K, forks: 14K, language: TypeScript, license: AGPL-3.0

# What's trending in Rust this month
ossinsight_trending({"language": "rust", "period": "past_month"})

# List all collections
ossinsight_collections({})

# Compare two databases
ossinsight_compare({"repo1": "postgres/postgres", "repo2": "clickhouse/clickhouse"})

# Top repos in the AI/ML collection by stars this year
ossinsight_ranking({"collection_id": 12, "metric": "stars", "range": "year"})
```

## Data Source

Uses the [OSSInsight API](https://ossinsight.io) (`/api/mcp`).

- **Auth:** None required
- **Rate limit:** 600 requests per hour per IP
- **Data:** GH Archive (all public GitHub events since 2011)

## Development

```bash
git clone https://github.com/GeniusTechnoMystic/ossinsight-mcp.git
cd ossinsight-mcp
uv sync
uv run ossinsight-mcp
```

## License

MIT
