@happyvertical/smrt-app-cli

中文文档
0.62.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 1.5万

SMRT应用程序的可再使用的CLI工厂——品牌 <name> <resource> <command> CLI + 有装饰器驱动的 MCP 桥

中文使用文档
文档目录11 节
  1. 安装
  2. 快开始
  3. 发现符合规定的文物
  4. 远程 MCP 客户端命令
  5. 添加特定应用程序的命令
  6. MCP桥
  7. 配置和认证
  8. 公共 API
  9. 发展
  10. 生成本地桌面插件元数据
  11. 生成本地客户端设置

@happyvertical/smrt-app-cli (英语)

可再用,应用程序品牌的CLI支持 s-m-r-t app. 结合资源 、 生成命令引用、 设备编码认证、 本地 配置,以及没有将 CLI 连接到一个应用的 MCP stdio 桥.

当部署的 s-m-r-t 应用程序显示品牌时使用此软件包 <app> <resource> <command> CLI(英语:CLI). 使用 @happyvertical/smrt-cli 框架发展, 和代码生成命令.

安装

pnpm add @happyvertical/smrt-app-cli

需要26号节点或更新.

已发布软件包还显示配置驱动 smrt-app 二进制. 它让政策运行者 和应用程序操作员使用 CLI 外部 消费者存放处不保留品牌包装:

SMRT_APP_NAME=work \
SMRT_APP_ENV_PREFIX=WORK \
SMRT_APP_CONFIG_DIR=happyvertical-work \
SMRT_APP_DEFAULT_SERVER_URL=https://work.example \
pnpm dlx --package @happyvertical/[email protected] \
  smrt-app -- auth status

在自动化中将已公布的软件包的准确版本固定下来。 四份申请 需要设置且非机密; 命令参数 : -- 为: 转发至 createAppCli。可以传递与 --name, (中文(简体) ), --env-prefix, (中文(简体) ), --config-dir,以及 --default-server-url 之前 断取者. 在 CLI 执行前无效或不完整的配置失败 网络或证书访问。 可执行文件还应用了 HTTPS/ roopback 从应用程序特定环境选择的有效服务器 URL或 持续配置,以及命令级服务器覆盖.

运行相同的CLI的stdio MCP桥,配置其明确的身份和 选择桥模式 :

SMRT_APP_NAME=work \
SMRT_APP_ENV_PREFIX=WORK \
SMRT_APP_CONFIG_DIR=happyvertical-work \
SMRT_APP_DEFAULT_SERVER_URL=https://work.example \
SMRT_APP_MCP_SERVER_NAME=work-mcp \
SMRT_APP_MCP_SERVER_VERSION=1.0.0 \
smrt-app --stdio-mcp

SMRT_APP_* 用于非秘密可执行配置。 运行时间 证书继续使用特定应用环境/配置分辨率 执行 createAppCli;从不通过无记名符号作为可执行选项.

快开始

#!/usr/bin/env node
import { createAppCli } from '@happyvertical/smrt-app-cli';

const cli = createAppCli({
  name: 'acme',
  defaultServerUrl: 'https://app.acme.test',
});

await cli.run(process.argv.slice(2));

由此产生的国家综合倡议包括:

acme auth login [--server <url>] [--no-open]
acme auth status
acme auth logout
acme resources [--json] [--debug]
acme mcp
acme <resource> <command> [flags]

资源及其命令是从应用程序中找到的 /_resources 表面。 JSON Schema 成为 CLI 旗帜, 而不支持的图案形状是 而不是默默猜测.

发现符合规定的文物

createResourceListHandler() 包含 artifact 在兼容的旁边 user, (中文(简体) ), warnings,以及 resources 反应字段。 文物有个马厩 计划选择器,版本,条形命令,和 a sha256:<hex> 消化系统 这个 在使用其嵌入式发现有效载荷之前,CLI对其进行验证.

对于发布在下游的应用软件,安装所发布的确切信息 @happyvertical/smrt-users 像这样被俘的文物:

import {
  validateDiscoveryConformanceArtifact,
} from '@happyvertical/smrt-users/app-contract';

const response = await fetch('https://app.example/api/_resources');
const body = await response.json();
const artifact = validateDiscoveryConformanceArtifact(body.artifact);

console.log(artifact.schema, artifact.version, artifact.integrity.digest);
// Store all three selectors and the canonical JSON in your packaged-runtime test.

产品名称中包含的结果合同 code, (中文(简体) ), message, (中文(简体) ), details, (中文(简体) ), retryable, (中文(简体) ), correlationId, (中文(简体) ), idempotencyKey,以及 expectedVersion 元数据. mcp tools 财务报告和审定财务报表 mcp call 将此打印为 JSON 成功/错误信封。 HTTP 失败可能使用常规顶级 元对象或 { error: metadata }两者都符合同样的形状. 生成动作失败使用后一种形式 { error: { ok: false, code, message, status, ... } };CLI报告: HTTP 状态与普通元数据相邻. 石桥在MCP里载着它 _meta 下级 io.happyvertical/smrt。它故意不合成 MCP structuredContent。 。 。 .

远程 MCP 客户端命令

<app> mcp tools 清单和清单 <app> mcp call <tool> '<json>' 引用工具于 a 已部署的应用程序的现代 MCP 端点( 精确的 Streamable HTTP ) /api/mcp,或 mcpPath),打印出JSON结果. 旗帜 :

  • --url <server> 目标为所配置服务器以外的服务器.
  • --token-env <NAME> 从环境变量读取无记名符号. 代币从未被打印出来,而是被从"出""出""出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出"出""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 错误只命名变量 。 明确符号需要 HTTPS(或 循环) --url。没有它,将使用存储的登录符.
  • --mcp-path <path> 覆盖同一服务器 MCP 路由.
  • --legacy-rest 选择使用已贬值的 <mcpPath>/tools 财务报告和审定财务报表 <mcpPath>/call REST路线及其结果信封.
  • --confirm (单位:千美元)mcp call (仅)套 confirm: true 在呼叫参数中 外出或破坏性工具。 除非通过,否则永远不会增加 参数必须是 JSON 对象。 A 类 "confirm": true 已经存在 jSON没有改变.
WORK_OWNER_TOKEN=... acme mcp call send_invoice '{"id":"inv_1"}' \
  --url https://work.example.com --token-env WORK_OWNER_TOKEN --confirm

添加特定应用程序的命令

const cli = createAppCli({
  name: 'acme',
  extraCommands: [
    {
      name: 'doctor',
      description: 'Check the deployed app',
      async run(_args, context) {
        const health = await context.requestJson('/api/health');
        context.stdout.write(`${JSON.stringify(health, null, 2)}\n`);
      },
    },
  ],
});

App特定命令胜出内置. 避免名称可能与 发现资源流.

MCP桥

同样的应用程序 CLI 可以向本地曝光应用程序的 MCP 表面 stdio 客户端 :

await cli.startMcpBridge({ name: 'acme-mcp', version: '1.0.0' });

大桥往前走 /api/mcp 默认。 当应用程序挂载其 MCP 设置 mcpPath 打开 createAppCli() 或通过它每个呼叫 (单位:千美元)startMcpBridge({ mcpPath: '/mcp' })) (中文(简体) ). 二进制 --mcp-path=/mcp (单位:千美元)smrt-mcp-bridge,或 SMRT_MCP_PATH和 --mcp-path 编号 : SMRT_APP_MCP_PATH (单位:千美元)smrt-app) (中文(简体) ). 路径必须是相同的服务器和绝对的.

对本地的S-m-r-t应用,薄荷 证书与 smrt app token --scopes <scope> 在应用程序检查。 记号印出 一次 一次吗 然后把回回回回回的服务器和信使通过 app的环境前缀. 这个 Claude 桌面条目是一个实例 :

{
  "mcpServers": {
    "notes": {
      "command": "npx",
      "args": ["smrt-mcp-bridge", "--env-prefix=NOTES", "--mcp-path=/mcp"],
      "env": {
        "NOTES_SERVER_URL": "http://127.0.0.1:5173",
        "NOTES_TOKEN": "smrt_mcp_…"
      }
    }
  }
}

只有在 <PREFIX>_SERVER_URL 匹配目标服务器. 用 smrt app token revoke <id>。 。 。 .

包裹还装了通用的 smrt-mcp-bridge 二进制. 远程应用程序 表面一般被挂载 @happyvertical/smrt-app-mcp。 。 。 . 二进制在解析或解析前拒绝非回放平方文本 HTTP 源头 发送已存储的证书; 远程应用服务器使用 HTTPS .

默认本地 MCP 桥保存上游工具目录顺序并转发 tools/list, (中文(简体) ), tools/call, (中文(简体) ), resources/list,以及 resources/read 通过 SDK v2. 工具目录和资源响应使用零 TTL 与 private 缓存范围 因此,随后的请求重新检查上游授权。 该桥使用 配置本地应用程序证书, 并且从不选择共享缓存 .

只有明确的 transport: 'legacy-rest' 兼容模式排序其 tools/list 按工具名称分类并发布一天 private 缓存寿命 . 该模式使用REST形状的工具端点,不转发资源.

配置和认证

  • name 提供显示名称和默认环境可变前缀.
  • envPrefix 覆盖前缀; configDir 覆盖本地配置 名称空间.
  • defaultServerUrl 仅在环境或存储配置中使用 提供服务器.
  • 设备编码登录在等待批准、到期、瞬态网络区分 失败 和强烈的拒绝.
  • Tokens和服务器配置保留在应用程序特定的本地配置路径中.
  • 设备流程响应可以识别其发行者. 托肯斯是按键 准确 发行器,在配置的服务器更改时不重复使用.

基于标准的远程 MCP OAuth 注册,使用 registerMcpClient() (计算机ID元数据文档,可执行 RFC 7591) DCR 倒计时 application_type并遵循 远程 MCP 授权指南。 。 。 .

公共 API

导出目的
createAppCli()建造有品牌的CLI和MCP桥
createMcpStdioBridge() 编号 : runMcpStdioBridge()低级桥梁控制
fetchResourceList()获取已部署的资源目录
invokeCommand()启动一个生成的资源命令
buildFlagParser()将支持的 JSON Schema 转换为旗帜
loadCliConfig() 编号 : saveCliConfig()读取并写入命名空间 CLI 配置
resolveMcpClientRegistration()检查选中的客户端 ID 元数据或 DCR 路径
registerMcpClient()使用客户端ID元数据或执行 DCR 倒置

发展

pnpm --filter @happyvertical/smrt-app-cli test
pnpm --filter @happyvertical/smrt-app-cli typecheck
pnpm --filter @happyvertical/smrt-app-cli build

维护者模式和认证变量记录在 AGENTS.md。 。 。 .

用于安装已知 OAuth 发行器的远程部署 CliConfigContext.expectedCredentialIssuer 以精确的标识。 存储 证书必须匹配服务器和签发者;环境证书也必须匹配 需求 ${PREFIX}_TOKEN_ISSUER。这不会取代终端设备 与浏览器 OAuth 相通。 见 远程授权合同。 。 。 .

生成本地桌面插件元数据

使用 generateDesktopPluginArtifacts 在产品的包装步骤。 过 便携式插件列表中的公共产品元数据,例如 厨房清单编辑 需要的字段为 name (小写字母、数字和单连字符), version (SemVer), (英语), description,以及 author.name选项 extensions["com.openai"].interface.displayName 默认为 name。 。 。 .

import { generateDesktopPluginArtifacts } from '@happyvertical/smrt-app-cli';

const files = generateDesktopPluginArtifacts(productManifest, {
  platform: 'darwin',
  executable: 'server/smrt-mcp-launcher',
});

结果绘制出分布-根基-相对路径来决定UTF-8 JSON. 将文件在新的中转目录中实现物质化 。 将可执行文件放入 同样的 server/ 每个插件目录中的路径。 运行生成器 目标平台(darwin, (中文(简体) ), win32,或 linux),使用一个 .exe 发射器 windows 的文件名 。 发射装置 必须解决已安装的应用程序捆绑的运行时间并获得本地授权 在发射时。 生成器只读取公共元数据,没有环境, MCP参数,端点,或认证配置.

  • claude-desktop/<name>/manifest.json 二进制扩展显示于 运行目录 mcpb pack。在包装时包含可执行文件. 明细表宣布目标平台 并解决发射装置 已安装扩展目录. Claude 桌面扩展 • 妇女 MCPB 显示格式
  • plugins/<name>/plugin.json 财务报告和审定财务报表 mcp.json 是可移动的 ChatGPT 桌面插件, 列出于 .agents/plugins/marketplace.json。 。 。 . OpenAI 插件包装 • 妇女 只用于桌面的插件 • 妇女 代理插件 stdio 路径规则
  • plugins/<name>/.claude-plugin/plugin.json 财务报告和审定财务报表 .claude-plugin/marketplace.json 提供 Claude 代码市场 兼容性。 Claude 桌面从分离处安装 MCPB 扩展 运行目录 . 克劳德代码市场

每个生成的目录包含一个条目. 对于共享目录,合并 输入由包装器维护的目录。 现场安装和 在 Claude 桌面和 ChatGPT 桌面中执行需要制作 发射器和单独的主机验证.

生成本地客户端设置

generateLocalMcpSetup({name,command,args}) 让克洛德代码的贝壳引用 claude mcp add, 克劳德桌面/.mcp.json 用于已有的 JSON 和 Codex TOML 拥有者授权的Stdio发射器。 只通过公共可执行文件/ 发射器路径, 从来没有一个携带者. CliConfigContext.configPath 让应用程序私自写作 直接通过 saveCliConfig 不改变进程环境. 现代桥梁广告 tools.listChanged 并调查上游无国籍者 每两秒编目(包括页). 更改的描述、撤销和 恢复无效发现; 关闭清除计时器。 没有共享目录缓存 .

版本与发布记录

@happyvertical/smrt-app-cli 共发布 366 个版本,首次发布于 2026/06/23;过去 12 个月发布了 366 个版本。

版本发布日期距今
0.62.1latest2026/11/17今天
0.62.02026/11/17今天
0.61.62026/11/161 天前
0.61.52026/11/161 天前
0.61.42026/11/161 天前
0.61.32026/11/152 天前

关于 @happyvertical/smrt-app-cli 的常见问题

@happyvertical/smrt-app-cli 是什么?

SMRT应用程序的可再使用的CLI工厂——品牌 <name> <resource> <command> CLI + 有装饰器驱动的 MCP 桥

如何安装 @happyvertical/smrt-app-cli?

在项目目录运行 npm install @happyvertical/smrt-app-cli,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 smrt-app、smrt-mcp-bridge,可以用 npx smrt-app 直接运行。

@happyvertical/smrt-app-cli 支持 TypeScript 吗?

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

@happyvertical/smrt-app-cli 支持 ESM 还是 CommonJS?

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

@happyvertical/smrt-app-cli 需要什么版本的 Node.js?

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

@happyvertical/smrt-app-cli 可以商用吗?

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

@happyvertical/smrt-app-cli 的下载量有多少?

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

@happyvertical/smrt-app-cli 还在维护吗?

最新版本 0.62.1 发布于 2026/11/17(今天);至今共发布 366 个版本,其中过去 12 个月发布了 366 个;首次发布于 2026/06/23。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。