企业官网建设流程全解析

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/app：MCP 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_TOKEN>"

Gemini 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_content=true可以移除 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.ts：

export 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.ts：

export 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)'), }), }

核心行为如下：

1. URL 归一化：normalizeDocUrl会把/docs/...相对路径补全为https://huggingface.co/docs/...，并把gradio.app域名规整为www.gradio.app（见 doc-fetch.ts）。
2. URL 白名单校验：只接受huggingface.co/www.huggingface.co下以/docs/开头的路径以及gradio.app域名的链接，其他一律报 "That was not a valid documentation URL"，防止越权抓取。
3. HTML 转 Markdown：优先请求accept: text/markdown；若服务端返回 HTML，则用 TurndownService 转换，并主动剥离header/nav/footer/aside/form/button/style/noscript/iframe等噪音容器与内联 SVG。
4. 分块返回：单块上限 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_FETCH=true让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同属一套体系：

其中model_search的配置可见 model-search.ts：sort支持trendingScore / downloads / likes / createdAt / lastModified，limit默认 20、范围 1～100，查询留空时可配合排序得到"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.md）；
• StreamableHTTPJson：无状态 JSON-RPC 模式，Docker 默认启用（见 Dockerfile）。

关键环境变量

从 README.md 与 start.sh 可确认以下配置项：

代理工具 CSV 格式为proxy_id,url,response_type，response_type取SSE或JSON；多代理源时工具名会加proxy_id_前缀（如papers_hf-papers-search_send）。

六、源码级实践建议

结合仓库实现，给出三条可直接落地的使用建议：

1. 查询新 API 一律先走hf_doc_search：这是 huggingface.md 的硬性规则，也是避免"记忆过期"的唯一可靠手段。空查询可先摸清文档结构，再带product过滤收敛结果。
2. 长文档用offset接力读取：hf_doc_fetch单块 7500 token，注意识别文末的DOCUMENT TRUNCATED标记并携带offset继续，直到读完为止。
3. 本地部署时优先 STDIO 或 JSON 模式：本地 Agent 建议直接npx @llmindset/hf-mcp-server（STDIO）或 Docker 默认的streamableHttpJson（无状态、便于水平扩展）；令牌务必通过环境变量注入，DEFAULT_HF_TOKEN切勿在生产 HTTP 部署中使用。

附：进一步阅读

• 使用规则原文：mcp_servers/hugging_face/huggingface.md
• MCP 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