# 🔍 Repo Scout MCP Server

> **"The #1 rule for Vibe Coders and Software Engineers: Don't reinvent the wheel. Let AI scout existing GitHub projects before writing a single line of code!"**

A high-performance, free local **Model Context Protocol (MCP)** server that empowers AI assistants (Google Antigravity, Claude Desktop, Cursor, Claude Code) to search GitHub for existing open-source projects, libraries, and frameworks **before** you start building from scratch.

---

## 👤 Author & Credits

* **Author:** Akash Kumar Jha
* **License:** MIT License (Free & Open Source)

---

## 🚀 Why Use Repo Scout MCP?

When vibe coding or building software, developers often spend hours writing code for features or complete applications that already exist as battle-tested, high-quality open-source projects.

**Repo Scout MCP** connects your AI coding assistant directly to GitHub's search & intelligence APIs:
* 💡 **Save Hundreds of Hours:** Instantly discover existing solutions before starting a project.
* 🆓 **100% Free & Local:** No paid API subscriptions required. Runs locally via Node.js over stdio.
* ⚡ **High Performance:** Raises GitHub rate limit from 60 to **5,000 requests/hour** with a free token.
* 🛡️ **Privacy & Security:** Zero hardcoded keys or tracking. Each user supplies their own environment variables.

---

## 🛠️ Included Tools

| Tool Name | Description | Example Usage |
| :--- | :--- | :--- |
| `suggest_stack` | Provide a plain-English description of what you want to build. It runs multi-angle GitHub searches (including awesome-lists) and returns a ranked shortlist of repos to reuse. | *"I'm building a markdown note app with tags. Check if something exists."* |
| `search_repos` | Keyword, topic, and language search across GitHub sorted by stars, forks, or recency. | *"Find Node.js rate-limiting middleware sorted by stars."* |
| `get_repo_details` | Pulls a repository's full README and top-level file structure so the AI can evaluate code fit. | *"Check details for `facebook/react`."* |

---

## 📦 Quick Start & Installation

### Step 1: Clone the Repository

```bash
git clone https://github.com/YOUR_USERNAME/repo-scout-mcp.git
cd repo-scout-mcp
npm install
```

### Step 2: Get a Free GitHub Access Token (2 Minutes)

1. Go to [GitHub Settings -> Tokens](https://github.com/settings/tokens).
2. Click **Generate new token** $\rightarrow$ **Generate new token (classic)**.
3. Name it `repo-scout-mcp`.
4. **Leave all scope checkboxes unchecked** (public data search requires no permissions).
5. Click **Generate token** and copy it (looks like `ghp_xxxxxxxxxxxx`).

---

## 🔌 Connecting to your AI Assistant

### 1. Google Antigravity

1. Open Antigravity $\rightarrow$ click the **`...`** menu at top-right of agent panel.
2. Go to **MCP Servers** $\rightarrow$ **Manage MCP Servers** $\rightarrow$ **View raw config** (`mcp_config.json`).
3. Add the following entry inside `"mcpServers"`:

```json
{
  "mcpServers": {
    "repo-scout": {
      "command": "node",
      "args": ["G:\\CODE\\repo-scout-mcp\\index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_personal_access_token_here"
      }
    }
  }
}
```
*(Note: Replace `G:\\CODE\\repo-scout-mcp\\index.js` with your actual full file path, using double backslashes on Windows).*

4. Save `mcp_config.json` and refresh MCP servers (or type `/mcp` in chat).

---

### 2. Claude Desktop

Add to your `claude_desktop_config.json`:

* **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
* **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "repo-scout": {
      "command": "node",
      "args": ["/absolute/path/to/repo-scout-mcp/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_personal_access_token_here"
      }
    }
  }
}
```

---

### 3. Claude Code CLI

Run:
```bash
claude mcp add repo-scout node /absolute/path/to/repo-scout-mcp/index.js -e GITHUB_TOKEN=ghp_your_token_here
```

---

## 💬 Example Prompts to Try

Once connected, simply prompt your AI assistant:

* **Before starting a project:**
  > *"I'm planning to build a self-hosted dashboard for monitoring Docker containers. Use repo-scout to check if a great open-source project already exists."*

* **Searching for libraries:**
  > *"Use repo-scout to search for high-star TypeScript financial technical indicator packages."*

* **Evaluating a repository:**
  > *"Use repo-scout get_repo_details on `shadcn/ui` to summarize its structure."*

---

## 📄 License

Created by **Akash Kumar Jha**. Released under the [MIT License](LICENSE).