Harvest

harvest-mcp

用通俗英语描述主题 → 12 位专家并行检索 Hugging Face + GitHub → 约 30 秒后输出覆盖度评分训练包 JSON。

无需 API 密钥。无需 Bridge。无需账户。连接到任意 MCP 主机后即可开箱即用——内部不含 LLM；由你的 Agent 负责思考。

Harvest 是一款训练数据侦察工具：你用通俗英语描述想要训练的内容（ “图像分类”“医疗问答”），12 位领域专家—— 代码、数学、科学、语言、视觉、音频、医疗、法律、知识、安全、情感、系统—— 各自使用精心整理的查询，扫描 Hugging Face 数据集和 GitHub 仓库。本地混合器 随后会将命中结果组合成一个均衡且带有覆盖度评分的训练库包 （flare-harvest-library v1 JSON），你可以将其交给任意训练流水线。

安装

npx github:The-Warl0ck/harvest-mcp

或者将其添加到 Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "harvest": {
      "command": "npx",
      "args": ["github:The-Warl0ck/harvest-mcp"]
    }
  }
}

如需更高的速率限制，可添加可选令牌：

{
  "mcpServers": {
    "harvest": {
      "command": "npx",
      "args": ["github:The-Warl0ck/harvest-mcp"],
      "env": {
        "HF_TOKEN": "hf_...",
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

要求：Node.js ≥ 20。

示例会话

你： 给我找一些用于小型视觉语言模型的训练数据

harvest.search { "topic": "vision language instruction tuning" } → 约 40 条结果：LLaVA-NeXT 数据、Cauldron、DOCCI、LLaVA 仓库……再加上 12 位专家的全域扫描，拓宽覆盖范围（代码、数学、安全……）

harvest.compose { "goal": "small vision-language model", "catalog": […] } → { "title": "small vision-language model", "picks": [ { "id": "lmms-lab/LLaVA-NeXT-Data", "expert": "vision", "why": "Anchor Vision on Hugging Face" }, … ], "rationale": "Local mixer staged 22 items across 12/12 experts. No mouth required.", "engine": "local" }

harvest.pack { "goal": "small vision-language model", "name": "VLM Mix v1", "catalog": […] } → flare-harvest-library v1 JSON，其中包含 coverage: { filled: 12, totalExperts: 12, balance: 0.94 } 以及每项的 ingest: { type: "hf-dataset" | "github-repo", ref } 指针。

后半部分——实际文件。包最初只是指针；通过 pull 将它们变成文件：

harvest.resolve { "item": { "id": "openai/gsm8k", "source": "huggingface" } } → 资源预览：4 个 parquet 分片 + README，每项都有一句话说明，绝不含糊

harvest.pull { "pack": {…}, "destination": "download" } → 解析并获取每个条目，更新包的 index 片段，并生成 VLM Mix v1.harvest.zip——一个包含全部内容和来源信息 MANIFEST.json 的文件

harvest.push { "bundle": "/path/to/VLM Mix v1.harvest.zip", "owner": "you", "repo": "my-data", "token": "ghp_…", "create_if_missing": true } → 在新建的私有仓库中提交一次：包含文件和清单，提交消息说明内容及来源

同样的流程也适用于代码。第二个会话——构建包：

你： 我想从几个不错的仓库中获取限流代码，打包起来供我的 Agent 构建使用

harvest.search { "topic": "express rate limiting middleware" } → code 专家会找出包含你所需部分的仓库

harvest.pack { "goal": "add rate-limiting to my API", "name": "Rate Limit Parts v1", "catalog": […], "purpose": "code" } → flare-harvest-codepack v1 JSON——条目结构相同，不进行训练覆盖度评分

harvest.pull { "pack": {…}, "destination": "download", "kinds": ["code", "docs"] } → 仅拉取源文件（跳过权重/数据集），并生成 .harvest.zip

harvest.push { "bundle": "…", "owner": "you", "repo": "rate-limit-parts", "create_if_missing": true } → 你的 Agent 拉取仓库，并基于这些部分进行构建

工具

工具	功能
harvest.search	{topic, hf_token?, gh_token?} — 按主题搜索 + 完整的 12 位专家图谱扫描，并去重
harvest.expert	{expert, hf_token?, gh_token?} — 运行一位专家精选的查询（12 个 ID：code、math、science、language、vision、audio、medical、law、knowledge、safety、affect、systems）
harvest.latest	{} — 趋势内容：近期更新的 HF 数据集、热门/近期 GitHub 仓库
harvest.compose	{goal, catalog} — 本地混合器组合出平衡的集合；提供选择结果和理由（混合器本身不需要 LLM）
harvest.pack	{goal, catalog, name, purpose?: "training" | "code"} — 组合 → 打包为 JSON。training（默认值）会为混合内容评分，并生成 flare-harvest-library v1；code 会生成 flare-harvest-codepack v1：供 Agent 提取并构建的零件箱
harvest.resolve	{item, kinds?, hf_token?, gh_token?} — 预览单个包条目的拉取列表：包含哪些文件、原因，以及受限条目的 needs_token。kinds（例如 ["code","docs"]）仅预览指定类型的文件。不下载
harvest.pull	{pack, destination: "local" | "download", kinds?, dir?, confirm_large?, hf_token?, gh_token?} — 为整个包解析并获取内容，然后更新索引；"download" 还会生成 .harvest.zip。kinds（例如 ["code","docs"]）适用于代码包流程：只获取源文件，不含权重/数据集。超大拉取会先返回 needs_confirm
harvest.push	{bundle, pack_name?, owner, repo, token, create_if_missing?, branch?, path?} — 通过一次提交将包推送到 GitHub（新建时默认为私有）

catalog 条目的格式为 { id, source, expert, description? } — harvest.search 返回的对象可直接传入。

速率限制

所有请求都会访问 Hugging Face 和 GitHub 的公共 API。未认证时，你可以获得：

• Hugging Face： /api/datasets 的匿名配额较宽裕（突发请求时偶尔会出现 429；结果会在进程内缓存 12 分钟）
• GitHub： 搜索每个 IP 每小时 60 次请求 — 12 位专家扫描是最耗请求的调用

如需实际使用，请通过环境变量或每次调用时传入的 hf_token / gh_token 参数设置 HF_TOKEN / GITHUB_TOKEN（免费账户即可）。参见 .env.example。

包格式

包是 flare-harvest-library v1 JSON — 参见 PACK-FORMAT.md。

指针与已拉取内容

新建的包只有指针，不含数据：每个条目会注明其来源以及如何 导入，但不包含文件。harvest.pull 会将指针转换为文件，并将结果 记录在包 JSON 中附加的 index 段：

{ "index": { "openai/gsm8k": { "local": "/tmp/harvest-pulls/pack/openai__gsm8k",
  "url": "https://huggingface.co/datasets/openai/gsm8k", "kind": "dataset",
  "license": null, "fetched_at": "2026-09-26T…", "files": ["main/train-….parquet", …] } } }

v1 读取器会安全地忽略该段；没有该段的包会作为纯指针包加载。 destination: "download" 还会生成包含这些文件和 MANIFEST.json 的 .harvest.zip（每个文件均记录来源、URL、许可证和 SHA-256 — 包未注明许可证时， 会将许可证标记为 unknown，绝不猜测）。

令牌说明

令牌会按调用传入，绝不存储：

• harvest.search / harvest.expert / harvest.latest / harvest.resolve / harvest.pull 接受 hf_token / gh_token（或 HF_TOKEN / GITHUB_TOKEN 环境变量）— 用于提高速率限制并访问受限数据集，且只会通过 Authorization 标头发送。
• harvest.push 接受每次调用传入的 token（GitHub PAT，或 GITHUB_TOKEN 环境变量）。
• 令牌绝不会写入磁盘、日志、包文件或清单。 获取续传记录（.harvest-fetch.json）只保存路径、字节数 和哈希值。

工作原理

• src/harvest/scan-core.ts — 并行扫描 HF/GitHub，结果缓存 12 分钟
• src/experts.ts — 12 位专家图谱（精选查询 + 种子条目）
• src/harvest/compose-local.ts — 本地混合器（“无需嘴巴”）：为每位专家锚定一个条目，然后平衡 HF/GitHub 来源，最后补充内容以提高覆盖度
• src/coverage.ts — 基于熵的 12 位专家覆盖度/平衡度评分
• src/harvest/compose-mouth.ts — 可选：通过任意兼容 OpenAI 的 /v1 端点（如 LM Studio）进行组合，而非使用本地混合器
• src/harvest/resolve.ts — “哪些文件”的智能处理：将 HF Hub / GitHub 树形列表分类为数据、权重、配置、代码、文档（纯函数 + 轻量 API 客户端）
• src/harvest/fetch.ts — 执行下载：支持续传的流式下载、大小限制、进度显示、每个文件的 SHA-256；令牌作为函数参数传入，绝不存储
• src/harvest/bundle.ts — 将已获取的目录和来源信息 MANIFEST.json 压缩为 .harvest.zip
• src/harvest/push.ts — 通过 GitHub 的 Git Data API 将压缩包推送到 GitHub：一次提交，默认私有（已勾勒出 // TODO(GitLab) 扩展接口）
• src/harvest/index.ts — Agent 端：增补式 index 条目 + resolvePointer / getItemFiles / queryIndex
• mcp/server.ts — MCP 服务（stdio、底层 SDK API、手写 schema）

许可证

Apache-2.0 — 详见 LICENSE。