使用说明

🚀 StarSeeker MCP: GitHub Stars Intelligence Agent

A powerful MCP (Model Context Protocol) server that helps you discover relevant repositories from your own starred list on GitHub. It uses BM25 keyword ranking and Gemini Semantic Search to find the best tools for your next project.

📸 Screenshots

StarSeeker: Fetch and Search part (left) and Result (Right)

🚀 Features

Semantic Search: Find repositories based on meaning and context, not just keywords, using Google Gemini (gemini-embedding-001).
Hybrid Search: Google gemini text embedding + BM25( Fallback to BM25 and popularity-based rank fusion when gemini embedding isn't available.)
Docker Ready: Easy containerized deployment.
Fast Performance: Persistent embedding cache and efficient batching.

🛠 File Structure for MCP

mcp_server.py: Main entry point.
server.py: Tool definitions and MCP logic.
search_engine.py: Core logic for BM25 and Gemini embeddings.
github_client.py: GitHub API integration for fetching stars.
config.py: Configuration and environment management.

📋 Prerequisites

Python 3.13+
uv (recommended)
GitHub Personal Access Token (for higher rate limits)
Gemini API Key (for semantic search capabilities)

⚙️ Installation & Setup

Clone the repository:

git clone <repository-url>
cd Star_Seeker_mcp

Set up Environment: Create a .env file in the root directory:
```
GITHUB_TOKEN=your_github_token
GEMINI_API_KEY=your_gemini_api_key
```
Note: You can run without a GITHUB_TOKEN (GitHub API allows ~60 requests/hr or up to 1000 repos without a token), but a GEMINI_API_KEY is required for the Agent Playground and semantic search. I used free tier of Gemini API.
Install Dependencies:
```
uv sync
```

🚀 Quick Start: One-Command Launch

The fastest way to run the server anywhere. No clone, no virtualenv setup:

uvx --from git+https://github.com/HikmetCTK/Star_Seeker_mcp star-seeker-mcp

uvx (part of uv) builds the package in a throwaway environment, runs the star-seeker-mcp console script, and leaves nothing behind. Set GEMINI_API_KEY and GITHUB_TOKEN in the environment to enable semantic search and higher GitHub rate limits; without them the server still starts and falls back to BM25 keyword search.

Alternative launch commands

# From an existing clone
uv sync
uv run mcp_server.py

# Or via the installed console script
uv run star-seeker-mcp

🎮 Agent Playground

A Gradio chat UI for interacting with your GitHub stars interactively.

1. Launch the Visual UI (Recommended)

uv run agent_playground.py

Access: Open http://localhost:8080 in your browser.
Features: Chat with Gemini, ask it to fetch your stars, and then search through them using natural language.

💡 Quick Tip: Once the UI is open, you can simply type:
github name : your_username. Find me some cool React libraries.
The agent will automatically fetch your stars (if not cached) and perform a semantic search.

2. Launch the CLI Version

If you prefer the terminal:

uv run agent_playground.py --cli

🔌 MCP Server (Integration for Antigravity/Cursor/Claude)

If you want to use StarSeeker as a tool inside Cursor, Claude Desktop, or Antigravity, follow these steps.

1. Antigravity (tested with Antigravity)

Antigravity provides the easiest setup experience with a visual interface.

Open Antigravity
Click the 3 dots in the top right corner
Select "MCP Servers" → "Manage Servers" → "View Raw Config"
Paste this configuration and restart Antigravity :

{
  "mcpServers": {
    "star-seeker-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\Star_Seeker_mcp",
        "run",
        "mcp_server.py"
      ],
      "env": {
        "GEMINI_API_KEY": "your_key",
        "GITHUB_TOKEN": "your_token"
      }
    }
  }
}

Replace C:\\path\\to\\Star_Seeker_mcp with your actual installation path
Replace the API keys with your actual keys
Restart Antigravity
You can see writing @MCP Server in Antigravity chat

2.VSCODE

Create mcp.json file in workspace folder or find if it exists.
Add this configuration to mcp.json file

{
  "mcpServers": {
    "github-stars-seeker": {
      "command": "uv",
      "args": [
        "--directory",
        "c:path\\to\\Star_Seeker_mcp",
        "run",
        "mcp_server.py"
      ],
      "env": {
        "GITHUB_TOKEN": "your_github_token",
        "GEMINI_API_KEY": "your_gemini_api_key"
      }
    }
  }
}

click start button .
You can use it

3. Cursor AI

Settings -> Cursor Settings -> MCP.
+ Add New MCP Server.
Name: StarSeeker, Type: command.
Command: uv --directory "C:\path\to\Star_Seeker_mcp" run mcp_server.py

3. Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "star-seeker-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\Star_Seeker_mcp",
        "run",
        "mcp_server.py"
      ],
      "env": {
        "GITHUB_TOKEN": "your_token",
        "GEMINI_API_KEY": "your_key"
      }
    }
  }
}

🛠 MCP Tools

`fetch_stars_tool`

Fetches all starred repositories for a given GitHub username and prepares the search index.

Args: username (required), token (optional)

`search_stars_tool`

Search through the fetched repositories using semantic or keyword search.

Args: username (required), query (required)

🔌 Integrations

Option A: Running with Docker

The Docker image is optimized to only install the core MCP server dependencies (skipping Gradio).

Build and Start:
```
docker-compose up --build -d
```
Access: The server runs on stdio/HTTP inside the container, ready for your tools.

Option B: Running Locally

uv run mcp_server.py

📂 Data Storage & Access

The server stores fetched JSON data and search embeddings in a centralized directory to avoid duplicates and ensure persistence.

File Locations

Local (Windows): explorer %USERPROFILE%\.star_seeker_mcp to open the directory
Local (Linux/macOS): ~/.star_seeker_mcp
Inside Docker: /root/.star_seeker_mcp (backed by a Docker volume)

Terminal Commands to Access Data

View Local Data Files (Windows CMD)

dir %USERPROFILE%\.star_seeker_mcp

View Data Files Inside Running Docker Container

docker exec -it star-seeker-mcp ls -lh /root/.star_seeker_mcp

Copy a Data File from Docker to Local Machine

docker cp star-seeker-mcp:/root/.star_seeker_mcp/yourusername_stars.json .

🧠 How it Works

Data Collection: Fetches repo names, descriptions, and topics via GitHub API.
Indexing:
- Generates vector embeddings for all descriptions using gemini-embedding-001.
- Builds a BM25 index for keyword search fallback.
Retrieval:
- Uses Cosine Similarity for semantic matches.
- For keyword search, it uses a rank fusion of BM25 scores and repository popularity (stars).

📄 License

MIT