Fossick

让你的 AI Agent 搜遍整个 GitHub，寻找潜在项目。

查找库、发现宝藏、搜索代码模式，并阅读真实的生产环境代码——覆盖 2 亿多个仓库、PyPI 和 npm。

目录

• Fossick 是什么
• 示例
• 安装
• 工具
• 为什么选择 Fossick
• 常见问题
• 配置
• 开发
• 许可证

什么是 Fossick

fossick /ˈfɒsɪk/ 动词（澳大利亚／新西兰）——淘宝或翻找宝石，尤其指小规模采矿：筛查溪床和旧矿渣堆，寻找大型采矿者遗漏的宝石。

这正是这个工具的用途——只不过对象是代码。

Fossick 为你的 AI Agent 提供七种只读工具，可在整个 GitHub、PyPI 和 npm 上探查，涵盖从头到尾的完整发现流程：

1. 搜索与发现。 使用多查询相关性排序，从 2 亿多个仓库中筛选，找到那些被大型工具埋没的小而精的库，并在 PyPI 和 npm 上查找软件包。
2. 无需克隆即可深入查看任何仓库。 浏览远程仓库的目录树，并使用深度和 glob 过滤条件；读取任意分支／标签／提交中的任意文件；还能跳转到任意类、函数或类型的定义——全部通过远程 GitHub 完成，无需在本地检出。
3. 搜索整个 GitHub 上的代码模式。 在所有公开文件中进行全文、正则表达式及支持限定条件的搜索——查找某个 API 在生产环境中的_实际_用法，而不只是文档中的用法。

只要你希望 Agent 能访问全球最大的代码库，这个工具就很实用：

• 选对库。 为任何任务找到小巧、专注且积极维护的选项，而不只是最受欢迎的选项。
• 发现隐藏的宝藏。 找出星标数为 500、但按_相关性_排名高于星标数为 50,000 的成熟项目的库。
• 深入查看找到的仓库。 浏览其目录结构、读取 README、找到核心 API 的定义位置——无需 git clone。
• 查找真实代码中的用法模式。 搜索生产环境中如何调用某个 API，然后结合上下文读取匹配的文件。
• 获取灵感。 查看其他人如何组织类似项目、采用了哪些模式，以及做出了哪些权衡。
• 紧跟最新动态。 发现热门项目、刚发布的项目或生态中的新项目——不受模型训练截止时间的限制。

它不用于代码考古——例如 git blame、PR 历史或版本差异。需要这些功能时，请使用 git 和 gh。

示例

连接 Fossick 后，你可以向 Agent 提出这类请求。

发现库和软件包

• “给我找一个小巧、维护活跃的 Rust TUI 库——要比 ratatui 更新。”
• “如今大家在用什么来替代 LangChain？”
• “给我看看过去 90 天发布的热门 Python Web 框架。”
• “有什么轻量级替代方案可以在运行时进行 Pydantic 式验证？”

深入查看特定仓库

• “浏览 astral-sh/uv 的结构——crates/ 里有什么？”
• “读取 pydantic/pydantic 中的主 __init__.py。”
• “anthropics/anthropic-sdk-python 中的 Stream 类定义在哪里？”
• “modelcontextprotocol/python-sdk 的最新版本是什么时候发布的？”

查找实际项目中的代码模式

• “生产环境中的 FastAPI 应用实际上如何使用 structlog 和 asyncio 设置结构化日志？”
• “给我看看使用 tokio::select! 实现超时取消的真实示例。”
• “找一些使用 uv 构建多阶段 Python 镜像的 Dockerfile。”
• “大家如何在 Go 中调用 OpenAI API 的流式端点？”

采用依赖项之前先评估

• “requests 库还在维护吗？”
• “比较 httpx 和 aiohttp 的更新情况——最近发布日期和近期活动。”
• “到底有哪些人在用 msgspec？给我看看它在生产代码库中的真实用法。”
• “找出 polars PyPI 软件包背后的 GitHub 仓库，并查看其最近一次发布。”

安装

前置条件： uv——使用 curl -LsSf https://astral.sh/uv/install.sh | sh 安装。 然后 uvx 会按需下载并运行 Fossick。无需克隆。

Claude Code

共有三种安装范围。根据你希望 Fossick 的可用范围选择——全局、与团队共享，或仅在某个项目中供你使用。范围标志决定配置写入的位置（Claude Code MCP 范围）。

全局（推荐个人使用）

在你机器上的每个项目中均可使用。存储在 ~/.claude.json 中，仅供你的用户账户使用。

claude mcp add fossick --scope user uvx fossick-mcp

团队共享（提交到 git）

存储在项目根目录的 .mcp.json 中，并纳入版本控制。任何克隆此代码库的人都会获得相同的 MCP 服务。需要整个团队都能使用 Fossick 时，请采用此方式。

claude mcp add fossick --scope project uvx fossick-mcp

仅用于此项目（默认）

默认使用本地范围。仅在当前项目中启用，且仅供你使用。存储在 ~/.claude.json 中该项目路径下——不会提交，也不会与协作者共享。

claude mcp add fossick uvx fossick-mcp

手动安装

如果你想跳过 CLI，可以自行编写配置。无论范围如何，JSON 结构都相同——只有文件不同：

• 用户／本地范围使用 ~/.claude.json
• 项目范围使用 .mcp.json（项目根目录）

{
  "mcpServers": {
    "fossick": {
      "command": "uvx",
      "args": ["fossick-mcp"]
    }
  }
}

其他客户端

{
  "mcpServers": {
    "fossick": {
      "command": "uvx",
      "args": ["fossick-mcp"]
    }
  }
}

code --add-mcp '{"name":"fossick","command":"uvx","args":["fossick-mcp"]}'

{
  "mcpServers": {
    "fossick": {
      "command": "uvx",
      "args": ["fossick-mcp"]
    }
  }
}

{
  "mcpServers": {
    "fossick": {
      "command": "uvx",
      "args": ["fossick-mcp"]
    }
  }
}

{
  "mcpServers": {
    "fossick": {
      "type": "stdio",
      "command": "uvx",
      "args": ["fossick-mcp"]
    }
  }
}

codex mcp add fossick -- uvx fossick-mcp

[mcp_servers.fossick]
command = "uvx"
args = ["fossick-mcp"]

git clone https://github.com/Lipdog/fossick-mcp.git
cd fossick-mcp
uv sync

{
  "mcpServers": {
    "fossick": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/fossick-mcp", "fossick-mcp"]
    }
  }
}

工具

七个只读工具，按其在发现工作流中的作用分类。

查找候选项

评估候选项

搜索 GitHub 中的代码

所有工具均为只读、幂等，并且可安全地自动批准。每个响应末尾都会提供提示链式后续步骤，让 Agent 知道接下来该做什么。

为什么选择 Fossick

• 专为发现工作流打造。 工具遵循自然的使用路径：查找候选项目 → 深入了解 → 阅读 API → 查看其他人的用法。基于提示词链的后续步骤建议，可引导你的 Agent 顺利完成整个流程。
• 无需克隆即可深入查看任何公开仓库。 浏览远程仓库树，使用深度和 glob 过滤条件；读取任意分支、标签或提交中的文件；并通过真正基于 AST 的符号搜索，跳转到任何类、函数或类型的定义——所有操作都在远程 GitHub 上完成。
• 多查询搜索，排名智能。 search_repos 可在一次调用中接受多个不同表述，并采用综合相关性排名，优先考虑字面匹配，而非单纯的人气——帮你找到胜过 50,000 星老牌项目的 500 星宝藏项目。
• 从设计上节省令牌。 只有 7 个专注的工具（而非 30 多个）、输出格式为 Markdown（而非 JSON 转储）、采用 TTL 缓存、通过提示词链减少 Agent 推理轮次，并将 N 个请求合并为 1 个多查询搜索。每个工具的描述和响应都经过精简，为真正的工作留出上下文预算。
• 充分考虑速率限制。 分别跟踪 GitHub 的 Search 和 Core API 配额，配额耗尽时等待，并采用指数退避进行重试。
• gh 用户无需配置。 已完成 GitHub CLI 身份验证？无需进行任何配置。
• 与其他工具配合良好。 只读、幂等，可安全地自动批准。如果还需要操作自己的仓库（issues、PR、Actions），可将 Fossick 与 github-mcp-server 配合使用。

常见问题

配置

身份验证

Fossick 会自动解析 GitHub token：

1. GH_TOKEN、GITHUB_TOKEN 或 GITHUB_PERSONAL_ACCESS_TOKEN 环境变量
2. 通过 GitHub CLI 获取 gh auth token——如果你已经登录，则无需配置

如需显式传入 token：

{
  "mcpServers": {
    "fossick": {
      "command": "uvx",
      "args": ["fossick-mcp"],
      "env": { "GITHUB_TOKEN": "ghp_your_token_here" }
    }
  }
}

token 只需具备公共仓库读取权限（不选择任何权限范围也可以）。

速率限制

Fossick 会跟踪两个 GitHub API 配额池，并在任一配额耗尽时自动暂停。

遇到速率限制错误和暂时性错误时，重试会采用指数退避。为避免冗余 API 调用，结果会短暂缓存；对于固定到特定提交 SHA 的内容，缓存 TTL 会更长。

开发

前置条件

• Python 3.11+
• uv

设置

git clone https://github.com/Lipdog/fossick-mcp.git
cd fossick-mcp
uv sync

运行

通过 stdio 启动 MCP 服务（用于手动测试或本地 MCP 客户端配置）：

uv run fossick-mcp

测试

单元测试和注册测试——无需网络，几秒钟即可运行：

uv run pytest

实时集成测试——针对固定版本 modelcontextprotocol/[email protected] 调用真实的 GitHub：

uv run pytest -m live

构建

uv build

生成 dist/fossick_mcp-<version>.tar.gz 和对应的 wheel。

架构

有关完整的架构介绍、关键模式以及添加新工具的方法，请参阅 CLAUDE.md。

Star 历史

许可证

MIT — 尽情探索吧。