# @chkp/mcp-utils 中文文档

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

版本：1\.6\.2
npm 元数据更新时间：2026-11-08T14:24:20.715Z
中文译文更新时间：2026-11-09T13:58:37.089Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：304 kB，81 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：3 个
- 首次发布：2025-07-17T11:50:58.073Z
- 最新版本发布：2026-11-08T14:24:20.273Z
- 近 30 天下载量：16749（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 9 个）

## 中文简介

用于检查点 MCP 服务器的共享工具

## 安装

```sh
npm install @chkp/mcp-utils
```

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

## README

# @ chkp/ mcp- utils

共享检查点MCP服务器的公用设施.

## 特征

### 配置驱动的 MCP 服务器启动器

这个 `launchMCPServer` 函数提供了一种由配置驱动的方法来启动MCP服务器,去除锅炉板代码并使得通过JSON配置文件可以维护的CLI选项.

## 使用量

### 1\. 创建服务器配置文件

创建一个 `server-config.json` 在服务器包中的文件 :

```json
{
  "name": "My MCP Server",
  "description": "Description of my MCP server",
  "options": [
    {
      "flag": "--api-key <key>",
      "description": "API key for authentication",
      "env": "API_KEY",
      "type": "string"
    },
    {
      "flag": "--host <host>",
      "description": "Server host",
      "env": "SERVER_HOST",
      "default": "localhost",
      "type": "string"
    },
    {
      "flag": "--verbose",
      "description": "Enable verbose output",
      "env": "VERBOSE",
      "type": "boolean"
    }
  ]
}
```

### 2\. 更新您的服务器的主要功能

用发射装置替换手动的 CLI 设置 :

```typescript
import { launchMCPServer } from '@chkp/mcp-utils';
import { join, dirname } from 'path';
import { fileURLToPath } from 'url';

// Your existing server, Settings, and pkg imports...

const main = async () => {
  await launchMCPServer(
    join(dirname(fileURLToPath(import.meta.url)), 'server-config.json'),
    { server, Settings, pkg }
  );
};

main().catch((error) => {
  console.error('Fatal error in main():', error);
  process.exit(1);
});
```

### 3\. 附加依赖

添加 `@chkp/mcp-utils` 给您的包裹

```json
{
  "dependencies": {
    "@chkp/mcp-utils": "*"
  }
}
```

## 配置图

### 服务器配置

-   `name` (字符串):显示服务器的名称
-   `description` (弦,可选): 在帮助文本中显示描述
-   `options` (备选\[\]): CLI 选项矩阵

### 选择

-   `flag` (字符串):指挥官.js-风格的旗帜定义(如:, `--api-key <key>`, (中文(简体) ), `--verbose`(中文(简体) )
-   `description` (字符串):选项的帮助文本
-   `env` (弦,可选): 要读取默认的环境变量名
-   `default` (弦,可选): 如果不通过 CLI 或 env 提供默认值
-   `type` (“ 字符串” QQ“ 布尔” , 可选): 选项类型( 默认为“ 字符串 ” )

## HTTP 运输

默认情况下,使用 `launchMCPServer` 使用情况 **静态** transport,是克洛德桌面和Cursor等MCP客户端的标准模式. 对主机或多用户部署 **HTTP 运输** (MCP可流式HTTP)也可用.

> **继续前的安全通知 :** HTTP服务器没有内置认证,也没有TLS. 任何能够到达端口的客户端都可以建立会话,并使用清晰文本的证书旅行. 只使用HTTP运输在认证的倒置代理(nginx, Caddy, a 云负载平衡器)后终止TLS并强制认证. 如果您正在运行与您的 MCP 客户端相同的机器上的服务器, 请使用默认的 stdio 传输 —— 它没有这些关切 .

### 以 HTTP 模式启动服务器

```bash
MCP_TRANSPORT_TYPE=http MCP_TRANSPORT_PORT=3000 my-mcp-server
# or
my-mcp-server --transport http --transport-port 3000
```

服务器曝光:

-   `POST/GET/DELETE /mcp` - MCP协议终点
-   `GET /health` — 服务器状态( 活动会话数, 版本)

HTTP 请求机构仅限于 **4个小米B** 默认。 设定 `MCP_MAX_HTTP_BODY_BYTES` 改为正整数以改变限制(例如, `8388608` 8个米B). 超过其范围的请求收到HTTP `413`,包括请求 以块式传输编码发送 。 阅读时, 在 JSON 解析或会话创建. 空值使用默认值;其他无效值失败 HTTP 启动 。 让 客户端在上传时接收拒绝, 服务器丢弃最多4个 乘以身体限制(最多32个米B),或最多等待一秒再关闭 拒绝的连接.

对于stdio 和 HTTP , 请求参数在工具- sema 之前检查 校验: 数组和对象最多可能包含 **1万个** 物品/财产, 最多为 **10万个** 价值和价值 **64国道** 巢穴水平跨越参数. 超大小的已注册呼叫, 启用工具返回 `isError: true` 与 `VALIDATION_ERROR` 并记录一个在启用遥测时失败的遥测事件, 不执行工具。 未知或已禁用的工具保留 SDK 的常用工具 拒绝而不记录或通过这个警卫报告他们所要求的姓名. 其他请求方法接收协议级无效参数错误. 这些共同限制还涵盖生成的工具和嵌入式收藏 工具计划可能会施加较小的限制.

### 连接 MCP 客户端

对准您的 MCP 客户端 `http://<host>:3000/mcp`。克劳德桌面示例`claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "my-server": {
      "url": "http://localhost:3000/mcp"
    }
  }
}
```

## 报告错误

一个规则,和 `CPMcpServer` 为你执行:

> 失败必须是 **抛出**,或已经正确形状 `isError` 结果。 永远不要把失败当作一个纯粹的价值.

**您不需要为您的工具写出正确错误处理 .** 每个 工具被包裹,是否您用 `registerTool()` 老年人 `tool()`。任何您抛出的东西 — HTTP 失败, 文件缺失, SQLite 出错, 失败的子进程、 Zod 验证错误、 平原 `Error` 改为 符合规格的结果 `isError: true` 和稳定 `error_code`,以及 报告为遥测失败。 提示和资源是相同的 无论是哪种方法名称 只会让错误传播的处理者 做对的事:

```ts
server.tool('my_tool', 'does a thing', { id: z.string() }, async (args, extra) => {
  const resp = await runApi('POST', 'show-thing', { uid: args.id }, extra);
  return { content: [{ type: 'text', text: JSON.stringify(resp) }] };
});
```

执行 **没有** 写这个——它让一个失败的呼叫看起来很成功,这恰恰是 包装器是用来防止的:

```ts
// ANTI-PATTERN: no isError, so callers and telemetry both see a success.
try {
  ...
} catch (error) {
  return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
}
```

### 选择更好的消息或代码

只有当您可以添加某物时, 分类者才能推断出 操作上下文,或更具体的代码:

```ts
import { McpErrorCode, toolError, toolErrorFrom, McpToolError } from '@chkp/mcp-utils';

// Keep your context, and get a classified code for free.
catch (error) {
  return toolErrorFrom(error, 'Failed to parse rulebase');
}

// Or state the code yourself, with extra context for programmatic callers.
return toolError(McpErrorCode.OPERATION_FAILED, `Simulation failed: ${detail}`, {
  retryable: false,
  details: { task },
});

// From a client or helper, throw so every caller benefits.
throw new McpToolError(McpErrorCode.AUTH_FAILED, 'API key rejected', {
  upstreamStatus: 401,
});
```

### 错误代码

`AUTH_FAILED`, (中文(简体) ), `PERMISSION_DENIED`, (中文(简体) ), `NOT_FOUND`, (中文(简体) ), `VALIDATION_ERROR`, (中文(简体) ), `RATE_LIMITED`, (中文(简体) ), `TIMEOUT`, (中文(简体) ), `UPSTREAM_UNREACHABLE`, (中文(简体) ), `UPSTREAM_ERROR`, (中文(简体) ), `RESOURCE_UNAVAILABLE`, (中文(简体) ), `OPERATION_FAILED`, (中文(简体) ), `INTERNAL`。 。 。 .

代码是故意的 原因不可知的: 它们描述了什么是错的 呼叫器,不是哪个子系统生产的 错误结果看起来是这样的 :

```json
{
  "isError": true,
  "content": [{ "type": "text", "text": "NOT_FOUND: Could not reach your Management" }],
  "structuredContent": {
    "error_code": "NOT_FOUND",
    "error_message": "Could not reach your Management",
    "upstream_status": 404,
    "retryable": false
  }
}
```

### 显示未标记失败

运行服务器 `CP_MCP_STRICT_ERRORS=true` 当工具出现时登录警告 返回一个不标记为错误但看起来像错误的结果。 这是一个 柔和而永不改变行为——它只是指点处理者值得一分 开发过程中的第二外观.

## 福利

-   **连续错误报告**: 工具故障在中央标出并编码,没有每包工作
-   **零沸腾**: 主函数从~15行减少到~5行
-   **配置驱动**: 所有可维护的 JSON 文件的 CLI 选项
-   **环境变量支持**: Env vars 自动映射到选项
-   **类型安全**: 所有配置的脚本接口
-   **一致帮助**: 自动帮助文本生成
-   **简单维护**: 不触碰代码而更改选项

## 迁移示例

**在此之前:**

```typescript
const main = async () => {
  const program = new Command();
  program
    .option('--api-key <key>', 'API key')
    .option('--host <host>', 'Server host', process.env.SERVER_HOST || 'localhost')
    .option('--verbose', 'Enable verbose output', process.env.VERBOSE === 'true');
  program.parse(process.argv);
  const options = program.opts();
  Settings.setSettings(Settings.fromArgs(options));
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error('Server running...');
};
```

**之后:**

```typescript
const main = async () => {
  await launchMCPServer(
    join(dirname(fileURLToPath(import.meta.url)), 'server-config.json'),
    { server, Settings, pkg }
  );
};
```

## 常见问题

### @chkp/mcp-utils 是什么？

用于检查点 MCP 服务器的共享工具

### 如何安装 @chkp/mcp-utils？

在项目目录运行 npm install @chkp/mcp-utils，或使用 pnpm add / yarn add / bun add。

### @chkp/mcp-utils 支持 TypeScript 吗？

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

### @chkp/mcp-utils 支持 ESM 还是 CommonJS？

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

### @chkp/mcp-utils 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @chkp/mcp-utils 可以商用吗？

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

### @chkp/mcp-utils 的下载量有多少？

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

### @chkp/mcp-utils 还在维护吗？

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