Klavis 仓库 Hugging Face MCP Server 使用指南hf 命令行与 hf_doc_search 文档检索实践【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis导读本文聚焦 Klavis 开源仓库中集成的 Hugging Face 官方 MCP Server目录 mcp_servers/hugging_face围绕其在仓库根目录提供的 huggingface.md 使用规则展开你可以学会如何在 AI 客户端中接入 Hugging Face MCP 服务、通过hf_doc_search/hf_doc_fetch工具获取最新文档以及使用huggingface_hub自带的hf命令行完成仓库管理与推理服务调用。读完本文你将获得一套可直接复制的 MCP 配置与命令行操作方案。一、Hugging Face MCP Server 在仓库中的定位Klavis 仓库的核心定位是让 AI Agent 在任何规模下可靠地使用工具的 MCP 集成平台。仓库将 Hugging Face 官方 MCP Server 作为内置连接器之一完整收录在 mcp_servers/hugging_face其 README 明确描述为官方 Hugging Face MCP Server用于把 LLM 连接到 Hugging Face Hub 以及数千个 Gradio AI 应用。从仓库结构看该项目是一个 pnpm workspace 多包工程核心配置见 mcp_servers/hugging_face/package.json 与 mcp_servers/hugging_face/pnpm-workspace.yaml主要包含两个包packages/mcp封装 Hugging Face Hub API 与语义搜索端点的 MCP 工具实现被服务器消费packages/appMCP Server 本体 管理 Web 界面负责部署各传输端点。在仓库中如何配置该 MCP Server在 AI 客户端如 Claude Code、Gemini CLI、Cursor、VSCode中添加 Hugging Face MCP 服务可直接使用官方托管的远程端点。以 Claude Code 为例# 交互式登录方式推荐完成后按提示完成认证 claude mcp add hf-mcp-server -t http https://huggingface.co/mcp?login # 使用个人访问令牌方式 claude mcp add hf-mcp-server \ -t http https://huggingface.co/mcp \ -H Authorization: Bearer YOUR_HF_TOKENGemini CLI 使用gemini mcp add -t http huggingface https://huggingface.co/mcp?login随后可安装其扩展以加载上下文文件与自定义命令gemini extensions install https://github.com/huggingface/hf-mcp-server。VSCode 与 Cursor 则支持在mcp.json中写入如下配置huggingface: { url: https://huggingface.co/mcp, headers: { Authorization: Bearer YOUR_HF_TOKEN } }接入完成后打开 https://huggingface.co/settings/mcp 即可按需启用/停用具体工具与 Spaces。这是 huggingface.md 中所强调的可定制入口MCP Server 工具可在 https://huggingface.co/settings/mcp 处定制。提示在端点 URL 上追加?no_image_contenttrue可以移除 Gradio 服务返回的ImageContent块减少上下文噪音。二、hf_doc_search获取超出知识截止日期的最新文档huggingface.md 中有一条关键规则hf_doc_search包含比你知识截止日期更新的近期信息在查询 Hugging Face 库与命令行工具时务必使用它。这是因为 LLM 的训练数据存在截止日期而 Hugging Face 的 API、SDK 与 CLI 持续演进静态记忆会迅速过期。从源码看该工具的真实 ID 为hf_doc_search见 tool-ids.ts 中DOCS_SEMANTIC_SEARCH_TOOL_ID DOCS_SEMANTIC_SEARCH_CONFIG.name其完整配置定义在 docs-semantic-search.tsexport const DOCS_SEMANTIC_SEARCH_CONFIG { name: hf_doc_search, description: Search and Discover Hugging Face Product and Library documentation. Send an empty query to discover structure and navigation instructions. You MUST consult this tool for the most up-to-date information when using Hugging Face libraries. Combine with the Product filter to focus results., schema: z.object({ query: z.string() .max(200, Query too long) // 非空时至少 3 个字符否则报错 Supply at least one search term .describe( Start with an empty query for structure, endpoint discovery and navigation tips. Use semantic queries for targetted searches. ), product: z.string().optional().describe(Filter by Product. Supply when known for focused results), }), // 标注只读、开放世界openWorldHint: true }使用方式空查询发现结构发送空查询工具会调用https://huggingface.co/api/docs拉取文档产品索引返回一张Product | Category | Documentation表格帮助 LLM 了解 Hugging Face 文档库的整体导航结构源码中还会附注每个文档根目录都暴露llms.txt端点的提示在 URL 后追加/llms.txt即可获得面向 LLM 的文档清单。语义查询检索传入自然语言问题如 rate limits、how to load an image to image model in transformers工具内部将查询小写化后请求https://hf.co/api/docs/search语义检索 API返回按 Product 分组、按页面命中数排序的结果并给出文档摘录。底层实现细节源码佐证Token 预算管理默认tokenBudget 12500源码在拼接结果时实时估算 token一旦超出预算 70% 就进入截断模式将过长摘录截断为 400 字符并提示[Content truncated - use hf_doc_fetch for full text or narrow search terms]见 docs-semantic-search.ts 与 formatSectionExcerpts。结果分组结果先按 product 分组再按去掉锚点#section后的页面 URL 分组最后按heading2小节再次分组保证同一页面同一小节的摘录聚合展示便于 LLM 精准引用。配套测试仓库提供了 docs-semantic-search.test.ts 与 doc-fetch.test.ts 覆盖上述格式化与分块逻辑。三、hf_doc_fetch按需获取完整文档正文语义搜索只返回摘录而hf_doc_fetch负责获取完整文档。该工具定义于 doc-fetch.tsexport const DOC_FETCH_CONFIG { name: hf_doc_fetch, description: Fetch a document from the Hugging Face or Gradio documentation library. For large documents, use offset to get subsequent chunks., schema: z.object({ doc_url: z.string().max(200, Query too long).describe(Documentation URL (Hugging Face or Gradio)), offset: z.number().min(0).optional() .describe(Token offset for large documents (use the offset from truncation message)), }), }核心行为如下URL 归一化normalizeDocUrl会把/docs/...相对路径补全为https://huggingface.co/docs/...并把gradio.app域名规整为www.gradio.app见 doc-fetch.ts。URL 白名单校验只接受huggingface.co/www.huggingface.co下以/docs/开头的路径以及gradio.app域名的链接其他一律报 That was not a valid documentation URL防止越权抓取。HTML 转 Markdown优先请求accept: text/markdown若服务端返回 HTML则用 TurndownService 转换并主动剥离header/nav/footer/aside/form/button/style/noscript/iframe等噪音容器与内联 SVG。分块返回单块上限 7500 token超出时在文末追加 DOCUMENT TRUNCATED. CALL hf_doc_fetch WITH AN OFFSET OF N FOR THE NEXT CHUNK LLM 可据此用offset参数继续拉取后续内容实现见 applyChunking。配合使用hf_doc_search负责找到相关文档页hf_doc_fetch负责读全文两者构成完整的检索→精读链路。服务器端还支持通过环境变量SEARCH_ENABLES_FETCHtrue让hf_doc_fetch在启用hf_doc_search时自动开启。四、hf 命令行管理仓库与调用推理服务huggingface.md 明确指出huggingface_hub自带一个可通过hf命令访问的 CLI用于管理模型与数据集仓库、使用推理提供方inference providers。安装方式# 方式一uv 工具安装推荐隔离环境 uv tool install huggingface_hub # 方式二pip 升级安装 pip install -U huggingface_hub常用命令hf --help查看全部可用子命令hf auth whoami检查当前登录状态未登录会提示先执行hf auth login完成认证。hfCLI 覆盖的能力包括创建/克隆/上传模型与数据集仓库、管理 repo 文件与版本、调用推理提供方Inference Providers发起推理请求等。由于 CLI 的能力随版本持续更新huggingface.md 特别强调当 LLM 需要给出hf相关命令时应优先用hf_doc_search检索最新文档而不是依赖训练记忆——这正是工具补足知识截止日期设计意图的直接体现。从源码佐证huggingface_hub对应的 TypeScript 实现由huggingface/hub依赖提供见 packages/mcp/package.json说明 MCP 工具与hfCLI 共享同一套 Hub 生态能力。五、内置工具全景与运行方式内置工具清单仓库将全部内置工具 ID 汇总在 tool-ids.ts 的ALL_BUILTIN_TOOL_IDS中与hf_doc_search/hf_doc_fetch同属一套体系工具 ID用途space_search语义搜索 Hugging Face Spaces可筛选仅含 MCP Server 的 Spacemodel_search搜索模型支持query/author/task/library/sort/limit参数model_detail/dataset_detail查看模型与数据集详情paper_search/paper_summary论文搜索与摘要dataset_search数据集搜索hub_inspect检查 Hub 资源duplicate_space/space_info/space_files/use_spaceSpace 克隆、信息、文件与调用hf_doc_search/hf_doc_fetch本文核心的文档检索与抓取hf_jobs/dynamic_space任务执行与动态 Space 调用其中model_search的配置可见 model-search.tssort支持trendingScore / downloads / likes / createdAt / lastModifiedlimit默认 20、范围 1100查询留空时可配合排序得到Top 20 趋势模型等结果space_search定义于 space-search.ts默认返回 10 条。本地运行 MCP Server仓库支持 npx 与 Docker 两种本地运行方式# npx 方式三种传输模式 npx llmindset/hf-mcp-server # STDIO 模式 npx llmindset/hf-mcp-server-http # Streamable HTTP 模式 npx llmindset/hf-mcp-server-json # Streamable HTTP (JSON RPC) 模式 # Docker 方式 docker pull ghcr.io/evalstate/hf-mcp-server:latest docker run --rm -p 5000:5000 ghcr.io/evalstate/hf-mcp-server:latest启动后管理 Web 界面位于http://localhost:5000/Streamable HTTP 服务端点位于http://localhost:5000/mcp。三种传输的差异源码见 packages/app/src/server/transport为STDIO直接走 stdin/stdout无 HTTP 端点适合本地 Agent 进程StreamableHTTP有状态通过 SSE 维持连接相关连接管理环境变量见 README.mdStreamableHTTPJson无状态 JSON-RPC 模式Docker 默认启用见 Dockerfile。关键环境变量从 README.md 与 start.sh 可确认以下配置项环境变量默认值说明TRANSPORTstdio传输类型stdio/streamableHttp/streamableHttpJsonDEFAULT_HF_TOKEN无请求若无Authorization: Bearer头时使用的令牌仅限开发/测试或本地 STDIO 部署使用HF_TOKEN无STDIO 模式下且未设DEFAULT_HF_TOKEN时生效HF_API_TIMEOUT12500msHugging Face API 请求超时MCP_STRICT_COMPLIANCEfalseJSON 模式下对 GET 405 的严格合规处理AUTHENTICATE_TOOL-是否包含Authenticate工具以触发 OAuth 质询SEARCH_ENABLES_FETCHfalse设为true时启用hf_doc_search会自动开启hf_doc_fetchPROXY_TOOLS_CSV无以 CSV 加载远程 Streamable HTTP 代理工具源代理工具 CSV 格式为proxy_id,url,response_typeresponse_type取SSE或JSON多代理源时工具名会加proxy_id_前缀如papers_hf-papers-search_send。六、源码级实践建议结合仓库实现给出三条可直接落地的使用建议查询新 API 一律先走hf_doc_search这是 huggingface.md 的硬性规则也是避免记忆过期的唯一可靠手段。空查询可先摸清文档结构再带product过滤收敛结果。长文档用offset接力读取hf_doc_fetch单块 7500 token注意识别文末的DOCUMENT TRUNCATED标记并携带offset继续直到读完为止。本地部署时优先 STDIO 或 JSON 模式本地 Agent 建议直接npx llmindset/hf-mcp-serverSTDIO或 Docker 默认的streamableHttpJson无状态、便于水平扩展令牌务必通过环境变量注入DEFAULT_HF_TOKEN切勿在生产 HTTP 部署中使用。附进一步阅读使用规则原文mcp_servers/hugging_face/huggingface.mdMCP Server 完整 README安装、传输、环境变量、代理工具mcp_servers/hugging_face/README.md工具 ID 全量表mcp_servers/hugging_face/packages/mcp/src/tool-ids.ts文档检索实现docs-semantic-search.ts 与 doc-fetch.ts传输实现目录packages/app/src/server/transport【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考