@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>/callREST路线及其结果信封.--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 并调查上游无国籍者
每两秒编目(包括页). 更改的描述、撤销和
恢复无效发现; 关闭清除计时器。 没有共享目录缓存 .