@supernal/universal-command

定义一次，随处部署。 CLI、API 和 MCP 接口的单一可信源。

⚠️ 重要提示：请直接使用，切勿重复造轮子

若您正在为 Supernal 构建命令，请务必使用本包，切勿为 CLI、API 和 MCP 分别实现独立版本。

安装

npm install @supernal/universal-command

快速上手

定义一个命令

import { UniversalCommand } from '@supernal/universal-command';

export const userCreate = new UniversalCommand({
  name: 'user create',
  description: 'Create a new user',
  
  input: {
    parameters: [
      { name: 'name', type: 'string', required: true },
      { name: 'email', type: 'string', required: true },
      { name: 'role', type: 'string', default: 'user', enum: ['user', 'admin'] },
    ],
  },
  
  output: { type: 'json' },
  
  handler: async (args, context) => {
    return await createUser(args);
  },
});

随处部署

// CLI
program.addCommand(userCreate.toCLI());
// → mycli user create --name "Alice" --email "alice@example.com"

// Next.js API
export const POST = userCreate.toNextAPI();
// → POST /api/users/create

// MCP Tool
const mcpTool = userCreate.toMCP();
// → user_create 工具，供 AI agent 调用

核心概念

单一处理器（Single Handler）

仅需编写一次业务逻辑。处理器接收已校验的参数，并返回结果：

handler: async (args, context) => {
  // 同一份代码同时适用于 CLI、API 和 MCP
  return await doThing(args);
}

输入 Schema

只需定义一次参数 —— 校验规则、CLI 选项、API 参数及 MCP Schema 均自动推导生成：

input: {
  parameters: [
    { name: 'id', type: 'string', required: true },
    { name: 'status', type: 'string', enum: ['draft', 'active', 'done'] },
    { name: 'limit', type: 'number', min: 1, max: 100, default: 10 },
  ],
}

接口专属配置

如需按接口定制行为，可分别覆盖对应配置：

cli: {
  format: (data) => formatForTerminal(data),
  streaming: true,
},

api: {
  method: 'GET',
  cacheControl: { maxAge: 300 },
  auth: { required: true, roles: ['admin'] },
},

mcp: {
  resourceLinks: ['export://results'],
}

注册表模式（Registry Pattern）

适用于管理多个命令的场景：

import { CommandRegistry } from '@supernal/universal-command';

const registry = new CommandRegistry();
registry.register(userCreate);
registry.register(userList);
registry.register(userDelete);

// 生成全部 CLI 命令
for (const cmd of registry.getAll()) {
  program.addCommand(cmd.toCLI());
}

// 生成全部 API 路由
await generateNextRoutes(registry, { outputDir: 'app/api' });

// 生成 MCP Server
const server = createMCPServer(registry);

运行时 Server

适用于无需代码生成的简易部署场景：

import { createRuntimeServer } from '@supernal/universal-command';

const server = createRuntimeServer();
server.register(userCreate);
server.register(userList);

// 作为 Next.js Route 使用
export const GET = server.getNextHandlers().GET;
export const POST = server.getNextHandlers().POST;

// 或作为 Express 中间件使用
app.use('/api', server.getExpressRouter());

// 或作为 MCP Server 启动
await server.startMCP({ name: 'my-server', transport: 'stdio' });

执行上下文（Execution Context）

可在处理器中识别当前调用接口：

handler: async (args, context) => {
  if (context.interface === 'cli') {
    // CLI 专属逻辑
  } else if (context.interface === 'api') {
    const userId = context.request.headers.get('x-user-id');
  }
  return result;
}

测试

只需编写一次测试，即可覆盖所有接口：

import { userCreate } from './user-create';

test('creates user', async () => {
  const result = await userCreate.execute(
    { name: 'Alice', email: 'alice@example.com' },
    { interface: 'test' }
  );
  expect(result.name).toBe('Alice');
});

架构图

┌─────────────────────────────────────────┐
│      UniversalCommand Definition        │
│  name, description, input, handler      │
└────────────────┬────────────────────────┘
                 │
        ┌────────┼────────┐
        ▼        ▼        ▼
     ┌─────┐  ┌─────┐  ┌─────┐
     │ CLI │  │ API │  │ MCP │
     └─────┘  └─────┘  └─────┘

适用场景

✅ 构建任意新的 Supernal 命令或工具
✅ 为现有业务逻辑添加 CLI 接口
✅ 向 AI agent（通过 MCP）暴露功能
✅ 构建具备一致规范的 REST API

❌ 简单的一次性脚本（过度设计）
❌ 第三方集成（已有其自身约定）

与 sc 和 si 的集成

sc（supernal-coding）和 si（supernal-interface）均在底层使用 universal-command。当向这两个工具新增命令时，请统一以 UniversalCommand 形式定义。

API 参考

class UniversalCommand {
  execute(args: TInput, context: ExecutionContext): Promise;
  toCLI(): Command;           // Commander.js Command
  toNextAPI(): NextAPIRoute;  // Next.js route handler
  toExpressAPI(): ExpressRoute;
  toMCP(): MCPToolDefinition;
  validateArgs(args: unknown): ValidationResult;
}

class CommandRegistry {
  register(command: UniversalCommand): void;
  getAll(): UniversalCommand[];
}

function createRuntimeServer(): RuntimeServer;
function generateNextRoutes(registry: CommandRegistry, options: CodegenOptions): Promise;
function createMCPServer(registry: CommandRegistry, options: MCPOptions): MCPServer;

源码

• 包名：@supernal/universal-command
• npm 页面：https://www.npmjs.com/package/@supernal/universal-command

切勿重复实现该模式 —— 请直接使用！