# @happyvertical/sdk-mcp 中文文档

规范地址：https://npmcn.com/package/%40happyvertical/sdk-mcp/

版本：0\.113\.1
npm 元数据更新时间：2026-11-17T00:02:22.553Z
中文译文更新时间：2026-11-17T13:57:00.874Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40happyvertical/sdk-mcp
原文对照：https://npmcn.com/package/%40happyvertical/sdk-mcp/?lang=original
项目主页：https://github.com/happyvertical/sdk/tree/main/packages/sdk-mcp#readme
源码仓库：https://github.com/happyvertical/sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：25.7 kB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2026-06-23T08:14:21.011Z
- 最新版本发布：2026-11-17T00:02:22.372Z
- 近 30 天下载量：5828（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：131（近 12 个月 131 个）

## 中文简介

Have SDK的MCP服务器 - 向使用AGENT.md文件的软件包专家查询路线

## 安装

```sh
npm install @happyvertical/sdk-mcp
```

也可以使用：`pnpm add @happyvertical/sdk-mcp`、`yarn add @happyvertical/sdk-mcp`、`bun add @happyvertical/sdk-mcp`

## README

# @happyvertical/sdk-mcp (英语)

Have SDK的MCP服务器将开发者的查询传送到包文件. 它扫描每个包 `AGENT.md` 文件在启动时创建关键词索引登记册,并披露三种MCP工具: `ask` (AI动力QQA), `list-packages`,以及 `get-docs`。 。 。 .

## 安装

```bash
pnpm install @happyvertical/sdk-mcp
```

> 释放到 npm.happyvertical.com 并镜像到公共 npm , 它可以滞后; 见 root README 的安装注释 `@happyvertical:registry` 线条。 公共 npm 不需要范围化的注册配置 .

## 使用量

### 作为 MCP 服务器

该包提供了基于stdio的MCP服务器. 直接运行 :

```bash
npx sdk-mcp
```

或者在您的 MCP 客户端( 如 Claude Desktop) 中配置它以启动为子进程 .

### Claude 代码背景 CLI

将 AGENT.md 和元数据复制到您的项目中 `.claude/` aI辅助开发目录:

```bash
npx have-sdk-mcp-context
```

### 环境变量

这个 `ask` 工具需要一个 AI 提供者。 设定其中之一 :

-   `HAVE_AI_API_KEY` ——任何提供者的倒置 API 密钥
-   `HAVE_AI_TYPE` - 提供者类型(`openai`, (中文(简体) ), `anthropic`, (中文(简体) ), `gemini`(中文(简体) )
-   `OPENAI_API_KEY`, (中文(简体) ), `ANTHROPIC_API_KEY`,或 `GEMINI_API_KEY`

这个 `list-packages` 财务报告和审定财务报表 `get-docs` 工具工作时没有AI配置.

## MCP 工具

### 询问

问个关于SDK的问题 通过关键词匹配与相关包的路由,并使用AI(top 3匹配)合成一个响应.

```json
{
  "query": "How do I send an email with an attachment?",
  "packages": ["email", "messages"]
}
```

-   `query` (需要)——问的问题
-   `packages` (可选) – 明确包名可参考而非自动路由

### 列表包

列出所有已发现的带有描述和关键词的SDK包. 无参数 .

### 获取文件

获取特定软件包的全部 AGENT.md 内容 .

```json
{
  "packageName": "ai"
}
```

## 如何运作

1.  **书记官处** -一接到电话就扫描 `packages/*/AGENT.md` 并建立一个 `Map<string, PackageMetadata>` 键入软件包名称。 每个条目包括描述(取自AGENT.md),关键词(取自 `registry.ts`),和完整的文档内容.
    
2.  **路线** ——将用户查询分解为令牌并按关键词重合给每个包打分(准确匹配=10平分,部分=5平分,名称奖金=15平分). 低于最低分数门槛的套件不包括在内.
    
3.  **综述** - 电话 `ask` 工具装入 AGENT.md 用于前3个匹配的软件包,根据上下文构建一个系统提示,并调用 `@happyvertical/ai` 生成一个响应.
    

## 添加新软件包

1.  创建一个 `AGENT.md` 在新软件包目录中
2.  添加关键字条目 `src/registry.ts` (单位:千美元)`PACKAGE_KEYWORDS`(中文(简体) )
3.  重建: `pnpm run build`

软件包将在下一个服务器启动时自动被发现.

## API 密码

### 书记官处`registry.ts`(中文(简体) )

| 导出 | 说明 |
| --- | --- |
| `PackageMetadata` | 接口 : `name`, (中文(简体) ), `path`, (中文(简体) ), `description`, (中文(简体) ), `claudeMd`, (中文(简体) ), `keywords` |
| `PACKAGE_KEYWORDS` | 用于路由的静态关键字到包装映射 |
| `buildPackageRegistry()` | 扫描软件包目录并返回缓存 `Map<string, PackageMetadata>` |
| `getPackage(name)` | 获取单个软件包的元数据 |
| `getAllPackages()` | 将所有软件包元数据作为数组 |
| `getPackageDocs(name)` | 获取软件包的原始 AGENT.md 内容 |
| `clearCache()` | 清除内存登记缓存 |

### 路由器( R)`router.ts`(中文(简体) )

| 导出 | 说明 |
| --- | --- |
| `PackageMatch` | 接口 : `package`, (中文(简体) ), `score`, (中文(简体) ), `matchedKeywords` |
| `routeQuery(query, minScore?)` | 针对查询字符串的分数和排序软件包 |
| `getPackagesByNames(names)` | 以明确名称列表查看软件包 |
| `getTopPackages(query, limit?)` | 简指 `routeQuery` + 切片 |

### 工具( E)`tools/`(中文(简体) )

| 导出 | 说明 |
| --- | --- |
| `ask(input)` | AI 驱动的 XQA 工具 |
| `listPackages()` | 列出所有软件包 |
| `getDocs(packageName)` | 获取软件包文档 |

## 依赖关系

-   `@happyvertical/ai` - 提供 `ask` 工具
-   `@modelcontextprotocol/sdk` - MCP协议的执行

## 发展

```bash
pnpm run build       # Build
pnpm test            # Run tests
pnpm run dev         # Watch mode (build + test)
```

## 许可证

麻省理工学院

## 常见问题

### @happyvertical/sdk-mcp 是什么？

Have SDK的MCP服务器 - 向使用AGENT\.md文件的软件包专家查询路线

### 如何安装 @happyvertical/sdk-mcp？

在项目目录运行 npm install @happyvertical/sdk-mcp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 sdk-mcp、have-sdk-mcp-context，可以用 npx sdk-mcp 直接运行。

### @happyvertical/sdk-mcp 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @happyvertical/sdk-mcp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @happyvertical/sdk-mcp 可以商用吗？

@happyvertical/sdk-mcp 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @happyvertical/sdk-mcp 的下载量有多少？

根据 npm 官方下载统计，@happyvertical/sdk-mcp 在 2026/10/17 – 2026/11/15 这 30 天内被下载 5,828 次，日均约 194 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @happyvertical/sdk-mcp 还在维护吗？

最新版本 0\.113\.1 发布于 2026/11/17（今天）；至今共发布 131 个版本，其中过去 12 个月发布了 131 个；首次发布于 2026/06/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

