🚀 StarSeeker MCP：GitHub明星情报代理
一个强大的MCP（模型上下文协议）服务器，可帮助您从GitHub上自己的星号列表中发现相关存储库。使用 BM25关键词排名 和 Gemini语义搜索 为你的下一个项目找到最好的工具。
📸 截图
StarSeeker: Fetch and Search part (left) and Result (Right)
🚀 特性
- 语义搜索：使用Google Gemini（text-embedding-004）根据含义和上下文（而不仅仅是关键字）查找存储库。
- 混合搜索：谷歌gemini文本嵌入+BM25（当gemini嵌入不可用时，回退到BM25和基于流行度的排名融合。）
- Docker就绪：易于集装箱化部署。
- 快速性能：持久嵌入缓存和高效批处理。
🛠 MCP的文件结构
mcp_server.py：主要入口点。server.py：工具定义和MCP逻辑。search_engine.py：BM25和Gemini嵌入的核心逻辑。github_client.py：用于获取星星的GitHub API集成。config.py：配置和环境管理。
📋 先决条件
- Python 3.13+
- 紫外线 （推荐）
- GitHub个人访问令牌（用于更高的速率限制）
- Gemini API密钥（用于语义搜索功能）
⚙️ 安装和设置
- 克隆仓库:
git clone
cd Star_Seeker_mcp- 设置环境:
创建 .env 根目录中的文件：
GITHUB_TOKEN=your_github_token
GEMINI_API_KEY=your_gemini_api_key> 备注：你可以不用 GITHUB_TOKEN （GitHub API允许约60个请求/小时或最多1000个无令牌转发），但 GEMINI_API_KEY 是 必需的 用于Agent Playground和语义搜索。我使用了Gemini API的免费层。
- 安装依赖项:
uv sync🎮 快速入门：Agent Playground
体验StarSeeker的最快方式是通过集成的Agent Playground。它提供了一个可视化聊天界面（Gradio）来与您的GitHub stars进行交互。
1.启动可视化UI（推荐）
uv run agent_playground.py- 访问：打开 http://localhost:8080 在您的浏览器中。
- 特性：与双子座聊天，让它取下你的星星，然后用自然语言搜索它们。
💡 快速提示：打开UI后，您只需键入：\ github name : your_username. Find me some cool React libraries.\ 代理将自动获取您的星号（如果没有缓存）并执行语义搜索。2.启动CLI版本
如果您更喜欢终端：
uv run agent_playground.py --cli______________________________________________________________________
🔌 MCP服务器（反重力/光标/克劳德集成）
如果你想将StarSeeker用作内部工具 光标, 克劳德桌面，或 反重力，请按照以下步骤操作。
1.反重力（用反重力测试）
Antigravity通过可视化界面提供了最简单的设置体验。
- 开放反重力
- 点击 3个点 在右上角
- 选择 “MCP服务器” → “管理服务器” → “查看原始配置”
- 粘贴此配置并重新启动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"
}
}
}
}- 替换
C:\\path\\to\\Star_Seeker_mcp使用您的实际安装路径 - 将API密钥替换为实际密钥
- 重新启动反重力
- 你可以在Antigravity聊天中看到写@MCP服务器
2.VSCODE
- 在工作区文件夹中创建mcp.json文件或查找是否存在。
- 将此配置添加到mcp.json文件
{
"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"
}
}
}
}
- 单击开始按钮。
- 你可以用它
3.光标AI
- 设置 -> 光标设置 -> 主控程序.
- +添加新的MCP服务器.
- 名字:
StarSeeker, 类型:command. - 命令:
uv --directory "C:\path\to\Star_Seeker_mcp" run mcp_server.py
3.克劳德桌面
将以下内容添加到您的 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工具
fetch_stars_tool
获取给定GitHub用户名的所有星号存储库，并准备搜索索引。
- 参数:
username（必填），token（可选）
search_stars_tool
使用语义或关键字搜索在提取的存储库中搜索。
- 参数:
username（必填），query（必填）
🔌 集成
选项A：使用Docker运行
Docker镜像经过优化，仅安装核心MCP服务器依赖项（跳过Gradio）。
- 构建和启动:
docker-compose up --build -d- 访问：服务器在容器内的stdio/HTTP上运行，为您的工具做好准备。
选项B：本地运行
uv run mcp_server.py📂 数据存储和访问
服务器将提取的JSON数据和搜索嵌入存储在一个集中目录中，以避免重复并确保持久性。
文件位置
- 本地（Windows）:
explorer %USERPROFILE%\.star_seeker_mcp打开目录 - 本地（Linux/macOS）:
~/.star_seeker_mcp - Docker内部:
/root/.star_seeker_mcp（由Docker卷支持）
访问数据的终端命令
查看本地数据文件（Windows CMD）
dir %USERPROFILE%\.star_seeker_mcp查看运行Docker容器内的数据文件
docker exec -it star-seeker-mcp ls -lh /root/.star_seeker_mcp将数据文件从Docker复制到本地计算机
docker cp star-seeker-mcp:/root/.star_seeker_mcp/yourusername_stars.json .🧠 原理
- 数据收集：通过GitHub API获取回购名称、描述和主题。
- 索引:
- 使用以下命令为所有描述生成向量嵌入 text-embedding-004. - 为关键字搜索回退构建BM25索引。
- 检索:
- 使用余弦相似度进行语义匹配。 - 对于关键字搜索，它使用BM25分数和存储库流行度（星级）的排名融合。
📄 许可证
麻省理工学院