@ chkp/ mcp- utils
共享检查点MCP服务器的公用设施.
特征
配置驱动的 MCP 服务器启动器
这个 launchMCPServer 函数提供了一种由配置驱动的方法来启动MCP服务器,去除锅炉板代码并使得通过JSON配置文件可以维护的CLI选项.
使用量
1. 创建服务器配置文件
创建一个 server-config.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 设置 :
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 给您的包裹
{
"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 模式启动服务器
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:
{
"mcpServers": {
"my-server": {
"url": "http://localhost:3000/mcp"
}
}
}
报告错误
一个规则,和 CPMcpServer 为你执行:
失败必须是 抛出,或已经正确形状
isError结果。 永远不要把失败当作一个纯粹的价值.
您不需要为您的工具写出正确错误处理 . 每个
工具被包裹,是否您用 registerTool() 老年人
tool()。任何您抛出的东西 — HTTP 失败, 文件缺失, SQLite 出错,
失败的子进程、 Zod 验证错误、 平原 Error 改为
符合规格的结果 isError: true 和稳定 error_code,以及
报告为遥测失败。 提示和资源是相同的
无论是哪种方法名称 只会让错误传播的处理者
做对的事:
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) }] };
});
执行 没有 写这个——它让一个失败的呼叫看起来很成功,这恰恰是 包装器是用来防止的:
// ANTI-PATTERN: no isError, so callers and telemetry both see a success.
try {
...
} catch (error) {
return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
}
选择更好的消息或代码
只有当您可以添加某物时, 分类者才能推断出 操作上下文,或更具体的代码:
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。 。 。 .
代码是故意的 原因不可知的: 它们描述了什么是错的 呼叫器,不是哪个子系统生产的 错误结果看起来是这样的 :
{
"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 自动映射到选项
- 类型安全: 所有配置的脚本接口
- 一致帮助: 自动帮助文本生成
- 简单维护: 不触碰代码而更改选项
迁移示例
在此之前:
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...');
};
之后:
const main = async () => {
await launchMCPServer(
join(dirname(fileURLToPath(import.meta.url)), 'server-config.json'),
{ server, Settings, pkg }
);
};